Allgemeines

  • Als Format für Bestellungen wird der industriestandard OpenTrans 2.1 genutzt.
  • zum Download der OpenTrans 2.1 Dokumentation und Beispieldateien
  • Der MimeType muss application/xml sein.
  • Abschicken funktioniert nur über HTTP POST.
  • Im POST Body darf nur die ORDER im OpenTrans 2.1 Format sein und als UTF-8 kodiert.
  • Eine Bestellung kann nur direkt an einen einzelnen Distributor gesendet werden, pro Distributor muss also jedesmal eine neue OpenTrans Order angelegt werden


Eine Liste aller Distributoren und deren Stammdaten kann per API abgerufen werden. Die Supplier->ID ist die in ITscope eindeutige Nummer des Distributors.

Die Bestellung unterläuft etlichen Validierungen, bevor diese tatsächlich abgeschickt würde

  • Validierung auf gültiges OpenTrans 2.1 Format
  • Validierung, ob die einzelnen Position auch in unserem Katalog für den oben genannten Distributor vorhanden sind
  • KEINE Validierung auf gültiger Preis oder Verfügbarkeit
  • Validierung, ob die Summe der einzelnen Positionen und Mengen mit der Endsumme übereinstimmen.


Beim Absenden kann es natürlich ebenso zu Fehler kommen oder auch zu synchronen Fehlermeldungen vom System des Distributors.

Die API gibt immer entsprechende Fehlermeldungen zurück und HTTPCodes >400

Wird eine Bestellung vollständig abgeschickt, wird der HTTPCode 200 gesendet und ein Response mit folgenden Daten:

  • Die neue OrderID
  • Der aktuelle Status der Bestellung

 

Aufbau der Order

Unser System empfängt Bestellungen ausschließlich in einem xsd-validen OpenTrans Version 2.1 Format.

Bestellnummer (ORDER_ID):

  • Diese generieren wir für jeden API Import neu und kopieren die vom Fremdsystem an uns gesendete Kundenauftragsnummer in das Feld CUSTOMER_ORDER_REFERENCE->ORDER_ID
  • d.h. in der an uns gesendet ORDER kopieren wir die ORDER_ID nach CUSTOMER_ORDER_REFERENCE->ORDER_ID und generieren in die ORDER_ID eine ITscope Bestellnummer


Teilnehmer (PARTIES):

  • Distributor als supplier mit der PartyID die in Ihrem System für den Distributor hinterlegt ist.
  • Käufer also Rechnungsempfänger PARTY_ROLE->buyer mit der PartyID die in Ihrem System als Kundennummer für den Besteller beim Distributor hinterlegt ist.
  • Lieferungsempfänger delivery, kann sich vom Käufer unterscheiden, eventuell wegen Dropshipment

Teillieferung (PARTIAL_SHIPMENT_ALLOWED):

  • Dieses Feld setzen wenn die Bestellung in Teillieferungen versendet werden soll
  • Das Feld wird in OpenTrans als Muss Feld definiert, daher mit false vorbelegen


Dropshipment (UDX.DROPSHIPMENT):

  • Dieses Feld setzen wenn Dropshipment gewünscht ist. Muss vorher mit dem Distributor abgestimmt sein.
  • Die UDX Felder sind optionale Felder

 

Endkundenbestellnummer (UDX.BUYORDERID.ENDCUSTOMER):

  • Dieses Feld ist die Nummer die der Endkunde als Bestellnummer bekommt
  • Die UDX Felder sind optionale Felder


Eigene Bestellnummer (UDX.BUYORDERID.SELFASSIGNED):

  • Dieses Feld ist die Nummer, die der Käufer für sich selbst vergeben kann (interne Firmen- Bestellnummer)
  • Die UDX Felder sind optionale Felder


Distributor Produktnummer (SUPPLIER_PID type="supplier_specific"):

  • Anhand dieser Nummer suchen wir nach dem Artikel, der bestellt werden soll.

 

Abschicken einer TestOrder

An das Live System können über die API Testbestellungen an einen von ITscope gepflegten Testlieferanten mit Namen ITscope Partner Test gesendet werden. Dieser Testlieferant hat die LieferantenID 10000735. Sie benötigen eine extra Freischaltung von ITscope, um diesen Testlieferanten sehen zu können und somit auch dort bestellen zu können.

Ob der Testlieferant freigeschaltet ist, kann ganz einfach auf 2 Arten geprüft werden:

Bsp: https://api.itscope.com/2.0/business/deals/send/10000735

 

Abschicken einer Order an einen Lieferanten

Das Bestelldokument muss wie in den weiter oben genannten Abschnitten erstellt, validiert und dann an den jeweiligen Distributor anhand dessen ID versendet werden.

Das Versenden muss über HTTP POST erfolgen und der Inhalt des POST ist die reine ORDER als XML. Der Content-Type des Posts sollte in der Form gesetzt sein application/xml;charset=UTF-8.

Bsp: https://api.itscope.com/2.0/business/deals/send/10000136

Haben Sie Fragen? Anfrage einreichen