Starea comenzii · Nexus Gateway

Primește progresul prin webhook-uri semnate. Folosește GET cu aceeași conexiune și același ID extern pentru reconcilierea stării curente din Retail după întreruperi sau actualizări lipsă. Separă progresul clientului de starea trimiterii și a plății.

Citește progresul

curl --fail-with-body "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

{
  "external_order_id": "shop-1001",
  "status": "accepted",
  "total": 3700,
  "currency": "RON"
}

Transformă starea într-un mesaj pentru client

Stare	Mesaj sugerat pentru client	Finală?
`pending_acceptance`	Comandă primită. Așteptăm confirmarea restaurantului.	Nu
`accepted`	Restaurantul a acceptat comanda.	Nu
`preparing`	Comanda ta este în curs de pregătire.	Nu
`ready`	Comanda este pregătită pentru ridicare sau expediere.	Nu
`out_for_delivery`	Comanda ta este pe drum.	Nu
`completed`	Comanda ta este finalizată.	Da
`rejected`	Restaurantul nu a putut accepta comanda.	Da
`cancelled`	Comanda ta a fost anulată.	Da

Progresul depinde de fluxul restaurantului. Nici observarea pentru webhook-uri, nici citirea periodică nu garantează fiecare stare intermediară. Ridicarea nu necesită etapa de livrare. Nu impune apariția tuturor stărilor în ordine. Programarea, estimările, motivele, progresul livrării și rezumatele rambursărilor sunt descrise mai jos; acestea nu verifică plata și nu oferă localizarea curierului în timp real.

Alternativa prin citire periodică

Cu un receptor webhook funcțional, nu ai nevoie de citire periodică permanentă. Dacă webhook-urile nu sunt configurate sau sunt temporar indisponibile, o politică inițială este o citire din backend la 5–10 secunde cât timp clientul urmărește activ o comandă nefinalizată, mai rar în perioadele inactive. Stabilește limitele de trafic cu Nexus; acesta nu este un interval garantat al serviciului. Revino la actualizări webhook după recuperare și folosește GET pentru reconcilierea lipsurilor.

Folosește un singur flux de citire per conexiune/comandă, comun sesiunilor clienților.
Citește ultima stare și salvează ultimul rezultat obținut cu succes.
Oprește citirile la completed, rejected sau cancelled.
La erori temporare, mărește intervalul cu o variație aleatorie și respectă Retry-After. Afișează „actualizare temporar indisponibilă”, fără a inventa o respingere.

Când starea nu este disponibilă

404 order_not_found înseamnă că gateway-ul nu are o rezervare pentru acel ID în conexiunea respectivă. Verifică ID-ul și conexiunea. Pentru o trimitere nerezolvată, retrimite același ID și corp salvate, fără a crea o achiziție înlocuitoare.

O rezervare din gateway a cărei stare din sistemul destinație nu poate fi încă confirmată poate întoarce 503. Citirea stării nu trimite o comandă și nu repară o trimitere neconfirmată; pentru aceasta, repetă POST-ul inițial.

Păstrează comenzile cu rezultat incert vizibile echipei operaționale când reîncercările depășesc intervalul ales. Gateway-ul nu reîncearcă în locul tău trimiterile de comenzi cu rezultat incert și nu garantează expirarea lor automată. Livrarea webhook-urilor are propriul proces de reîncercare în fundal; acesta nu repară o trimitere neconfirmată.

Estimări și rezultate raportate

scheduled_for păstrează intervalul solicitat; estimated_ready_at este stabilit la acceptare. reason oferă motivul disponibil de respingere/anulare. Obiectul opțional delivery include alocarea/progresul și estimările ridicării/livrării, fără contactele curierului. Obiectul opțional refund rezumă rambursările raportate de website; nu verifică plata și nu inversează un bon. Aceste câmpuri pot fi null. Consultă referința schemei pentru contractele complete.