Comenzi și plăți

O comandă conține coșul cu totalul calculat, propriul ID al comenzii, datele de contact ale clientului și modul de plată. ID-ul conexiunii din URL stabilește locația care o primește.

Construiește cererea

Trimite JSON cu Content-Type: application/json. Limita corpului cererii este 4 MiB. Câmpurile necunoscute sunt respinse. Vezi referința schemei pentru toate limitele și valorile implicite.

Ridicare sau livrare

Ridicare: setează fulfillment: "pickup", omite address sau trimite null și nu adăuga taxă de livrare.

Livrare: setează fulfillment: "delivery", completează address.city și address.street, adaugă opțional address.details și include o singură dată taxa fixă de livrare din meniu. Zonele de livrare și eligibilitatea adresei rămân în responsabilitatea website-ului/restaurantului; API-ul nu calculează un tarif de livrare și nu rezervă un curier.

Declară cum se încasează plata

Toate comenzile Website sunt tratate ca achitate în Retail, inclusiv cele cu numerar sau card la primire. Trimite metoda reală de plată: cash_on_fulfillment corespunde metodei Cash, card_on_fulfillment metodei CardPOS, iar paid_online metodei ModernPayment. Nu este necesar un câmp separat achitat/neachitat. Acceptarea înregistrează bonul cu metoda respectivă, fără încă o etapă de încasare în Register sau debitarea terminalului. Această convenție Retail nu dovedește plata clientului: site-ul, restaurantul sau curierul rămâne responsabil pentru încasarea efectivă. Starea comenzii descrie pregătirea și livrarea.

Gestionează separat plata și rezultatul comenzii

O plată încasată nu garantează că restaurantul va accepta comanda. Stabilește modul de tratare a respingerilor, anulărilor și rambursărilor și comunică-l clienților. Încasarea, anularea tranzacțiilor și rambursările rămân la procesatorul tău; folosește endpointul de raportare a rambursărilor pentru a înregistra rezultatul final în Nexus.

După expirarea timpului de răspuns, păstrează referința inițială de plată și corpul comenzii. Nu încasa din nou și nu genera alt ID de comandă pentru recuperare. Rezolvă trimiterea folosind protocolul de reîncercare.

Interpretează corect răspunsul

• 201 Created: restaurantul a primit comanda. Starea rămâne pending_acceptance până când personalul o acceptă sau o respinge.
• 200 OK: retrimiterea identică finalizată întoarce confirmarea inițială de primire.
• 503 sau expirarea timpului de răspuns: nu știi dacă restaurantul a primit comanda. Retrimite aceeași cerere; nu crea niciodată un ID nou.

După confirmarea primirii, urmărește progresul prin webhook-uri. Folosește GET /v1/connections/{connection_id}/orders/{external_order_id} pentru reconcilierea stării după notificări pierdute sau când webhook-urile nu sunt disponibile. Nu repeta POST pentru a citi progresul.

Exemple complete de cereri

{
  "external_order_id": "shop-1001",
  "menu_revision": "example-menu-1",
  "currency": "RON",
  "fulfillment": "pickup",
  "customer": {
    "name": "Example Customer",
    "phone": "0700000000"
  },
  "payment": {
    "method": "paid_online",
    "reference": "payment-example-1001"
  },
  "items": [
    {
      "product_id": "pizza-margherita",
      "quantity": 1,
      "modifiers": [
        {
          "group_id": "pizza-extras",
          "option_id": "cheese"
        }
      ],
      "notes": "Please slice the pizza"
    }
  ],
  "total": 3700,
  "notes": "Pickup by Alex"
}

{
  "external_order_id": "shop-1002",
  "menu_revision": "example-menu-1",
  "currency": "RON",
  "fulfillment": "delivery",
  "customer": {
    "name": "Example Customer",
    "phone": "0700000000"
  },
  "address": {
    "city": "Iași",
    "street": "Example Street 10",
    "details": "Apartment 2, ring the bell"
  },
  "payment": {
    "method": "cash_on_fulfillment"
  },
  "items": [
    {
      "product_id": "burger-meal",
      "quantity": 2,
      "modifiers": [
        {
          "group_id": "size",
          "option_id": "large"
        },
        {
          "group_id": "drink",
          "option_id": "water"
        },
        {
          "group_id": "meal-extras",
          "option_id": "sauce"
        }
      ]
    }
  ],
  "total": 7400
}

Onorare programată

