Referință API · Nexus Gateway

Explorează contractul exact al acestui gateway. Tipurile, restricțiile și exemplele de mai jos provin din schema sa OpenAPI.

Folosește cheia website. Publicarea meniurilor folosește o credențială separată de operator. Exemplele sunt fictive; această pagină nu trimite cereri.

Download OpenAPI 3.1 ↗

GET/health

Verifică dacă procesul rulează

Autentificare: Fără autentificare

Întoarce 200 cât timp procesul gateway rulează. Nu necesită cheie. Nu verifică meniurile sau sistemele restaurantului.

Răspunsuri

200

Procesul gateway rulează.

object

Cerere

cURL

curl "https://website.api.pionier.ro/health"

Răspuns

200

Fără conținut

GET/v1/connections

Descoperă punctele de vânzare activate

Autentificare: WebsiteKey

Listează locațiile și casele de marcat care pot primi comenzi cu cheia website. Folosește ID-ul unei conexiuni în fiecare cerere pentru meniu, comandă și stare, chiar dacă există o singură conexiune. O listă goală înseamnă că restaurantul nu a activat încă comenzile website.

Răspunsuri

200

Conexiunile activate pentru cheia website.

ConnectionList

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl "https://website.api.pionier.ro/v1/connections" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

200

Fără conținut

401

{
  "detail": "invalid_credentials"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/connections/{connection_id}/menu

Citește meniul restaurantului

Autentificare: WebsiteKey

Întoarce meniul publicat pentru această conexiune. Sumele sunt în bani întregi. Trimite revizia și ID-urile din acest meniu în comandă. Disponibilitatea și accepting_orders se pot schimba fără o revizie nouă, deci preia meniul din nou chiar înainte de finalizarea comenzii.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

fulfillment_atstring | nullqueryopțional

Răspunsuri

200

Meniul publicat pentru această conexiune.

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/menu" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

200

{
  "revision": "example-menu-1",
  "currency": "RON",
  "accepting_orders": true,
  "fulfillment": [
    "pickup",
    "delivery"
  ],
  "delivery_fee": 700,
  "categories": [
    {
      "id": "pizzas",
      "name": "Pizza"
    },
    {
      "id": "meals",
      "name": "Meals"
    }
  ],
  "products": [
    {
      "id": "pizza-margherita",
      "category_id": "pizzas",
      "name": "Margherita",
      "description": "Tomato, mozzarella and basil",
      "image_url": "https://images.example.test/margherita.jpg",
      "translations": {
        "en": {
          "name": "Margherita",
          "description": "Tomato, mozzarella and basil"
        },
        "ro": {
          "name": "Margherita",
          "description": "Roșii, mozzarella și busuioc"
        }
      },
      "price": 3200,
      "packaging": 100,
      "packaging_product_id": "pizza-box",
      "modifier_groups": [
        {
          "id": "pizza-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "cheese",
              "name": "Extra cheese",
              "price": 400
            }
          ]
        }
      ]
    },
    {
      "id": "burger-meal",
      "category_id": "meals",
      "name": "Burger meal",
      "description": "Burger, fries and your choice of drink",
      "translations": {
        "en": {
          "name": "Burger meal",
          "description": "Burger, fries and your choice of drink"
        },
        "ro": {
          "name": "Meniu burger",
          "description": "Burger, cartofi prăjiți și băutură la alegere"
        }
      },
      "price": 2500,
      "packaging": 100,
      "packaging_product_id": "meal-bag",
      "modifier_groups": [
        {
          "id": "size",
          "name": "Size",
          "kind": "variant",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "regular",
              "name": "Regular",
              "price": 0
            },
            {
              "id": "large",
              "name": "Large",
              "price": 0
            }
          ]
        },
        {
          "id": "drink",
          "name": "Drink",
          "kind": "bundle",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "water",
              "name": "Water",
              "price": 0,
              "deposit": 50
            }
          ]
        },
        {
          "id": "meal-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "sauce",
              "name": "Extra sauce",
              "price": 200
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "meal-regular",
          "selections": [
            {
              "group_id": "size",
              "option_id": "regular"
            }
          ],
          "price": 2500
        },
        {
          "id": "meal-large",
          "selections": [
            {
              "group_id": "size",
              "option_id": "large"
            }
          ],
          "price": 3000
        }
      ]
    }
  ]
}

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "menu_not_published"
}

409

