API-ul magazinului
versiunea 1.0.0Cu API-ul magazinului, site-ul de comenzi al unui restaurant citește meniul, cere prețul coșului, plasează comanda și deschide contul clientului. Site-ul poate fi scris în orice limbaj și orice framework, sau poate fi o aplicație mobilă cu server propriu.
- Adresa:
https://api.edin.ro - Referința completă: referinta.html
- Documentul OpenAPI 3.1: openapi.json
- Pentru asistenți AI: llms.txt, llms-full.txt și skill-ul SKILL.md
Cheia magazinului
Fiecare cerere are cheia magazinului în antetul Authorization:
GET /storefront/locations HTTP/1.1
Host: api.edin.ro
Authorization: Bearer <cheia magazinului>
Cheia o creează firma în Operations Hub, la Setări → Chei pentru site, după ce Edin îi permite să emită chei. Cheia se vede întreagă o singură dată, la creare. Firma și punctele de lucru ale comenzii se stabilesc după cheie: un identificator de firmă trimis în cerere este ignorat.
Cheia se păstrează numai pe serverul site-ului. Nu o pune în codul care rulează în browser și nu o trimite
vizitatorului. Browserul trimite cererile la serverul site-ului, iar serverul site-ului apelează API-ul.
O cerere cu antetul Origin (din browser) este acceptată numai de pe domeniile configurate pentru cheie.
Trimite IP-ul vizitatorului în X-Forwarded-For. Limitele de cereri se aplică pe cheie și pe
acest IP. Fără acest antet, toți vizitatorii site-ului împart aceeași limită.
Comanda, pas cu pas
- Punctele de lucru.
GET /storefront/locationsîntoarce punctele de lucru la care are acces cheia, cu programul, ridicarea din local (pickup), comenzile programate (scheduling) și metodele de plată (paymentMethods).id-ul unui punct de lucru estelocationIdîn pașii următori. - Meniul.
GET /storefront/menu?location=<id>întoarce categoriile, produsele, opțiunile, meniurile combo și promoțiile automate. Un produs cuavailable: falsenu se poate comanda acum, iarunavailableReasonspune de ce. - Intervalele, pentru o comandă programată.
GET /storefront/slots?location=<id>întoarce zilele și intervalele de 15 minute. Începutul unui interval liber se trimite înscheduledFor. FărăscheduledFor, comanda se pregătește cât mai curând. - Adresa.
POST /storefront/address-checkspune dacă adresa este într-o zonă de livrare (delivers), în afara zonelor (outside_zones) sau negăsită pe hartă (not_found). Ladelivers, răspunsul are punctul pe hartă (point), taxa de livrare și comanda minimă. Păstreazăpointpentru pașii următori. - Prețul coșului.
POST /storefront/quoteprimește liniile coșului, fără prețuri, și întoarce prețul fiecărei linii, reducerile, taxa de livrare, TVA-ul și totalul. Dacăorderableestefalse,refusalsspune de ce nu se poate plasa comanda (closed,below_minimum,outside_zones,address_requiredși celelalte), iar o linie cuproblemnu se adună la total. - Comanda.
POST /storefront/ordersplasează comanda. Alege oidempotencyKeyo dată pe coș și trimite-o la fiecare încercare: o cerere cu aceeași cheie primește aceeași comandă, deci o reîncercare după o eroare de rețea nu creează o a doua comandă. Răspunsul are comanda,accessTokenși, la plata online,paymentUrl, unde trimiți clientul să plătească. - Pagina comenzii.
GET /storefront/orders/{id}?token=<accessToken>întoarce starea comenzii. PuneaccessTokenîn linkul paginii comenzii, ca clientul să o poată deschide fără cont. O comandă programată se poate anula cuPOST /storefront/orders/{id}/cancel, până la ora limită.
Comanda trece prin stările din status: awaiting_payment (așteaptă plata online),
awaiting_dispatch (așteaptă acceptarea), scheduled (programată), sent_to_kitchen (acceptată și
trimisă la bucătărie), rejected (respinsă de restaurant), expired (neplătită la timp) și
cancelled (anulată).
Prețul îl calculează serverul
Site-ul nu calculează prețuri, reduceri sau TVA. Afișează sumele din quote, iar la plasare
serverul calculează din nou prețul și ignoră orice sumă din cerere. Dacă între quote și plasare
s-a schimbat ceva (un produs s-a terminat, un cod de reducere a expirat), cererea de plasare primește
409, cu motivul în error.details.reason și prețul actual în error.details.quote. Arată clientului noul preț și lasă-l să
confirme din nou.
Contul clientului
Clientul intră în cont cu un cod primit prin SMS sau prin e-mail:
POST /storefront/account/codetrimite codul prin SMS (channel:phone) sau prin e-mail (channel:email), la numărul sau adresa dindestination.POST /storefront/account/code/verifyverifică codul și întoarce sesiunea:token,expiresAtși contul.
Sau cu o platformă: GET /storefront/auth/providers întoarce platformele activate de firmă, iar
POST /storefront/auth/{provider} verifică tokenul primit de la platformă și deschide sesiunea
clientului.
Trimite token în antetul X-Storefront-Session, împreună cu cheia magazinului, la rutele contului
(/storefront/account/...). Păstrează-l pe serverul site-ului, de exemplu într-un cookie
HttpOnly. La quote și la plasarea comenzii, sesiunea este opțională. Cu sesiune, comanda se
salvează în contul clientului și primește prețurile grupului lui. Dacă sesiunea a expirat sau a fost
închisă, răspunsul este 401, cu error.code STOREFRONT_SESSION_INVALID. Scoate atunci clientul din cont.
Banii
O sumă este un obiect cu valoarea zecimală, ca text, și moneda:
{ "amount": "58.50", "currency": "RON" }
Valoarea are mereu două zecimale. Prețurile din meniu sunt cu TVA inclus. Afișează sumele așa cum
vin și nu face calcule cu ele pe site: totalul, TVA-ul și reducerile le calculează serverul, în quote. În cereri
(de exemplu productsTotal la address-check), o sumă se trimite ca text, cu cel mult două
zecimale: "58.50".
Erorile
Un răspuns de eroare are forma:
{
"success": false,
"error": {
"statusCode": 409,
"code": "STOREFRONT_ORDER_REFUSED",
"message": "The order cannot be placed",
"error": "Conflict",
"details": { "code": "STOREFRONT_ORDER_REFUSED", "reason": "not_orderable", "quote": { "…": "…" } },
"timestamp": "2026-11-20T12:00:00.000Z",
"path": "/storefront/orders",
"requestId": "…"
}
}
error.code este stabil și se citește de program. error.message este pentru dezvoltator, în
engleză. error.details are ce ține de eroare: câmpurile greșite în fieldErrors (la 400,
INVALID_PAYLOAD), motivul în reason și prețul actual în quote (la 409,
STOREFRONT_ORDER_REFUSED). Trimite error.requestId când ceri ajutor pentru o eroare.
| Cod HTTP | Când |
|---|---|
400 | Cererea nu respectă schema (câmp lipsă, valoare în afara limitelor). |
401 | Cheia lipsește sau nu este validă (STOREFRONT_KEY_INVALID). Sesiunea clientului lipsește sau a expirat (STOREFRONT_SESSION_INVALID). |
404 | Punctul de lucru nu este al cheii, comanda nu există sau linkul comenzii nu este valid. |
409 | Comanda nu se poate plasa așa cum este (vezi reason) sau idempotencyKey a fost folosită pentru alt coș. |
429 | Prea multe cereri. Reîncearcă după numărul de secunde din Retry-After. |
Limitele
| Ce se numără | Limita |
|---|---|
| Cererile unei chei | 1200 pe minut |
Cererile unui vizitator (IP din X-Forwarded-For) | 120 pe minut |
| Codurile de intrare în cont cerute de un vizitator | 10 la 15 minute |
| Codurile încercate de un vizitator | 30 la 15 minute |
| Firmele căutate după CUI de un vizitator | 20 pe minut |
Versiunea
Versiunea API-ului este în info.version din openapi.json. Rutele nu au prefix de
versiune. API-ul se schimbă numai prin adăugare:
- Câmpuri noi în răspunsuri. Clientul trebuie să ignore câmpurile pe care nu le cunoaște.
- Câmpuri opționale noi în cereri și rute noi.
- Valori noi numai în enumurile marcate
x-extensible-enum.
Un câmp sau o rută care se retrage rămâne funcțională și este marcată deprecated.
Tipurile pentru TypeScript
Tipurile TypeScript pentru codul site-ului se generează din documentul OpenAPI:
npx openapi-typescript https://<adresa documentației>/openapi.json -o edin-storefront.ts