Esempi di payload per ordini, per settore
Copia i payload completi per ordini di DEUNA, per ristoranti, compagnie aeree, cinema, banche e commercio al dettaglio.
Questi esempi mostrano i corpi di richiesta completi per POST /merchants/orders. Scegli un settore, ispeziona ogni campo e copia la richiesta JSON o cURL. Gli esempi seguono il contratto pubblico Create Order; gli importi sono espressi in unità monetarie minori.
Quali campi sono richiesti in order.items quando si crea un ordine?#
La risposta breve è che il validatore di richiesta di creazione ordine di base non definisce una proprietà universalmente richiesta all'interno di ciascun articolo. Verifica se l'array degli articoli è presente per un particolare tipo di ordine, non il contenuto di ciascun articolo.
| Tipo di ordine | Oggetto richiesto | Comportamento contrattuale di base |
|---|---|---|
DEUNA_CHECKOUT | order.items | Obbligatorio. Se fornito, il tipo di evasione accetta solo dine_in, pickupo delivery. |
SUBSCRIPTIONS | order.items | Obbligatorio. Contrassegnare le linee applicabili con included_in_subscription. |
AIRLINE_ORDER | order.airline_information | Obbligatorio. La matrice degli articoli rimane facoltativa a livello del contratto base. |
DEUNA_NOW | Nessuno | La matrice degli articoli non è richiesta dal contratto di base. Includilo quando l'elaborazione a valle richiede dettagli sul prodotto. |
PAYMENT_LINK | Nessuno | La matrice degli articoli non è richiesta dal contratto di base. Includilo quando l'esperienza ospitata o l'elaborazione downstream richiedono dettagli sul prodotto. |
Un elemento vuoto non è un obiettivo di integrazione utile. I fornitori di servizi di pagamento, i controlli antifrode, la gestione fiscale, la rendicontazione e la tua riconciliazione potrebbero richiedere maggiori dettagli. A meno che una guida del fornitore non indichi un requisito più rigoroso, utilizza questa linea di base portatile per ogni articolo:
JSON
{
"id": "merchant-item-001",
"sku": "SKU-001",
"name": "Product name",
"quantity": 1,
"unit_price": {
"amount": 2500,
"currency": "USD"
},
"total_amount": {
"amount": 2500,
"original_amount": 2500,
"total_discount": 0,
"currency": "USD"
},
"tax_amount": {
"amount": 0,
"currency": "USD"
},
"category": "products",
"type": "physical",
"taxable": false
}Il modello di articolo supporta i seguenti gruppi di campi:
| Oggetto | Campi supportati |
|---|---|
| Identità dell'articolo del commerciante | id, sku, upc, isbn |
| Dettagli dell'articolo rivolto al cliente | name, description, image_url, details_url |
| Dettagli su quantità e prezzi | quantity, uom, unit_price, total_amount, tax_amount, taxable, discounts |
| Catalogo e dettaglio varianti | brand, manufacturer, category, sub_category, color, size, weight |
| Realizzazione e contesto aggiuntivo | options, type, item_details, included_in_subscription, shipping_options |
| Campo | Valori documentati |
|---|---|
type | physical, digital, event, service |
Mantieni allineate le valute degli articoli e degli ordini e calcola gli importi nelle unità valutarie minori.
Campi obbligatori a livello di ordine e regola di importo
| Campo o regola | Requisito |
|---|---|
order_id | Obbligatorio per ogni ordine. |
currency | Obbligatorio per ogni ordine. |
total_amount | Deve essere maggiore di zero per i normali ordini di acquisto. Una ricorrenza del primo utilizzo con valore zero è l'eccezione documentata di verifica della carta. |
sub_total + total_tax_amount = total_amount | Applicato ogni volta che viene fornito un importo totale o parziale dell'imposta. |
Guida del campo verticale#
QSR, cinema, servizi bancari e vendita al dettaglio sono modelli di documentazione basati sul tipo di ordine di pagamento standard. Non sono valori di tipo ordine separati. Le compagnie aeree utilizzano il contratto d'ordine della compagnia aerea dedicato.
| Verticale | Tipo di ordine | Insieme di campi primari | Come usarlo |
|---|---|---|---|
| QSR | DEUNA_CHECKOUT | items[].id, items[].sku, options, shipping_options, scheduled_at, user_instructions | Identificare le righe e i modificatori del menu, la modalità di servizio e il negozio, il tempo di preparazione e le istruzioni di trasferimento. La matrice degli elementi è obbligatoria. |
| Compagnie aeree | AIRLINE_ORDER | airline_information.booking_items, pnr, ticket_number, passenger, legs, ancillaries | Invia prenotazione, biglietto, agenzia, passeggero, itinerario e dettagli del servizio a pagamento. Sono richieste le informazioni sulla compagnia aerea; l'array degli articoli è facoltativo a livello del contratto base. |
| Cinema | DEUNA_CHECKOUT | items, type, options, shipping_options.details, expires_at | Modella biglietti e concessioni come linee separate, identifica i biglietti per gli eventi e allega l'orario di proiezione, i posti, il luogo, il destinatario e la scadenza per la prenotazione del posto. La matrice degli elementi è obbligatoria. |
| Banca | DEUNA_CHECKOUT | items, type, description, statement_descriptor, initiator_type, channel_type, metadata | Modella il pagamento come servizio e invia riferimenti aziendali mascherati o tokenizzati. La matrice degli elementi è obbligatoria. Non inserire mai numeri di conto o credenziali completi nei metadati. |
| Commercio al dettaglio | DEUNA_CHECKOUT | items, discounts, shipping_address, shipping_method, shipping_options | Invia l'identità del prodotto e della variante, le promozioni, la destinazione, il metodo di consegna e il contesto di evasione. La matrice degli elementi è obbligatoria. Mantieni i riferimenti di sconto sugli articoli allineati con l'array di sconti a livello di ordine. |
Esempi completi#
Payload completo dell’ordine
QSR
Menu, modificatori, modalità di servizio, sede, orario e istruzioni del cliente in un unico ordine di ristorazione.
itemsshipping_optionsscheduled_atuser_instructionsCorpo della richiestaJSON
{
"order_type": "DEUNA_CHECKOUT",
"order": {
"order_id": "qsr-2048",
"store_code": "mad-gran-via-01",
"currency": "EUR",
"items_total_amount": 2890,
"sub_total": 2890,
"total_tax_amount": 286,
"total_amount": 3176,
"items": [
{
"id": "meal-smash-01",
"sku": "SMASH-COMBO",
"name": "Smash burger combo",
"description": "Burger, fries, and drink",
"options": "medium; no onions; sparkling water",
"quantity": 1,
"category": "combos",
"taxable": true,
"unit_price": {
"amount": 1890,
"currency": "EUR",
"currency_symbol": "€"
},
"total_amount": {
"amount": 1890,
"original_amount": 1890,
"currency": "EUR",
"currency_symbol": "€",
"total_discount": 0
},
"tax_amount": {
"amount": 172,
"currency": "EUR",
"currency_symbol": "€"
}
},
{
"id": "side-wings-06",
"sku": "WINGS-6",
"name": "Six hot wings",
"options": "chipotle sauce",
"quantity": 1,
"category": "sides",
"taxable": true,
"unit_price": {
"amount": 1000,
"currency": "EUR",
"currency_symbol": "€"
},
"total_amount": {
"amount": 1000,
"original_amount": 1000,
"currency": "EUR",
"currency_symbol": "€",
"total_discount": 0
},
"tax_amount": {
"amount": 114,
"currency": "EUR",
"currency_symbol": "€"
}
}
],
"shipping_options": {
"type": "pickup",
"method": "counter",
"requires_shipping": false,
"details": {
"store_id": "mad-gran-via-01",
"store_name": "Gran Vía",
"address": "Calle Gran Vía 42, Madrid",
"address_coordinates": {
"lat": 40.4201,
"lng": -3.7058
},
"contact": {
"name": "Gran Vía team",
"phone": "+34910000000"
},
"additional_details": {
"pickup_time": "2026-10-03T18:30:00Z",
"stock_location": "Front counter"
}
}
},
"scheduled_at": "2026-10-03T18:30:00Z",
"user_instructions": "Label the order for Alex. Include napkins.",
"payer_info": {
"email": "alex@example.com",
"external_registration_date": "2024-02-10T12:00:00Z"
},
"channel_type": "mobile_app_ios",
"metadata": {
"vertical": "qsr",
"service_mode": "pickup",
"loyalty_member_id": "LOY-88201"
},
"callback_urls": {
"on_success": "https://merchant.example.com/payments/success",
"on_pending": "https://merchant.example.com/payments/pending",
"on_reject": "https://merchant.example.com/payments/rejected",
"on_canceled": "https://merchant.example.com/payments/canceled",
"on_failed": "https://merchant.example.com/payments/failed"
}
}
}Cosa rimane comune#
Ogni settore utilizza lo stesso contratto di base:
order_id,store_codeecurrencyIdentificare il contesto aziendale del commerciante.- Gli importi sono numeri interi in unità di valuta minori e devono corrispondere ai dettagli dell'articolo, delle tasse, degli sconti e della spedizione.
itemsDescrivere cosa il cliente sta acquistando o pagando.payer_info,channel_typeeinitiator_typeChiarire chi ha avviato il processo e dove.callback_urlse i dati restituitiorder_tokenCollegare la richiesta sincrona al suo risultato finale.metadatacontiene riferimenti definiti dal commerciante; è preferibile utilizzare i campi di tipo supportati quando disponibili.