{
  "error": "scheduled_time_unavailable"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

PUT/v1/menu

Publică un meniu complet

Autentificare: PublisherKey

Folosit de Nexus Retail cu o cheie de publicare; integrările website nu îl apelează niciodată. Reviziile sunt imuabile. Include generația pozitivă obligatorie X-Website-Publication. O reîncercare identică cu aceeași generație este idempotentă dacă nu a sosit o generație mai nouă; generațiile învechite sau conținutul modificat sub aceeași generație întorc 409 publication_superseded.

Parametri

x-website-publicationintegerheaderobligatoriu

min: 1 · max: 9223372036854775807

Corpul cererii application/json

Schemă: Menu

revisionstringobligatoriu

Versiunea meniului publicat. Trimite-o ca menu_revision. Disponibilitatea și accepting_orders se pot schimba fără o revizie nouă.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

currencystringopțional

Întotdeauna RON. Sumele sunt în bani întregi.

implicit: "RON" · valoare: "RON"

accepting_ordersbooleanopțional

False când restaurantul este în pauză sau închis. Continuă să afișezi meniul, dar dezactivează finalizarea comenzii.

implicit: true

opening_hoursOpeningHours | nullopțional

Programul curent și excepțiile restaurantului în fusul său orar. Null dacă nu există politică configurată.

schedulingSchedulingPolicyopțional

Comenzile programate sunt acceptate întotdeauna; durata implicită de preparare stabilește momentul începerii în bucătărie.

fulfillmentarray<string>obligatoriu

Include întotdeauna ridicare și livrare.

minimum de elemente: 1 · maximum de elemente: 2

delivery_feeintegeropțional

Taxă fixă în bani, aplicată o singură dată per comandă cu livrare, niciodată pentru ridicare.

min: 0.0 · max: 100000000.0 · implicit: 0

tips_enabledbooleanopțional

Indică dacă pot fi incluse bacșișuri pentru personalul restaurantului. Necesită configurarea bacșișului în POS; bacșișurile curierului nu sunt incluse.

implicit: false

categoriesarray<Category>obligatoriu

Secțiunile meniului.

minimum de elemente: 1 · maximum de elemente: 200

productsarray<Product>obligatoriu

Tot ce poate fi comandat. Fiecare produs face referire la o categorie.

minimum de elemente: 1 · maximum de elemente: 5000

Răspunsuri

204

Meniul a fost publicat sau exista deja o copie identică publicată.

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

413

Corpul cererii depășește 4 MiB.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X PUT "https://website.api.pionier.ro/v1/menu" \
  -H "Authorization: Bearer $NEXUS_PUBLISHER_KEY" \
  -H "X-Website-Publication: 1" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

request.json

{
  "revision": "example-menu-1",
  "currency": "RON",
  "accepting_orders": true,
  "fulfillment": [
    "pickup",
    "delivery"
  ],
  "delivery_fee": 700,
  "categories": [
    {
      "id": "pizzas",
      "name": "Pizza"
    },
    {
      "id": "meals",
      "name": "Meals"
    }
  ],
  "products": [
    {
      "id": "pizza-margherita",
      "category_id": "pizzas",
      "name": "Margherita",
      "description": "Tomato, mozzarella and basil",
      "image_url": "https://images.example.test/margherita.jpg",
      "translations": {
        "en": {
          "name": "Margherita",
          "description": "Tomato, mozzarella and basil"
        },
        "ro": {
          "name": "Margherita",
          "description": "Roșii, mozzarella și busuioc"
        }
      },
      "price": 3200,
      "packaging": 100,
      "packaging_product_id": "pizza-box",
      "modifier_groups": [
        {
          "id": "pizza-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "cheese",
              "name": "Extra cheese",
              "price": 400
            }
          ]
        }
      ]
    },
    {
      "id": "burger-meal",
      "category_id": "meals",
      "name": "Burger meal",
      "description": "Burger, fries and your choice of drink",
      "translations": {
        "en": {
          "name": "Burger meal",
          "description": "Burger, fries and your choice of drink"
        },
        "ro": {
          "name": "Meniu burger",
          "description": "Burger, cartofi prăjiți și băutură la alegere"
        }
      },
      "price": 2500,
      "packaging": 100,
      "packaging_product_id": "meal-bag",
      "modifier_groups": [
        {
          "id": "size",
          "name": "Size",
          "kind": "variant",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "regular",
              "name": "Regular",
              "price": 0
            },
            {
              "id": "large",
              "name": "Large",
              "price": 0
            }
          ]
        },
        {
          "id": "drink",
          "name": "Drink",
          "kind": "bundle",
          "minimum": 1,
          "maximum": 1,
          "options": [
            {
              "id": "water",
              "name": "Water",
              "price": 0,
              "deposit": 50
            }
          ]
        },
        {
          "id": "meal-extras",
          "name": "Extras",
          "kind": "extra",
          "minimum": 0,
          "maximum": 1,
          "options": [
            {
              "id": "sauce",
              "name": "Extra sauce",
              "price": 200
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "meal-regular",
          "selections": [
            {
              "group_id": "size",
              "option_id": "regular"
            }
          ],
          "price": 2500
        },
        {
          "id": "meal-large",
          "selections": [
            {
              "group_id": "size",
              "option_id": "large"
            }
          ],
          "price": 3000
        }
      ]
    }
  ]
}

Răspuns

204

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

409

{
  "error": "revision_already_used"
}

413

{
  "error": "body_too_large"
}

503

