Trimitere comenzi prin API

Documentație pentru sistemul de gestiune, site-ul sau aplicația restaurantului. Dacă ai primit o cheie de acces, ești în locul potrivit.

Autentificare

Fiecare restaurant are o cheie proprie. Se trimite în antetul X-API-Key la fiecare cerere. Cheia se vede în portal, la Setări, sau se cere de la dispecerat.

Trimiterea unei comenzi

POST https://europe-west1-lexina-delivery.cloudfunctions.net/apiComanda

# Exemplu cu curl
curl -X POST https://europe-west1-lexina-delivery.cloudfunctions.net/apiComanda \
  -H "X-API-Key: lxk_cheia_ta" \
  -H "Content-Type: application/json" \
  -d '{
    "idExtern": "BON-10432",
    "sursa": "telefonic",
    "zona": "Brașov",
    "client": {
      "nume": "Maria Popescu",
      "telefon": "0722123456",
      "adresa": "Str. Lungă 24, bl. 3, ap. 12"
    },
    "linii": [
      { "nume": "Pizza Diavola", "pret": 42.00, "cantitate": 2 },
      { "nume": "Coca-Cola 0.5", "pret": 9.00, "cantitate": 1 }
    ],
    "taxaLivrare": 9.00,
    "metodaPlata": "cash",
    "observatii": "Interfonul nu merge, sunați la telefon",
    "esteGata": false
  }'

Câmpuri

Câmp	Descriere
client.nume obligatoriu	Numele clientului, minimum 3 caractere.
client.telefon obligatoriu	10 cifre, începe cu 07, 02 sau 03.
client.adresa obligatoriu	Stradă, număr și detalii. Minimum 8 caractere — curierul trebuie să găsească.
linii	Lista de produse: nume, pret, cantitate. Valoarea comenzii se calculează din ele. Curierul le vede pe telefon și poate verifica punga.
valoareMancare	Alternativă la linii, dacă sistemul tău nu trimite produsele. Suma totală a mâncării.
taxaLivrare	Taxa pe care o încasezi de la client. Rămâne a ta.
zona	Numele localității de livrare, ex. Brașov, Săcele. Dacă lipsește, se folosește zona implicită setată pe restaurant.
metodaPlata	cash sau card. La card, curierul nu încasează nimic.
idExtern	Numărul comenzii din sistemul tău. Recomandat: dacă retrimiți aceeași comandă, nu se dublează.
sursa	De unde vine: telefonic, site, glovo, wolt, bolt. Apare în rapoarte.
observatii	Text liber pentru curier.
esteGata	true dacă mâncarea e deja pregătită. Curierii văd eticheta și vin direct.

Răspuns

{
  "comandaId": "aBcD1234...",
  "status": "asteptare",
  "zona": "Brașov",
  "total": 102.00
}

Cod 201 la creare. Dacă retrimiți o comandă cu același idExtern, primești 200 și "duplicat": true, fără să se creeze una nouă.

Erori

Cod	Ce înseamnă
401	Cheie lipsă sau greșită.
400	Date invalide — mesajul spune exact care câmp.
403	Cont dezactivat.
500	Eroare la noi. Reîncearcă peste câteva secunde.

Verificarea stării

GET .../apiStareComanda?comandaId=... sau ?idExtern=..., cu același antet.

{
  "comandaId": "aBcD1234...",
  "status": "spre_client",
  "curier": "Andrei M.",
  "esteGata": true,
  "livratLa": null
}

Stările posibile: asteptare, preluat, la_restaurant, spre_client, livrat, anulat.

Notificări automate (webhook)

În loc să întrebi periodic ce s-a întâmplat cu o comandă, îți trimitem noi un mesaj de fiecare dată când starea ei se schimbă. Ne dai o adresă https:// din sistemul tău, iar noi facem POST pe ea la fiecare schimbare — de la „caută curier" până la „livrată".

