Ordini in JSON: schema ph.order/1.2

Payload versionato degli ordini ph.order/1.2: schema JSON pubblicato, regole di compatibilità ed esempi di consegna.

Quando si conferma una vendita, l'ordine viene consegnato nell'integrazione (webhook, SFTP o email) con questo JSON canonico e versionato. Questa pagina è la specifica esatta del formato ph.order/1.2.

Regole di formato

Tutte le chiavi sono sempre presenti; le chiavi non vengono mai omesse.
null significa «dato sconosciuto»; non deve essere interpretato come 0 (alcuni canali non dettagliano le imposte per riga).
Gli importi sono numeri con fino a 2 decimali.
tax_rate è un decimale: 0.21 equivale al 21 %.
channel è il codice interno del canale (ad es. ebay, wllp) e channel_name il suo nome visibile (ad es. Ebay, Wallapop).
total_gross è il prezzo di vendita per il venditore, commissione del venditore inclusa: channel_fees_gross (ciò che il canale gli trattiene da tale importo) e buyer_fees_gross (ciò che l'acquirente paga al canale oltre al prezzo, mai dentro total_gross) sono informativi; lo è anche shipping_gross (trasporto), che può essere incluso o meno in total_gross a seconda del canale (le lines danno il dettaglio della merce).

Esempio di payload

{
  "schema": "ph.order/1.2",
  "order_id": "123456789",
  "channel": "ebay",
  "channel_name": "Ebay",
  "created_at": "2026-06-18T10:32:00+00:00",
  "status": "accepted",
  "currency": "EUR",
  "original_currency": "EUR",
  "exchange_rate": 1.0,
  "customer": {
    "foreign_id": "a1b2c3d4",
    "first_name": "Toni",
    "last_name": "Bosch",
    "company_name": null,
    "email": "toni.bosch@example.com",
    "tax_number": "12345678Z",
    "phone": "+34600000000",
    "address": {
      "street": "Carrer Major 1",
      "city": "Campdevànol",
      "province": "Girona",
      "postal_code": "17530",
      "country": "ES"
    }
  },
  "lines": [
    {
      "external_id": "ITEM-001",
      "title": "Faro delantero izquierdo",
      "quantity": 1,
      "line_net": 100.00,
      "line_tax": 21.00,
      "line_gross": 121.00,
      "tax_rate": 0.21
    }
  ],
  "shipping_gross": 10.00,
  "channel_fees_gross": 13.00,
  "buyer_fees_gross": null,
  "total_net": 100.00,
  "total_tax": 21.00,
  "total_gross": 131.00,
  "carrier": "Correos",
  "tracking_code": "AB123456789ES",
  "tracking_url": "https://tracking.example.com/AB123456789ES",
  "payment_method": "card",
  "source_account": null
}

Campi

Campo	Tipo	Descrizione
`schema`	string	Identificatore dello schema e della sua versione, «ph.order/MAGGIORE.MINORE» (oggi ph.order/1.2). Guardare solo il maggiore.
`order_id`	string	Identificatore univoco dell'ordine.
`channel`	string	Codice interno del canale di vendita (ad es. ebay, wllp).
`channel_name`	string	Nome visibile del canale di vendita (ad es. Ebay, Wallapop).
`created_at`	string \| null	Data e ora di creazione dell'ordine, in formato ISO 8601.
`status`	string	Stato dell'ordine (ad es. accepted). Elenco di valori aperto.
`currency`	string \| null	Valuta degli importi dell'ordine in formato ISO 4217 (ad es. EUR).
`original_currency`	string \| null	Valuta in cui ha pagato l'acquirente, in formato ISO 4217. Se è diversa, l'ordine è stato convertito e i suoi importi sono in currency.
`exchange_rate`	number \| null	Unità di original_currency che valeva un'unità di currency al momento della conversione dell'ordine (ad es. 0.8346 sterline per euro); 1 se non è stato convertito.
`customer`	object	Dati dell'acquirente (oggetto; vedi i campi più sotto).
`lines`	array	Righe dell'ordine, una per articolo (elenco di oggetti; vedi i campi più sotto).
`shipping_gross`	number \| null	Importo della spedizione, imposte incluse.
`channel_fees_gross`	number \| null	Commissione che il canale trattiene al venditore per l'ordine (informativo; inclusa in total_gross, il canale la detrae dall'incasso).
`buyer_fees_gross`	number \| null	Costi che l'acquirente paga al canale oltre al prezzo, p. es. la protezione dell'acquirente (informativo; non fa parte di total_gross).
`total_net`	number \| null	Base imponibile totale dell'ordine (senza imposte).
`total_tax`	number \| null	Importo totale delle imposte dell'ordine.
`total_gross`	number \| null	Prezzo di vendita per il venditore, imposte e commissione del venditore incluse (il trasporto può essere incluso o meno a seconda del canale).
`carrier`	string \| null	Corriere della spedizione.
`tracking_code`	string \| null	Codice di tracciamento della spedizione.
`tracking_url`	string \| null	URL di tracciamento della spedizione.
`payment_method`	string \| null	Metodo di pagamento (ad es. card). Elenco di valori aperto.
`source_account`	string \| null	Account di origine nel canale di vendita, se applicabile.
`customer.foreign_id`	string \| null	Identificatore dell'acquirente nel canale di origine.
`customer.first_name`	string \| null	Nome dell'acquirente.
`customer.last_name`	string \| null	Cognome dell'acquirente.
`customer.company_name`	string \| null	Ragione sociale dell'acquirente, se è un'azienda.
`customer.email`	string \| null	Email dell'acquirente.
`customer.tax_number`	string \| null	Identificazione fiscale dell'acquirente (NIF/CIF/VAT).
`customer.phone`	string \| null	Telefono dell'acquirente.
`customer.address`	object	Indirizzo di spedizione dell'acquirente (oggetto; vedi i campi più sotto).
`customer.address.street`	string \| null	Via e numero dell'indirizzo di spedizione.
`customer.address.city`	string \| null	Località dell'indirizzo di spedizione.
`customer.address.province`	string \| null	Provincia o regione dell'indirizzo di spedizione.
`customer.address.postal_code`	string \| null	Codice postale dell'indirizzo di spedizione.
`customer.address.country`	string \| null	Paese dell'indirizzo di spedizione, in formato ISO 3166-1 alpha-2 (ad es. ES).
`lines[].external_id`	string \| null	Identificatore dell'articolo nel catalogo (SKU o referenza).
`lines[].title`	string \| null	Titolo o descrizione dell'articolo.
`lines[].quantity`	integer \| null	Unità dell'articolo in questa riga.
`lines[].line_net`	number \| null	Base imponibile della riga (senza imposte).
`lines[].line_tax`	number \| null	Importo delle imposte della riga.
`lines[].line_gross`	number \| null	Importo della riga, imposte incluse.
`lines[].tax_rate`	number \| null	Aliquota d'imposta della riga in decimale (0.21 = 21 %).