{
  "error": "storage_unavailable"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders

Trimite o comandă

Autentificare: WebsiteKey

Trimite o comandă restaurantului. 201 înseamnă că restaurantul a primit-o; personalul trebuie încă să o accepte. Retrimiterea cererii identice întoarce 200 cu confirmarea inițială și nu creează niciodată o a doua comandă. După expirarea timpului de răspuns sau 503, retrimite același external_order_id și același corp. Primește progresul prin webhook-uri; folosește GET pentru reconcilierea actualizărilor lipsă sau când webhook-urile nu sunt disponibile.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

Corpul cererii application/json

Schemă: OrderRequest

external_order_idstringobligatoriu

ID-ul tău pentru această achiziție. Salvează-l înainte de trimitere și refolosește-l neschimbat la fiecare reîncercare; gateway-ul nu creează niciodată două comenzi pentru același ID.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

menu_revisionstringobligatoriu

Revizia meniului folosită la calcularea prețului acestui coș.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

currencystringopțional

Întotdeauna RON.

implicit: "RON" · valoare: "RON"

fulfillmentstringobligatoriu

pickup sau delivery. Ambele modalități sunt acceptate.

valori: ["delivery", "pickup"]

scheduled_forstring | nullopțional

Ora cerută pentru onorare, cu offset explicit. Null înseamnă onorare imediată.

customerCustomerobligatoriu

Persoana care a plasat comanda.

addressAddress | nullopțional

Obligatorie pentru livrare; omite sau trimite null pentru ridicare.

paymentPaymentobligatoriu

Cum este plătită comanda. Nexus nu încasează de la client.

itemsarray<OrderLine>obligatoriu

Coșul: între 1 și 100 de linii.

minimum de elemente: 1 · maximum de elemente: 100

totalintegerobligatoriu

Totalul calculat de tine în bani, după reducerile publicate și incluzând garanțiile, ambalajele, taxa de livrare și bacșișul. Gateway-ul recalculează și respinge diferențele.

min: 0.0 · max: 100000000.0

tipintegeropțional

Bacșiș opțional pentru personalul restaurantului în bani, implicit zero. Include-l o singură dată în total. Necesită menu.tips_enabled.

min: 0.0 · max: 100000000.0 · implicit: 0

checkout_discountCheckoutDiscount | nullopțional

Cupon opțional la finalizarea comenzii. Unul per comandă; alocarea este păstrată împreună cu cererea inițială.

notesstringopțional

Instrucțiuni pentru întreaga comandă. Folosește items[].notes pentru un singur produs.

lungime maximă: 1000 · implicit: ""

Răspunsuri

201

Restaurantul a primit comanda; aceasta așteaptă acceptarea de către personal.

OrderReceipt

200

Comanda identică a fost deja primită; întoarce confirmarea inițială.

OrderReceipt

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

413

Corpul cererii depășește 4 MiB.

Error

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Pizza cu ridicare, plătită online

{
  "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"
}

Două meniuri combo, numerar la livrare

{
  "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
}

Răspuns

201

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

200

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

409

{
  "error": "menu_changed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

413

{
  "error": "body_too_large"
}

404

{
  "detail": "connection_not_found"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/connections/{connection_id}/orders/{external_order_id}

Citește starea curentă a comenzii

Autentificare: WebsiteKey

Întoarce starea curentă a comenzii din restaurant. Folosește-o pentru reconcilierea notificărilor webhook sau pentru citiri periodice când webhook-urile nu sunt configurate. Un 503 înseamnă că starea nu a putut fi citită, nu că a fost respinsă comanda. Oprește citirile la completed, rejected sau cancelled.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathobligatoriu

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

Răspunsuri

200

Starea curentă a comenzii.

OrderReceipt

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

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

Răspuns

200

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

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/refunds

Raportează rezultatul unei rambursări externe

Autentificare: WebsiteKey

Înregistrează rezultatul final succeeded sau failed al unei rambursări efectuate de procesatorul tău. Nu inițiază și nu verifică o rambursare și nu inversează un bon Retail. Doar comenzile paid_online sunt eligibile. Salvează request_id și reîncearcă același corp după un răspuns incert. Fiecare processor_reference este unică per comandă; maximum 100 de rapoarte. Sumele reușite nu pot depăși totalul inițial al comenzii.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

Corpul cererii application/json

Schemă: RefundReport

request_idstringobligatoriu

Identitate stabilă pentru acest raport final de rambursare; reîncearcă fără modificări.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

processor_referencestringobligatoriu

Referință unică a procesatorului per comandă; păstrată privat pentru reconciliere.

lungime minimă: 1 · lungime maximă: 200

outcomestringobligatoriu

Rezultat final raportat de website: succeeded sau failed. Nu este verificat cu un procesator.

valori: ["succeeded", "failed"]

amountintegerobligatoriu

Suma pozitivă a rambursării în bani, fără rambursările deja raportate.

min: 1.0 · max: 100000000.0

Răspunsuri

200

Successful Response

OrderReceipt

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/refunds" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Răspuns

200

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "refund_report_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/delivery

Raportează progresul livrării

Autentificare: WebsiteKey

Trimite un request_id stabil pentru fiecare actualizare și reîncearcă același corp după un rezultat incert. Doar comenzi cu livrare: alocarea necesită acceptarea, ridicarea necesită starea ready, iar delivered necesită picked_up. Maximum 100 de actualizări distincte per comandă. Datele de contact și estimările omise păstrează valorile anterioare. Nu înregistrează încasarea plății.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

Corpul cererii application/json

Schemă: DeliveryUpdate

request_idstringobligatoriu

Identitate stabilă pentru această actualizare a livrării; reîncearcă fără modificări.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

statusstringobligatoriu

assigned, arrived, picked_up sau delivered; tranzițiile nu pot reveni la o stare anterioară.

valori: ["assigned", "arrived", "picked_up", "delivered"]

courier_namestring | nullopțional

Numele curierului pentru personalul restaurantului; exclus din starea publică și webhook-uri.

courier_phonestring | nullopțional

Telefonul curierului pentru personalul restaurantului; exclus din starea publică și webhook-uri.

estimated_pickup_atstring | nullopțional

Ora estimată a ridicării cu offset; null păstrează estimarea anterioară.

estimated_delivery_atstring | nullopțional

Ora estimată a livrării cu offset; null păstrează estimarea anterioară.

Răspunsuri

200

Successful Response

OrderReceipt

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/delivery" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Răspuns

200

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "delivery_update_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/connections/{connection_id}/orders/{external_order_id}/cancel

Anulează o comandă eligibilă

Autentificare: WebsiteKey

Comenzile imediate pot fi anulate înainte de acceptare. Comenzile programate acceptate pot fi anulate strict înainte de momentul salvat pentru începerea preparării, dacă prepararea nu a început. Ulterior este necesară aprobarea personalului restaurantului în Retail; comenzile finalizate nu pot fi anulate. Retrimite același request_id și corp după un răspuns incert. Codul 409 cancellation_not_allowed indică depășirea intervalului de anulare de către client sau o stare care nu mai este eligibilă. Anularea nu restituie plata și nu stornează bonurile fiscale; personalul trebuie să reconcilieze bonurile existente în Nexus ERP.

Parametri

connection_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

external_order_idstringpathobligatoriu

format: "^[A-Za-z0-9_-]{1,100}$"

Corpul cererii application/json

Schemă: CancellationRequest

request_idstringobligatoriu

Identitatea stabilă a anulării. Salvează și retrimite același ID și motiv după rezultate incerte.

lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

reasonstringobligatoriu

Motivul anulării de către client. Nu inițiază niciodată o rambursare.

valori: ["customer_request", "duplicate", "ordered_by_mistake", "other"]

Răspunsuri

200

Successful Response

OrderReceipt

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Conexiunea nu este disponibilă pentru acest tenant sau meniul/comanda solicitată nu există.

DetailError

409

Conflict, de exemplu o revizie de meniu învechită sau un articol epuizat. Codul erorii indică ce trebuie schimbat.

Error

503

Rezultat neconfirmat. Reîncearcă după cel puțin 5 secunde; păstrează ID-ul și corpul comenzii.

Error | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/connections/$NEXUS_CONNECTION_ID/orders/shop-1001/cancel" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Răspuns

200

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "order_not_found"
}

409

{
  "error": "cancellation_not_allowed"
}

503

{
  "error": "retail_unavailable",
  "retry_same_order_id": true
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/webhook

Citește configurația webhook-ului

Autentificare: WebsiteKey

Întoarce configurația de callback a tenantului. Secretul de semnare nu este întors niciodată prin GET. Un singur callback deservește toate conexiunile POS activate.

Răspunsuri

200

Configurația curentă de callback; salvează în siguranță orice secret de semnare întors.

WebhookSubscription

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

503

Semnarea webhook-urilor nu este activată pe acest gateway. Contactează Nexus; rutele existente pentru comenzi rămân disponibile.

DetailError | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl "https://website.api.pionier.ro/v1/webhook" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

200

Fără conținut

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

PUT/v1/webhook

Configurează webhook-ul tenantului

Autentificare: WebsiteKey

Înregistrează un singur callback HTTPS public pe portul 443 folosind cheia website. Setează enabled la false pentru a opri livrarea. Crearea sau schimbarea URL-ului întoarce o singură dată un signing_secret nou și anulează evenimentele din coadă pentru configurația veche. Un PUT identic păstrează secretul și întoarce null pentru signing_secret; înlocuiește-l dacă ai pierdut răspunsul inițial. Comenzile noi primite cât timp webhook-ul este activat sunt urmărite în fundal; istoricul comenzilor existente nu este preluat retroactiv.

Corpul cererii application/json

Schemă: WebhookConfiguration

urlstringobligatoriu

URL de callback HTTPS public pe portul 443. Fără parametri de interogare, fragment sau credențiale.

lungime maximă: 2048

enabledbooleanopțional

Activează notificările despre comenzi, disponibilitate, meniuri și conexiuni. False anulează livrările din coadă.

implicit: true

Răspunsuri

200

Configurația curentă de callback; salvează în siguranță orice secret de semnare întors.

WebhookSubscription

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

503

Semnarea webhook-urilor nu este activată pe acest gateway. Contactează Nexus; rutele existente pentru comenzi rămân disponibile.

DetailError | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X PUT "https://website.api.pionier.ro/v1/webhook" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

request.json

{
  "url": "https://shop.example.com/nexus/events",
  "enabled": true
}

Răspuns

200

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/webhook/rotate-secret

Înlocuiește secretul de semnare al webhook-ului

Autentificare: WebsiteKey

Întoarce un secret de semnare nou pentru callback-ul curent. Evenimentele din coadă semnate pentru configurația anterioară sunt anulate. O cerere HTTP deja trimisă poate totuși să ajungă. Înlocuirea cheii API este separată și nu modifică acest secret.

Răspunsuri

200

Configurația curentă de callback; salvează în siguranță orice secret de semnare întors.

WebhookSubscription

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Consultă codul erorii și ghidul de recuperare.

DetailError

503

Semnarea webhook-urilor nu este activată pe acest gateway. Contactează Nexus; rutele existente pentru comenzi rămân disponibile.

DetailError | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/webhook/rotate-secret" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

200

Fără conținut

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "webhook_not_configured"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

GET/v1/webhook/deliveries

Verifică livrările recente de webhook-uri

Autentificare: WebsiteKey

Întoarce până la 100 de livrări recente pentru acest tenant, cele mai noi primele. Include ID-uri stabile de eveniment, ID-uri de comandă/conexiune, numere de încercări, starea livrării și coduri de eroare fără date sensibile. Corpurile răspunsurilor receptorului și secretele de semnare nu sunt expuse niciodată.

Răspunsuri

200

Ultimele 100 de înregistrări de livrare pentru acest tenant.

array<WebhookDelivery>

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

503

Semnarea webhook-urilor nu este activată pe acest gateway. Contactează Nexus; rutele existente pentru comenzi rămân disponibile.

DetailError | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl "https://website.api.pionier.ro/v1/webhook/deliveries" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

200

Fără conținut

401

{
  "detail": "invalid_credentials"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

POST/v1/webhook/deliveries/{event_id}/retry

Reîncearcă o livrare epuizată

Autentificare: WebsiteKey

Reintroduce în coadă un eveniment eșuat cu același ID și corp, cu o nouă fereastră de încercări de livrare. Pot fi reîncercate doar evenimentele eșuate ale acestui tenant pentru callback-ul curent activat. Secvența originală a comenzii rămâne neschimbată; receptorii trebuie să ignore secvențele mai vechi.

Parametri

event_idstringpathobligatoriu

format: "^evt_[a-f0-9]{48}$"

Răspunsuri

204

Evenimentul eșuat a fost reintrodus în coadă cu identitatea și corpul originale.

422

Date de intrare invalide. Sunt întoarse căile și tipurile câmpurilor; valorile introduse sunt omise.

ValidationError

401

Cheie absentă, invalidă sau cu rol greșit.

DetailErrorAntet WWW-Authenticate

404

Consultă codul erorii și ghidul de recuperare.

DetailError

503

Semnarea webhook-urilor nu este activată pe acest gateway. Contactează Nexus; rutele existente pentru comenzi rămân disponibile.

DetailError | objectAntet Retry-After Întârzierea minimă în secunde.

429

Limita de cereri a fost depășită. Așteaptă numărul de secunde din Retry-After și repetă aceeași cerere.

Antet Retry-After Numărul de secunde de așteptat.

Cerere

cURL

curl -X POST "https://website.api.pionier.ro/v1/webhook/deliveries/$NEXUS_EVENT_ID/retry" \
  -H "Authorization: Bearer $NEXUS_WEBSITE_KEY"

Răspuns

204

Fără conținut

422

{
  "error": "invalid_request",
  "fields": [
    {
      "path": [
        "body",
        "total"
      ],
      "type": "int_type"
    }
  ]
}

401

{
  "detail": "invalid_credentials"
}

404

{
  "detail": "failed_delivery_not_found"
}

503

{
  "detail": "webhooks_not_configured"
}

429

{
  "error": "rate_limit_exceeded"
}

Modele de date

Câmpurile necunoscute din cereri sunt respinse. Sumele sunt în bani întregi; cantitățile sunt întregi. Cerințele condiționate, precum adresa de livrare și referința plății, sunt descrise în ghiduri.

Address

Câmp	Contract
`city`obligatoriu	string Orașul de livrare. lungime minimă: 1 · lungime maximă: 100
`street`obligatoriu	string Strada și numărul. lungime minimă: 1 · lungime maximă: 200
`details`opțional	string Apartament, intrare sau alte indicații. lungime maximă: 500 · implicit: ""

CancellationRequest

Câmp	Contract
`request_id`obligatoriu	string Identitatea stabilă a anulării. Salvează și retrimite același ID și motiv după rezultate incerte. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`reason`obligatoriu	string Motivul anulării de către client. Nu inițiază niciodată o rambursare. valori: ["customer_request", "duplicate", "ordered_by_mistake", "other"]

Category

Câmp	Contract
`name`obligatoriu	string Numele secțiunii afișat clienților. lungime minimă: 1 · lungime maximă: 256
`translations`opțional	object Nume și descrieri indexate după limbă. Folosește name și description când traducerea lipsește.
`id`obligatoriu	string ID-ul categoriei la care fac referire produsele. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

CheckoutDiscount

Câmp	Contract
`code`obligatoriu	string Identificatorul cuponului; eligibilitatea este verificată de backendul website-ului. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`amount`obligatoriu	integer Reducere suportată de restaurant, în bani întregi, după promoțiile meniului. Nu poate depăși prețurile de bază eligibile ale produselor. min: 1.0 · max: 100000000.0
`product_ids`opțional	array<string> \| null ID-uri unice opționale ale produselor din comandă. Omite pentru toate produsele. Extraopțiunile, garanțiile, ambalajele, livrarea și bacșișul sunt excluse.

ConnectionList

Câmp	Contract
`connections`obligatoriu	array<ConnectionSummary> Conexiunile activate pentru cheia website. Lista este goală până când restaurantul activează una.

ConnectionSummary

Câmp	Contract
`id`obligatoriu	string ID-ul conexiunii folosit în URL-urile pentru meniu, comandă și stare. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`location_id`obligatoriu	string ID-ul locației restaurantului. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`location_name`obligatoriu	string Numele locației afișat clienților.
`pos_id`obligatoriu	string ID-ul casei de marcat care primește comenzile. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`pos_name`obligatoriu	string Numele casei de marcat, util pentru asistență.

Customer

Câmp	Contract
`name`obligatoriu	string Numele clientului pentru personal și bon. lungime minimă: 1 · lungime maximă: 200
`phone`obligatoriu	string Numărul de telefon la care personalul poate suna în legătură cu comanda. lungime minimă: 3 · lungime maximă: 40

DatePeriod

Câmp	Contract
`start`obligatoriu	string Ora locală de început, inclusivă, HH:mm.
`end`obligatoriu	string Sfârșit exclusiv în aceeași zi, HH:mm; este permis 24:00.

DeliveryStatus

Câmp	Contract
`status`obligatoriu	string Ultima stare confirmată a livrării. valori: ["assigned", "arrived", "picked_up", "delivered"]
`estimated_pickup_at`opțional	string \| null Ultima estimare a ridicării sau null.
`estimated_delivery_at`opțional	string \| null Ultima estimare a livrării sau null.
`picked_up_at`opțional	string \| null Momentul înregistrat de server la confirmarea ridicării.
`delivered_at`opțional	string \| null Momentul înregistrat de server la confirmarea livrării.

DeliveryUpdate

Câmp	Contract
`request_id`obligatoriu	string Identitate stabilă pentru această actualizare a livrării; reîncearcă fără modificări. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`status`obligatoriu	string assigned, arrived, picked_up sau delivered; tranzițiile nu pot reveni la o stare anterioară. valori: ["assigned", "arrived", "picked_up", "delivered"]
`courier_name`opțional	string \| null Numele curierului pentru personalul restaurantului; exclus din starea publică și webhook-uri.
`courier_phone`opțional	string \| null Telefonul curierului pentru personalul restaurantului; exclus din starea publică și webhook-uri.
`estimated_pickup_at`opțional	string \| null Ora estimată a ridicării cu offset; null păstrează estimarea anterioară.
`estimated_delivery_at`opțional	string \| null Ora estimată a livrării cu offset; null păstrează estimarea anterioară.

Câmp	Contract
`revision`obligatoriu	string Versiunea meniului publicat. Trimite-o ca menu_revision. Disponibilitatea și accepting_orders se pot schimba fără o revizie nouă. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`currency`opțional	string Întotdeauna RON. Sumele sunt în bani întregi. implicit: "RON" · valoare: "RON"
`accepting_orders`opțional	boolean False când restaurantul este în pauză sau închis. Continuă să afișezi meniul, dar dezactivează finalizarea comenzii. implicit: true
`opening_hours`opțional	OpeningHours \| null Programul curent și excepțiile restaurantului în fusul său orar. Null dacă nu există politică configurată.
`scheduling`opțional	SchedulingPolicy Comenzile programate sunt acceptate întotdeauna; durata implicită de preparare stabilește momentul începerii în bucătărie.
`fulfillment`obligatoriu	array<string> Include întotdeauna ridicare și livrare. minimum de elemente: 1 · maximum de elemente: 2
`delivery_fee`opțional	integer Taxă fixă în bani, aplicată o singură dată per comandă cu livrare, niciodată pentru ridicare. min: 0.0 · max: 100000000.0 · implicit: 0
`tips_enabled`opțional	boolean Indică dacă pot fi incluse bacșișuri pentru personalul restaurantului. Necesită configurarea bacșișului în POS; bacșișurile curierului nu sunt incluse. implicit: false
`categories`obligatoriu	array<Category> Secțiunile meniului. minimum de elemente: 1 · maximum de elemente: 200
`products`obligatoriu	array<Product> Tot ce poate fi comandat. Fiecare produs face referire la o categorie. minimum de elemente: 1 · maximum de elemente: 5000

Modifier

Câmp	Contract
`name`obligatoriu	string Numele opțiunii afișat clienților. lungime minimă: 1 · lungime maximă: 256
`translations`opțional	object Nume și descrieri indexate după limbă. Folosește name și description când traducerea lipsește.
`id`obligatoriu	string Trimite ca items[].modifiers[].option_id. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`price`obligatoriu	integer Preț suplimentar în bani pentru un extra. Întotdeauna 0 pentru opțiunile variant și bundle. min: 0.0 · max: 100000000.0
`deposit`opțional	integer Garanția în bani adăugată la selectare, de exemplu garanția sticlei unei băuturi incluse. min: 0.0 · max: 100000000.0 · implicit: 0
`available`opțional	boolean False când opțiunea este epuizată. Nu permite selectarea ei. implicit: true

ModifierGroup

Câmp	Contract
`name`obligatoriu	string Numele grupului afișat clienților. lungime minimă: 1 · lungime maximă: 256
`translations`opțional	object Nume și descrieri indexate după limbă. Folosește name și description când traducerea lipsește.
`kind`opțional	string variant definește produsul (de exemplu mărimea), bundle este o componentă inclusă, extra este un adaos contra cost. implicit: "extra" · valori: ["extra", "variant", "bundle"]
`id`obligatoriu	string Trimite ca items[].modifiers[].group_id. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`minimum`opțional	integer Numărul minim de opțiuni diferite pe care trebuie să le aleagă clientul. min: 0.0 · max: 99.0 · implicit: 0
`maximum`opțional	integer Numărul maxim de opțiuni diferite pe care le poate alege clientul. min: 1.0 · max: 99.0 · implicit: 1
`options`obligatoriu	array<Modifier> Opțiunile acestui grup. minimum de elemente: 1 · maximum de elemente: 100

OpeningHours

Câmp	Contract
`schedule_enabled`opțional	boolean Indică dacă programul săptămânal restricționează comenzile. Excepțiile și pauzele manuale se aplică în continuare. implicit: false
`time_zone`opțional	string Fusul orar IANA folosit pentru programul restaurantului și al produselor. implicit: "Europe/Bucharest"
`periods`opțional	array<OpeningPeriod> Intervale săptămânale de funcționare; sunt permise intervale peste miezul nopții. maximum de elemente: 28
`special_dates`opțional	array<SpecialDate> Înlocuiri complete pentru anumite date locale. Lista periods goală înseamnă închis. maximum de elemente: 366

OpeningPeriod

Câmp	Contract
`day`obligatoriu	integer Zi ISO: luni 1 până la duminică 7. min: 1.0 · max: 7.0
`start`obligatoriu	string Ora locală de început, inclusivă, HH:mm.
`end`obligatoriu	string Ora locală de sfârșit, exclusivă, HH:mm; este permis 24:00. O oră anterioară încheie intervalul în ziua următoare.

OrderLine

Câmp	Contract
`product_id`obligatoriu	string ID-ul unui produs din meniu. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`quantity`obligatoriu	integer Numărul de unități, de la 1 la 99. min: 1.0 · max: 99.0
`modifiers`opțional	array<Selection> Toate opțiunile alese de client pentru această linie, inclusiv mărimea și componentele incluse. Fiecare pereche apare cel mult o dată. maximum de elemente: 100
`notes`opțional	string Instrucțiuni pentru această linie, de exemplu „fără ceapă”. lungime maximă: 500 · implicit: ""

OrderReceipt

Câmp	Contract
`external_order_id`obligatoriu	string ID-ul comenzii tale. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`status`obligatoriu	string Progresul comenzii. La un POST repetat, starea din momentul primei primiri a comenzii. valori: ["pending_acceptance", "accepted", "preparing", "ready", "out_for_delivery", "completed", "rejected", "cancelled"]
`total`obligatoriu	integer Totalul comenzii în bani. min: 0.0 · max: 100000000.0
`currency`obligatoriu	string Întotdeauna RON. valoare: "RON"
`scheduled_for`opțional	string \| null Ora cerută inițial pentru onorare sau null pentru comenzile imediate.
`estimated_ready_at`opțional	string \| null Ora estimată de restaurant după acceptare; poate fi ulterioară orei cerute.
`reason`opțional	string \| null Codul motivului de respingere sau anulare, când este disponibil.
`delivery`opțional	DeliveryStatus \| null Starea livrării și estimări, fără datele de contact ale curierului; null până la prima raportare.
`refund`opțional	RefundStatus \| null Sumarul rambursărilor externe raportate sau null înaintea primului raport.

OrderRequest

Câmp	Contract
`external_order_id`obligatoriu	string ID-ul tău pentru această achiziție. Salvează-l înainte de trimitere și refolosește-l neschimbat la fiecare reîncercare; gateway-ul nu creează niciodată două comenzi pentru același ID. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`menu_revision`obligatoriu	string Revizia meniului folosită la calcularea prețului acestui coș. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`currency`opțional	string Întotdeauna RON. implicit: "RON" · valoare: "RON"
`fulfillment`obligatoriu	string pickup sau delivery. Ambele modalități sunt acceptate. valori: ["delivery", "pickup"]
`scheduled_for`opțional	string \| null Ora cerută pentru onorare, cu offset explicit. Null înseamnă onorare imediată.
`customer`obligatoriu	Customer Persoana care a plasat comanda.
`address`opțional	Address \| null Obligatorie pentru livrare; omite sau trimite null pentru ridicare.
`payment`obligatoriu	Payment Cum este plătită comanda. Nexus nu încasează de la client.
`items`obligatoriu	array<OrderLine> Coșul: între 1 și 100 de linii. minimum de elemente: 1 · maximum de elemente: 100
`total`obligatoriu	integer Totalul calculat de tine în bani, după reducerile publicate și incluzând garanțiile, ambalajele, taxa de livrare și bacșișul. Gateway-ul recalculează și respinge diferențele. min: 0.0 · max: 100000000.0
`tip`opțional	integer Bacșiș opțional pentru personalul restaurantului în bani, implicit zero. Include-l o singură dată în total. Necesită menu.tips_enabled. min: 0.0 · max: 100000000.0 · implicit: 0
`checkout_discount`opțional	CheckoutDiscount \| null Cupon opțional la finalizarea comenzii. Unul per comandă; alocarea este păstrată împreună cu cererea inițială.
`notes`opțional	string Instrucțiuni pentru întreaga comandă. Folosește items[].notes pentru un singur produs. lungime maximă: 1000 · implicit: ""

Payment

Câmp	Contract
`method`obligatoriu	string paid_online când procesatorul tău a încasat deja de la client; cash_on_fulfillment sau card_on_fulfillment când restaurantul încasează plata. valori: ["paid_online", "cash_on_fulfillment", "card_on_fulfillment"]
`reference`opțional	string \| null Referința tranzacției din procesatorul tău de plăți. Obligatorie pentru paid_online; omite pentru celelalte metode.

Product

Câmp	Contract
`name`obligatoriu	string Numele produsului afișat clienților. Afișează-l ca text. lungime minimă: 1 · lungime maximă: 256
`translations`opțional	object Nume și descrieri indexate după limbă. Folosește name și description când traducerea lipsește.
`id`obligatoriu	string Trimite ca items[].product_id. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`category_id`obligatoriu	string Categoria din care face parte produsul. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`description`opțional	string Descriere opțională afișată clienților. Afișeaz-o ca text. lungime maximă: 4000 · implicit: ""
`image_url`opțional	string \| null URL HTTP(S) absolut, opțional, pentru imagine. Gateway-ul nu descarcă imaginea.
`schedule`opțional	array<OpeningPeriod> \| null Program săptămânal al produsului în opening_hours.time_zone. Null înseamnă fără restricție; o listă goală înseamnă indisponibil toată săptămâna.
`price`obligatoriu	integer Prețul de bază în bani. Pentru un produs cu variante, este înlocuit de prețul variantei selectate. min: 0.0 · max: 100000000.0
`discount`opțional	integer Reducerea publicată în bani per unitate, scăzută din price înaintea garanțiilor, ambalajelor și extra. Implicit zero. Nu trimite o reducere în comandă. min: 0.0 · max: 100000000.0 · implicit: 0
`deposit`opțional	integer Garanția în bani per unitate, de exemplu garanția unei sticle. Este înlocuită de garanția variantei selectate. min: 0.0 · max: 100000000.0 · implicit: 0
`packaging`opțional	integer Costul ambalajului în bani per unitate, adăugat peste preț. min: 0.0 · max: 100000000.0 · implicit: 0
`packaging_product_id`opțional	string \| null Articolul de ambalaj adăugat de restaurant pe bon. Nu îl adăuga în comandă.
`available`opțional	boolean False când produsul este epuizat sau nu se vinde în această locație. Nu permite selectarea lui. implicit: true
`modifier_groups`opțional	array<ModifierGroup> Opțiunile produsului: variant (de exemplu mărimea), bundle (o componentă inclusă) sau extra (un adaos contra cost). maximum de elemente: 30
`variants`opțional	array<Variant> Toate combinațiile valide ale opțiunilor de variantă ale produsului, fiecare cu propriul preț. Potrivește alegerile clientului cu una dintre ele. maximum de elemente: 500

RefundReport

Câmp	Contract
`request_id`obligatoriu	string Identitate stabilă pentru acest raport final de rambursare; reîncearcă fără modificări. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`processor_reference`obligatoriu	string Referință unică a procesatorului per comandă; păstrată privat pentru reconciliere. lungime minimă: 1 · lungime maximă: 200
`outcome`obligatoriu	string Rezultat final raportat de website: succeeded sau failed. Nu este verificat cu un procesator. valori: ["succeeded", "failed"]
`amount`obligatoriu	integer Suma pozitivă a rambursării în bani, fără rambursările deja raportate. min: 1.0 · max: 100000000.0

RefundStatus

Câmp	Contract
`reported_refunded_amount`obligatoriu	integer Suma rambursărilor reușite raportate de website; nu reprezintă verificarea procesatorului. min: 0.0 · max: 100000000.0
`report_count`obligatoriu	integer Numărul rapoartelor finale distincte, inclusiv rambursările eșuate. min: 1.0 · max: 100.0
`last_outcome`obligatoriu	string Ultimul rezultat raportat: succeeded sau failed. valori: ["succeeded", "failed"]
`last_reported_at`obligatoriu	string Momentul înregistrat de server pentru ultimul raport confirmat.

SchedulingPolicy

Câmp	Contract
`enabled`opțional	boolean Întotdeauna true. Comenzile programate nu necesită activare. implicit: true
`preparation_minutes`opțional	integer Durata implicită de preparare; personalul poate adăuga timp la acceptare. min: 1.0 · max: 240.0 · implicit: 20

Selection

Câmp	Contract
`group_id`obligatoriu	string ID-ul unui grup de opțiuni al produsului. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`option_id`obligatoriu	string ID-ul unei opțiuni din acel grup. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"

SpecialDate

Câmp	Contract
`date`obligatoriu	string Data calendaristică locală, YYYY-MM-DD.
`periods`opțional	array<DatePeriod> Intervale care înlocuiesc întreaga zi. Lista goală înseamnă închis, inclusiv prelungirea din ziua precedentă. maximum de elemente: 8

Translation

Câmp	Contract
`name`obligatoriu	string Numele tradus. Afișează-l ca text. lungime minimă: 1 · lungime maximă: 256
`description`opțional	string Descrierea tradusă. Goală dacă nu a fost completată. Afișeaz-o ca text. lungime maximă: 4000 · implicit: ""

Variant

Câmp	Contract
`id`obligatoriu	string Identifică această combinație. Nu îl trimite în comenzi; trimite opțiunile în schimb. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`selections`obligatoriu	array<Selection> Opțiunile de variantă care formează această combinație. maximum de elemente: 100
`price`obligatoriu	integer Prețul în bani al combinației, care înlocuiește prețul produsului. min: 0.0 · max: 100000000.0
`discount`opțional	integer Reducerea publicată în bani per unitate, scăzută din price înaintea garanțiilor, ambalajelor și extra. Implicit zero. Nu trimite o reducere în comandă. min: 0.0 · max: 100000000.0 · implicit: 0
`deposit`opțional	integer Garanția în bani a combinației, care înlocuiește garanția produsului. min: 0.0 · max: 100000000.0 · implicit: 0
`available`opțional	boolean False când această combinație nu poate fi comandată. implicit: true

WebhookConfiguration

Câmp	Contract
`url`obligatoriu	string URL de callback HTTPS public pe portul 443. Fără parametri de interogare, fragment sau credențiale. lungime maximă: 2048
`enabled`opțional	boolean Activează notificările despre comenzi, disponibilitate, meniuri și conexiuni. False anulează livrările din coadă. implicit: true

WebhookDelivery

Câmp	Contract
`id`obligatoriu	string ID stabil de eveniment. Elimină livrările duplicate folosind această valoare.
`connection_id`obligatoriu	string Conexiunea POS identificată de acest eveniment.
`external_order_id`obligatoriu	string \| null ID-ul comenzii tale sau null pentru toate evenimentele de conexiune și meniu.
`state`obligatoriu	string pending, delivered, failed sau cancelled. Doar evenimentele failed pot fi reîncercate manual. valori: ["pending", "delivered", "failed", "cancelled"]
`attempts`obligatoriu	integer Numărul de încercări de livrare preluate în fereastra curentă de reîncercare.
`last_status`obligatoriu	integer \| null Ultimul status HTTP al receptorului sau null când nu s-a primit răspuns.
`failure`obligatoriu	string \| null Cod de eroare fără date sensibile sau null. Corpurile răspunsurilor receptorului nu sunt expuse niciodată.

WebhookSubscription

Câmp	Contract
`url`opțional	string \| null URL de callback înregistrat sau null înainte de configurare.
`enabled`opțional	boolean Indică dacă urmărirea și livrarea webhook-urilor sunt activate. implicit: false
`signing_secret`opțional	string \| null Întors doar la creare, schimbarea URL-ului sau înlocuirea secretului. Păstrează-l în siguranță în backend.

AvailabilityEventData

Câmp	Contract
`accepting_orders`obligatoriu	boolean Dacă se pot trimite comenzi acum; orele programate trebuie evaluate prin GET meniu.
`reason`obligatoriu	string accepting, paused, closed sau menu_not_published. valori: ["accepting", "paused", "closed", "menu_not_published"]
`pause_until`opțional	string \| null Expirarea pauzei în UTC sau null dacă nu există pauză temporizată. Expirarea respectă programul de funcționare. implicit: null

ConnectionEventData

Câmp	Contract
`enabled`obligatoriu	boolean Dacă această conexiune POS este activată. Recitește lista conexiunilor; conexiunile dezactivate nu pot primi comenzi.
`location_id`obligatoriu	string ID-ul locației restaurantului.
`location_name`obligatoriu	string Numele locației afișat clienților.
`pos_id`obligatoriu	string ID-ul casei de marcat care primește comenzile.
`pos_name`obligatoriu	string Numele casei de marcat, util pentru asistență.

DeliveryEventData

Câmp	Contract
`external_order_id`obligatoriu	string ID-ul comenzii tale. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`request_id`obligatoriu	string ID-ul stabil al cererii tale de raportare. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`status`obligatoriu	string Starea livrării trimisă în acest raport, nu neapărat ultima stare. valori: ["assigned", "arrived", "picked_up", "delivered"]
`estimated_pickup_at`opțional	string \| null Estimarea ridicării trimisă în acest raport sau null. implicit: null
`estimated_delivery_at`opțional	string \| null Estimarea livrării trimisă în acest raport sau null. implicit: null

MenuEventData

Câmp	Contract
`revision`obligatoriu	string Revizia publicată la momentul observării. Recitește meniul conexiunii; disponibilitatea se poate schimba fără o revizie nouă.

RefundEventData

Câmp	Contract
`external_order_id`obligatoriu	string ID-ul comenzii tale. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`request_id`obligatoriu	string ID-ul stabil al cererii tale de raportare. lungime minimă: 1 · lungime maximă: 100 · format: "^[A-Za-z0-9_-]+$"
`outcome`obligatoriu	string Rezultat final raportat de website: succeeded sau failed. Nu este verificat cu un procesator. valori: ["succeeded", "failed"]
`amount`obligatoriu	integer Suma rambursării pentru acest raport, în bani. min: 0 · max: 100000000

SettingsEventData

Câmp	Contract
`settings_version`obligatoriu	string Amprenta opacă a setărilor de funcționare observate. Recitește meniul conexiunii pentru opening_hours și scheduling curente; aceasta nu este o revizie de meniu. format: "^[a-f0-9]{64}$"

WebhookEvent

Câmp	Contract
`id`obligatoriu	string ID stabil de eveniment. Elimină livrările duplicate folosind această valoare. format: "^evt_[a-f0-9]{48}$"
`type`obligatoriu	string Actualizări ale comenzilor, rapoarte de livrare/rambursare, disponibilitatea restaurantului, meniuri sau modificări ale conexiunilor POS. valori: ["order.status_changed", "order.updated", "order.delivery_updated", "refund.reported", "connection.availability_changed", "menu.published", "menu.availability_changed", "connection.changed", "connection.settings_changed"]
`sequence`obligatoriu	integer Secvență crescătoare per comandă; evenimentele fără comandă au secvențe separate pentru fiecare conexiune și tip de eveniment. Ignoră actualizările mai vechi. min: 1
`observed_at`obligatoriu	string Momentul observării în UTC, nu momentul acțiunii din restaurant.
`connection_id`obligatoriu	string Conexiunea POS identificată de acest eveniment.
`data`obligatoriu	OrderReceipt \| RefundEventData \| DeliveryEventData \| AvailabilityEventData \| MenuEventData \| ConnectionEventData \| SettingsEventData Datele depind de tip: OrderReceipt, DeliveryEventData, RefundEventData, AvailabilityEventData, MenuEventData, ConnectionEventData sau SettingsEventData.