Adresa se setează de noi, din panoul de administrare: ne-o trimiți odată cu cheia de API. Primești atunci și un secret de semnătură (începe cu lws_), afișat o singură dată.

Ce primești

POST https://sistemul-tau.ro/lexina-stare
Content-Type: application/json
X-Lexina-Eveniment: stare_comanda
X-Lexina-Semnatura: 9f2c...   // HMAC-SHA256 al corpului

{
  "eveniment": "stare_comanda",
  "comandaId": "aBcD1234...",
  "idExtern": "BON-8841",
  "sursa": "api",
  "status": "livrat",
  "statusEticheta": "Livrată",
  "restaurant": { "id": "rest_x", "nume": "Habul" },
  "curier": { "nume": "Andrei M.", "telefon": "07XXXXXXXX" },
  "client": { "nume": "Ioana P.", "telefon": "07XXXXXXXX", "adresa": "Str. Lungă 12, Brașov" },
  "zona": "Brașov oraș",
  "sume": { "mancare": 84.5, "livrare": 15, "total": 99.5 },
  "metodaPlata": "cash",
  "incident": null,
  "timp": {
    "creata":     "2026-09-25T17:02:11.000Z",
    "confirmata": "2026-09-25T17:03:40.000Z",
    "preluata":   "2026-09-25T17:09:02.000Z",
    "laClient":   "2026-09-25T17:24:55.000Z",
    "livrata":    "2026-09-25T17:26:10.000Z"
  },
  "trimisLa": "2026-09-25T17:26:11.412Z"
}

curier este null cât timp nimeni n-a preluat comanda. Câmpurile din timp sunt null până se întâmplă momentul respectiv. Valorile posibile pentru status sunt aceleași ca la verificarea stării, plus neconfirmat, retur, returnat, de_ridicat și livrare_restaurant. statusEticheta e același lucru scris în română, gata de afișat pe bon sau pe ecran.

Verificarea semnăturii

Oricine îți poate trimite un POST pe acea adresă. Ca să știi că mesajul chiar vine de la noi, calculezi HMAC-SHA256 peste corpul brut al cererii, cu secretul tău, și compari rezultatul cu antetul X-Lexina-Semnatura.

// Node.js
const semnatura = crypto.createHmac("sha256", SECRET)
  .update(corpBrut)            // exact octeții primiți, nu JSON reserializat
  .digest("hex");
if (semnatura !== req.headers["x-lexina-semnatura"]) return res.sendStatus(401);

// PHP
$semnatura = hash_hmac('sha256', $corpBrut, $SECRET);
if (!hash_equals($semnatura, $_SERVER['HTTP_X_LEXINA_SEMNATURA'])) { http_response_code(401); exit; }

Ce așteptăm de la serverul tău

• Răspunde cu 200 imediat ce ai primit mesajul. Procesarea o faci după.
• Ai 10 secunde să răspunzi. Peste atât considerăm că n-a ajuns.
• Dacă nu răspunzi sau dai eroare de server, reîncercăm de 3 ori (la 2 și la 4 secunde). La 400–499 nu reîncercăm: înseamnă că cererea nu ți-a plăcut.
• Un mesaj poate ajunge de două ori. Folosește comandaId + status ca să nu prelucrezi de două ori același eveniment.
• Adresa trebuie să fie publică și pe https. Adresele interne (localhost, 192.168.…) sunt respinse la salvare.

Recomandări practice

• Trimite idExtern întotdeauna. La o eroare de rețea vei reîncerca, iar fără el ai risca să dublezi comanda.
• Trimite produsele în linii, nu doar suma. Curierul verifică punga la restaurant, nu la ușa clientului.
• Trimite comanda când e confirmată, nu când e doar plasată. Odată trimisă, un curier poate porni spre tine.
• Marchează esteGata abia când mâncarea chiar e făcută. E semnalul după care curierii aleg comenzile.