Bestellungen in JSON: Schema ph.order/1.2

Versionierter Bestell-Payload ph.order/1.2: veröffentlichtes JSON-Schema, Kompatibilitätsregeln und Zustellbeispiele.

Wenn ein Verkauf bestätigt wird, wird die Bestellung in der Integration (Webhook, SFTP oder E-Mail) mit diesem kanonischen und versionierten JSON übermittelt. Diese Seite ist die genaue Spezifikation des Formats ph.order/1.2.

Formatregeln

Alle Schlüssel sind immer vorhanden; Schlüssel werden niemals weggelassen.
null bedeutet „unbekannter Wert“; es darf nicht als 0 interpretiert werden (einige Kanäle schlüsseln Steuern nicht pro Position auf).
Die Beträge sind Zahlen mit bis zu 2 Dezimalstellen.
tax_rate ist eine Dezimalzahl: 0.21 entspricht 21 %.
channel ist der interne Code des Kanals (z. B. ebay, wllp) und channel_name sein sichtbarer Name (z. B. Ebay, Wallapop).
total_gross ist der Verkaufspreis für den Verkäufer, einschließlich der Verkäuferprovision: channel_fees_gross (was der Kanal dem Verkäufer davon einbehält) und buyer_fees_gross (was der Käufer dem Kanal zusätzlich zum Preis zahlt, nie Teil von total_gross) sind informativ; shipping_gross (Versand) ebenfalls, und er kann je nach Kanal in total_gross enthalten sein oder nicht (die lines geben die Aufschlüsselung der Ware).

Beispiel-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
}

Felder

Feld	Typ	Beschreibung
`schema`	string	Kennung des Schemas und seiner Version, „ph.order/HAUPT.NEBEN“ (heute ph.order/1.2). Nur auf die Hauptversion achten.
`order_id`	string	Eindeutige Kennung der Bestellung.
`channel`	string	Interner Code des Verkaufskanals (z. B. ebay, wllp).
`channel_name`	string	Sichtbarer Name des Verkaufskanals (z. B. Ebay, Wallapop).
`created_at`	string \| null	Datum und Uhrzeit der Erstellung der Bestellung, im Format ISO 8601.
`status`	string	Status der Bestellung (z. B. accepted). Offene Werteliste.
`currency`	string \| null	Währung der Beträge der Bestellung im Format ISO 4217 (z. B. EUR).
`original_currency`	string \| null	Währung, in der der Käufer bezahlt hat, im Format ISO 4217. Weicht sie ab, wurde die Bestellung umgerechnet und ihre Beträge sind in currency.
`exchange_rate`	number \| null	Einheiten von original_currency, die eine Einheit von currency bei der Umrechnung der Bestellung wert war (z. B. 0.8346 Pfund pro Euro); 1, wenn nicht umgerechnet wurde.
`customer`	object	Daten des Käufers (Objekt; siehe Felder weiter unten).
`lines`	array	Positionen der Bestellung, eine pro Artikel (Liste von Objekten; siehe Felder weiter unten).
`shipping_gross`	number \| null	Betrag des Versands inklusive Steuern.
`channel_fees_gross`	number \| null	Provision, die der Kanal dem Verkäufer für die Bestellung einbehält (informativ; in total_gross enthalten, der Kanal zieht sie von der Auszahlung ab).
`buyer_fees_gross`	number \| null	Gebühren, die der Käufer dem Kanal zusätzlich zum Preis zahlt, z. B. der Käuferschutz (informativ; nicht Teil von total_gross).
`total_net`	number \| null	Gesamte Bemessungsgrundlage der Bestellung (ohne Steuern).
`total_tax`	number \| null	Gesamter Steuerbetrag der Bestellung.
`total_gross`	number \| null	Verkaufspreis für den Verkäufer, inklusive Steuern und Verkäuferprovision (der Versand kann je nach Kanal enthalten sein oder nicht).
`carrier`	string \| null	Transporteur des Versands.
`tracking_code`	string \| null	Sendungsverfolgungscode des Versands.
`tracking_url`	string \| null	Sendungsverfolgungs-URL des Versands.
`payment_method`	string \| null	Zahlungsmethode (z. B. card). Offene Werteliste.
`source_account`	string \| null	Herkunftskonto im Verkaufskanal, sofern zutreffend.
`customer.foreign_id`	string \| null	Kennung des Käufers im Herkunftskanal.
`customer.first_name`	string \| null	Vorname des Käufers.
`customer.last_name`	string \| null	Nachname des Käufers.
`customer.company_name`	string \| null	Firmenname des Käufers, sofern es sich um ein Unternehmen handelt.
`customer.email`	string \| null	E-Mail-Adresse des Käufers.
`customer.tax_number`	string \| null	Steuernummer des Käufers (NIF/CIF/VAT).
`customer.phone`	string \| null	Telefon des Käufers.
`customer.address`	object	Lieferadresse des Käufers (Objekt; siehe Felder weiter unten).
`customer.address.street`	string \| null	Straße und Hausnummer der Lieferadresse.
`customer.address.city`	string \| null	Ort der Lieferadresse.
`customer.address.province`	string \| null	Provinz oder Region der Lieferadresse.
`customer.address.postal_code`	string \| null	Postleitzahl der Lieferadresse.
`customer.address.country`	string \| null	Land der Lieferadresse, im Format ISO 3166-1 alpha-2 (z. B. ES).
`lines[].external_id`	string \| null	Kennung des Artikels im Katalog (SKU oder Referenz).
`lines[].title`	string \| null	Titel oder Beschreibung des Artikels.
`lines[].quantity`	integer \| null	Einheiten des Artikels in dieser Position.
`lines[].line_net`	number \| null	Bemessungsgrundlage der Position (ohne Steuern).
`lines[].line_tax`	number \| null	Steuerbetrag der Position.
`lines[].line_gross`	number \| null	Betrag der Position inklusive Steuern.
`lines[].tax_rate`	number \| null	Steuersatz der Position als Dezimalzahl (0.21 = 21 %).