Comenzile programate sunt acceptate implicit (scheduling.enabled este true). Trimite scheduled_for ca marcaj temporal ISO 8601 cu offset explicit. Omite-l pentru onorare imediată. Nu există o anticipare minimă sau un termen maxim de programare; website-ul stabilește ora solicitată. Gateway-ul verifică programul locației, excepțiile de sărbători și programul produselor la ora cerută, iar stocul și pauzele manuale la trimitere. Un meniu închis acum poate accepta o oră viitoare validă.

Comanda așteaptă în continuare acceptarea de către personal. La acceptare se înregistrează estimated_ready_at; dacă personalul acceptă târziu, estimarea poate depăși ora cerută. Urmărește estimarea returnată și nu promite ora cerută ca garanție. Reîncercarea unei comenzi deja rezervate păstrează ora și prețurile inițiale, chiar dacă fereastra de programare s-a schimbat.

Pentru o oră programată, citește GET /v1/connections/{connection_id}/menu?fulfillment_at=2026-12-25T12%3A00%3A00%2B02%3A00 folosind o oră din fereastra curentă de programare. Codifică offsetul în URL. Indicatorii returnați reflectă ora aleasă, iar stocul și pauzele manuale rămân cele curente. Trimite același moment drept scheduled_for în comandă.

Anulare de către client

Apelează POST /v1/connections/{connection_id}/orders/{external_order_id}/cancel cu {"request_id":"cancel-123","reason":"customer_request"}. Motivele sunt customer_request, duplicate, ordered_by_mistake sau other. Salvează ID-ul și corpul cererii înainte de trimitere; reîncearcă fără modificări după timeout sau 503.

Comenzile imediate pot fi anulate înainte de acceptare. Comenzile programate acceptate pot fi anulate strict înainte de momentul salvat pentru începerea preparării, doar cât timp așteaptă prepararea. La sau după acel moment, ori după începerea preparării, cere restaurantului să aprobe anularea în Retail. Comenzile finalizate nu pot fi anulate. Retrimite cererea identică după timeout sau 503; 409 cancellation_not_allowed înseamnă că nu mai este eligibilă. Bonurile existente rămân pentru reconciliere în Nexus ERP, iar rambursarea plății online rămâne responsabilitatea website-ului.

Curierul și progresul livrării

Pentru comenzile cu livrare, apelează POST /v1/connections/{connection_id}/orders/{external_order_id}/delivery cu {"request_id":"courier-1","status":"assigned","courier_name":"Curier exemplu"}. Alocă un curier după acceptare; opțional, raportează arrived. Raportează picked_up doar după ce restaurantul marchează comanda ca pregătită, apoi delivered. Aceste acțiuni actualizează starea livrării în Retail fără încasarea plății.

Câmpurile opționale courier_phone, estimated_pickup_at și estimated_delivery_at ajută la coordonarea predării. Estimările necesită un offset explicit. Valorile omise păstrează datele anterioare. Contactele curierului sunt vizibile personalului, dar excluse din starea publică și webhook-uri. Folosește un ID nou pentru fiecare modificare, maximum 100 per comandă; reîncearcă aceleași ID-uri și corpuri după un rezultat incert. Reîncercările întorc progresul curent, fără revenirea la o stare anterioară.

Bonurile de bucătărie pentru comenzile programate se tipăresc la acceptare, cu ora programată. Ecranul Kitchen reține comanda până la momentul începerii preparării.

Raportează rambursările efectuate de procesator

După ce procesatorul returnează un rezultat final, apelează POST /v1/connections/{connection_id}/orders/{external_order_id}/refunds cu {"request_id":"refund-1","processor_reference":"provider-refund-1","outcome":"succeeded","amount":1200}. Rezultatele sunt succeeded sau failed. Folosește o referință unică a procesatorului per comandă și un ID stabil al cererii; reîncercările repetă același corp. O rambursare eșuată este finală pentru acea referință; o nouă încercare folosește ID-uri noi. Doar comenzile paid_online sunt eligibile, inclusiv cele finalizate, respinse sau anulate. Maximum 100 de rapoarte sunt păstrate per comandă, iar sumele reușite nu pot depăși totalul inițial.

Endpointul înregistrează declarația ta. Nexus nu contactează procesatorul, nu transferă bani, nu verifică reușita, nu anulează comanda și nu inversează bonul fiscal. Stabilește cu restaurantul reconcilierea fiscală necesară. Starea expune refund.reported_refunded_amount, suma rambursărilor reușite raportate. Referințele procesatorului sunt excluse din stare și webhook-uri.