Compatibilità e versioni

Per non dover rimettere mano all'integrazione nelle versioni future, conviene costruire il lettore seguendo queste regole:

Versionamento: il campo schema è ph.order/MAGGIORE.MINORE (oggi ph.order/1.2). Guardare solo il MAGGIORE (l'1) e accettare qualsiasi versione minore.
Versioni pubblicate: 1.0, lo schema iniziale. 1.1 aggiunge buyer_fees_gross e fissa channel_fees_gross come la commissione che il canale addebita al venditore su tutti i canali; su Wallapop conteneva la protezione dell'acquirente, che passa a buyer_fees_gross. 1.2 aggiunge original_currency ed exchange_rate: un ordine pagato in un'altra valuta arriva con gli importi in euro, e questi campi indicano in quale valuta ha pagato l'acquirente e a quale cambio.
Si aggiunge soltanto, non si toglie mai: all'interno della versione maggiore 1 le modifiche sono additive. Si potranno aggiungere nuovi campi (sempre presenti, con null quando non applicabili), ma non si eliminerà, rinominerà né si cambierà il tipo o il significato di un campo esistente. Unica eccezione: quella della 1.1 indicata nelle versioni pubblicate.
Ignorare i campi non riconosciuti: il lettore deve scartarli senza fallire (non validare con additionalProperties: false).
Elenchi di valori aperti: in status, channel, payment_method, currency e original_currency possono comparire nuovi valori; gestire un valore sconosciuto senza rompersi (ad es. come «altro»).
Solo un cambio di versione MAGGIORE (ph.order/2.0) richiederebbe un adattamento, e verrebbe comunicato in anticipo; le versioni minori non esigono alcun cambiamento da parte del consumatore, salvo l'eccezione della 1.1 indicata sopra.

Per validare con un JSON Schema, se ne fornisce uno permissivo per ph.order/1.x che già contempla tutto questo (accetta nuovi campi e qualsiasi versione minore). Per coordinare il cambiamento o richiedere lo schema e i payload di prova, contattare il referente in Portal Hero.