Kompatibilität und Versionen

Um die Integration bei künftigen Versionen nicht erneut anfassen zu müssen, sollte der Reader nach diesen Regeln aufgebaut werden:

Versionierung: Das Feld schema ist ph.order/HAUPT.NEBEN (heute ph.order/1.2). Achten Sie nur auf die HAUPT-Version (die 1) und akzeptieren Sie jede Nebenversion.
Veröffentlichte Versionen: 1.0, das ursprüngliche Schema. 1.1 fügt buyer_fees_gross hinzu und legt channel_fees_gross in allen Kanälen als die Provision fest, die der Kanal dem Verkäufer berechnet; bei Wallapop enthielt es den Käuferschutz des Käufers, der nach buyer_fees_gross wandert. 1.2 fügt original_currency und exchange_rate hinzu: Eine in einer anderen Währung bezahlte Bestellung kommt mit Beträgen in Euro an, und diese Felder geben an, in welcher Währung der Käufer bezahlt hat und zu welchem Kurs.
Es wird nur hinzugefügt, niemals entfernt: Innerhalb der Hauptversion 1 sind die Änderungen additiv. Es können neue Felder hinzugefügt werden (immer vorhanden, mit null, wenn sie nicht zutreffen), aber ein bestehendes Feld wird niemals entfernt, umbenannt oder in Typ oder Bedeutung geändert. Einzige Ausnahme: die von 1.1, bei den veröffentlichten Versionen beschrieben.
Nicht erkannte Felder ignorieren: Der Reader muss sie verwerfen, ohne zu scheitern (nicht mit additionalProperties: false validieren).
Offene Wertelisten: In status, channel, payment_method, currency und original_currency können neue Werte auftauchen; behandeln Sie einen unbekannten Wert, ohne zu brechen (z. B. als „sonstiges“).
Nur eine Änderung der HAUPT-Version (ph.order/2.0) würde eine Anpassung erfordern, und sie würde rechtzeitig angekündigt; die Nebenversionen erfordern keinerlei Änderung seitens des Konsumenten, abgesehen von der oben genannten Ausnahme in 1.1.

Zur Validierung mit einem JSON Schema wird ein lockeres für ph.order/1.x bereitgestellt, das all dies bereits berücksichtigt (akzeptiert neue Felder und jede Nebenversion). Um die Änderung zu koordinieren oder das Schema und Test-Payloads anzufordern, wenden Sie sich an den Ansprechpartner bei Portal Hero.