edin. API-ul magazinului

API-ul magazinului

versiunea 1.0.0

Cu 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.

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

  1. 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 este locationId în pașii următori.
  2. Meniul. GET /storefront/menu?location=<id> întoarce categoriile, produsele, opțiunile, meniurile combo și promoțiile automate. Un produs cu available: false nu se poate comanda acum, iar unavailableReason spune de ce.
  3. Intervalele, pentru o comandă programată. GET /storefront/slots?location=<id> întoarce zilele și intervalele de 15 minute. Începutul unui interval liber se trimite în scheduledFor. Fără scheduledFor, comanda se pregătește cât mai curând.
  4. Adresa. POST /storefront/address-check spune dacă adresa este într-o zonă de livrare (delivers), în afara zonelor (outside_zones) sau negăsită pe hartă (not_found). La delivers, răspunsul are punctul pe hartă (point), taxa de livrare și comanda minimă. Păstrează point pentru pașii următori.
  5. Prețul coșului. POST /storefront/quote primește liniile coșului, fără prețuri, și întoarce prețul fiecărei linii, reducerile, taxa de livrare, TVA-ul și totalul. Dacă orderable este false, refusals spune de ce nu se poate plasa comanda (closed, below_minimum, outside_zones, address_required și celelalte), iar o linie cu problem nu se adună la total.
  6. Comanda. POST /storefront/orders plasează comanda. Alege o idempotencyKey o 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ă.
  7. Pagina comenzii. GET /storefront/orders/{id}?token=<accessToken> întoarce starea comenzii. Pune accessToken în linkul paginii comenzii, ca clientul să o poată deschide fără cont. O comandă programată se poate anula cu POST /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:

  1. POST /storefront/account/code trimite codul prin SMS (channel: phone) sau prin e-mail (channel: email), la numărul sau adresa din destination.
  2. POST /storefront/account/code/verify verifică 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 HTTPCând
400Cererea nu respectă schema (câmp lipsă, valoare în afara limitelor).
401Cheia lipsește sau nu este validă (STOREFRONT_KEY_INVALID). Sesiunea clientului lipsește sau a expirat (STOREFRONT_SESSION_INVALID).
404Punctul de lucru nu este al cheii, comanda nu există sau linkul comenzii nu este valid.
409Comanda nu se poate plasa așa cum este (vezi reason) sau idempotencyKey a fost folosită pentru alt coș.
429Prea multe cereri. Reîncearcă după numărul de secunde din Retry-After.

Limitele

Ce se numărăLimita
Cererile unei chei1200 pe minut
Cererile unui vizitator (IP din X-Forwarded-For)120 pe minut
Codurile de intrare în cont cerute de un vizitator10 la 15 minute
Codurile încercate de un vizitator30 la 15 minute
Firmele căutate după CUI de un vizitator20 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:

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