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
- Bestellnummer max 18 Zeichen lang
- 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
- Bei Projektbestellungen: KEINE Validierung, ob die angegebene Projektnummer in der auf ITscope.com eingerichteten Projektliste enthalten ist.
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
Abschicken einer Test Order an den ITscope Partner Test Lieferant
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.
Hinweise zur Freischaltung vom ITscope Partner Test Lieferanten können Sie unter folgenden Hilfe Eintrag einsehen: https://guide.itscope.com/kb/itscope-partner-test/
Ob der Testlieferant freigeschaltet ist, kann ganz einfach auf 2 Arten geprüft werden:
- Auf der ITscope Plattform: wenn bei Aufruf vom Sortimentslink der Lieferant „ITscope Partner-Test for test orders“ als einer der Bezugsquellen sichtbar ist (inkl. Preis und Bestand).
- Direkt über die API per API-Key kann eine Liste aller Distributoren geladen werden, dort sollte der Lieferant vorhanden sein.
Bsp: https://api.itscope.com/2.0/business/deals/send/10000735
Antwortdokumente automatisch erstellen
Damit Sie auch realitätsnah testen können, ob Ihr System auch Antwortdokumente von uns (Auftragsbestätigung, Lieferavis und Rechnung) verarbeiten kann, haben Sie die Möglichkeit, die zu generierenden Dokumente und deren Anzahl festzulegen.
Hinweis: Die Anzahl der zu generierenden Dokumente ist jeweils auf 6 begrenzt.
Dies können Sie über die Bestellnummer bzw. Order-ID steuern. Hängen Sie dazu einfach an die Bestellnummer ein „§“-Zeichen dran, gefolgt von den Parametern, die unten aufgeführt sind. Die Parameter werden wie folgt angegeben:
§<Kürzel1><Anzahl1><Kürzel2><Anzahl2> usw.
Folgende Kürzel führen zur Generierung des entsprechenden Dokuments:
| Kürzel | Aktion | Generiert Dokument |
|---|---|---|
| R | Auftrag ablehnen (reject) | ORDERRESPONSE |
| C | Auftrag bestätigen (confirm) | ORDERRESPONSE |
| A | Als verschickt markieren (advise) | DISPATCHNOTIFICATION |
| I | Als berechnet markieren (invoice) | INVOICE |
Groß- und Kleinschreibung muss hierbei nicht beachtet werden.
Beispiele einer Bestellnummer:
TEST180620§C3A1I2
Unser System wird für eine Bestellung mit dieser Bestellnummer sofort 3 Auftragsbestätigungen (C3), 1 Lieferavis (A1) und 2 Rechnungen (I2) ausstellen.
TEST180620§R1
Unser System wird für eine Bestellung mit dieser Bestellnummer 1 Antwortdokument (R1) ausstellen, in diesem die Bestellung abgelehnt wird.
TEST180620
Ohne Angabe von Parametern wird einfach nur die Test-Bestellung ausgelöst, ohne Antwortdokumente zu generieren.
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