Die Bestell-API deckt den vollständigen Bestellzyklus ab — vom Abruf eingehender Aufträge aus ITscope über die Erstellung neuer Bestellungen bis hin zum Senden, Tracking und Dokumentenabruf. Sie besteht aus zwei Bereichen:

• Legacy-Endpunkte (/orders/sales/*, /orders/purchase/*) für den klassischen Auftragsabruf und die direkte Bestellübermittlung an ITscope-Distributoren.
• V2-Endpunkte (/orders/v2/*) für den modernen, zustandsbehafteten Bestellfluss mit eindeutiger Bestell-ID, Statusverfolgung und Dokumentenabruf.

---

Aufträge abrufen (Legacy)

1. Verkaufsaufträge abrufen

Holt eingehende Verkaufsaufträge (Sales Deals) aus ITscope ab — typischerweise zur Synchronisation in das eigene ERP.

Anwendungsfall: Eingegangene Kundenaufträge aus dem ITscope-Marktplatz periodisch in Odoo importieren.

Endpoint:

POST /orders/sales/fetch

Request-Body:

curl-Beispiel:

curl -X POST "https://api.connector.mateit.de/api/v1/orders/sales/fetch" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "from_date": "2026-05-01T00:00:00Z" }'

Antwort (Auszug):

{
  "deals": [
    {
      "deal_id": "SD-100245",
      "status": "OPEN",
      "created_at": "2026-05-12T10:21:00Z",
      "buyer": { "name": "Beispiel GmbH" },
      "items": [
        { "puid": "12345678", "quantity": 2 }
      ]
    }
  ]
}

---

2. Einkaufsbestellungen abrufen

Analog zu sales/fetch, jedoch für Einkaufsbestellungen (Purchase Deals), die Sie selbst bei ITscope-Distributoren ausgelöst haben.

Anwendungsfall: Synchronisation des aktuellen Bestellstatus eigener Einkaufsbestellungen in das ERP.

Endpoint:

POST /orders/purchase/fetch

curl-Beispiel:

curl -X POST "https://api.connector.mateit.de/api/v1/orders/purchase/fetch" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "from_date": "2026-05-01T00:00:00Z" }'

---

3. Bestellung an ITscope übermitteln

Sendet eine Einkaufsbestellung direkt an einen ITscope-Distributor. Dieser Endpunkt überträgt die Bestellung ohne vorgelagerten Anlage-Schritt.

Anwendungsfall: Schnelle Übermittlung einer fertigen Bestellung an einen ausgewählten Distributor.

Endpoint:

POST /orders/purchase/submit

Request-Body (Auszug):

curl-Beispiel:

curl -X POST "https://api.connector.mateit.de/api/v1/orders/purchase/submit" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "distributor_id": "1001",
        "items": [{ "puid": "12345678", "quantity": 1 }],
        "delivery_address": { "name": "Beispiel GmbH", "city": "Berlin" },
        "external_reference": "PO-2026-000123"
      }'

---

Bestellungen V2 (empfohlen)

Die V2-Endpunkte bilden den zweistufigen Bestellprozess ab: zunächst wird eine Bestellung im Connector angelegt (create) und kann anschließend gezielt an ITscope abgesendet (send) werden. Jede Bestellung erhält eine eigene id, über die Status, Details und Dokumente abrufbar sind.

4. Neue Bestellung anlegen

Legt eine Bestellung im Connector an — sie ist damit persistiert, aber noch nicht an ITscope übermittelt.

Anwendungsfall: Mehrstufige Freigabeprozesse, Vorbereitung mehrerer Bestellungen vor der eigentlichen Absendung.

Endpoint:

POST /orders/v2/create

Request-Body (Auszug):

curl-Beispiel:

curl -X POST "https://api.connector.mateit.de/api/v1/orders/v2/create" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "distributor_id": "1001",
        "items": [{ "puid": "12345678", "quantity": 1 }],
        "delivery_address": { "name": "Beispiel GmbH", "city": "Berlin" },
        "external_reference": "PO-2026-000123"
      }'

Antwort (Auszug):

{
  "id": "ord_01HXYZ...",
  "status": "DRAFT",
  "created_at": "2026-05-31T08:14:00Z"
}

---

5. Bestellung an ITscope absenden

Sendet eine zuvor angelegte Bestellung tatsächlich an ITscope. Erst dieser Schritt löst die Übermittlung an den Distributor aus.

Anwendungsfall: Finaler Bestellabschluss nach interner Freigabe oder Plausibilitätsprüfung.

Endpoint:

POST /orders/v2/send

Request-Body:

curl-Beispiel:

curl -X POST "https://api.connector.mateit.de/api/v1/orders/v2/send" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ord_01HXYZ..." }'

---

6. Alle Bestellungen auflisten

Liefert eine paginierte Übersicht aller Bestellungen des Accounts.

Anwendungsfall: Bestellübersicht im ERP-System, Reporting und Reconciliation.

Endpoint:

GET /orders/v2/list

Parameter:

curl-Beispiel:

curl -X GET "https://api.connector.mateit.de/api/v1/orders/v2/list?status=SENT&limit=25" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

7. Bestelldetails abrufen

Liefert eine einzelne Bestellung inklusive aller Positionen, Lieferadresse und Metadaten.

Anwendungsfall: Detailansicht einer Bestellung, Anzeige im Kundenportal oder im ERP.

Endpoint:

GET /orders/v2/{id}

curl-Beispiel:

curl -X GET "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ..." \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

8. Bestellstatus abfragen

Liefert den aktuellen Status einer Bestellung in kompakter Form — ideal für Polling oder Statusanzeigen.

Anwendungsfall: Aktuellen Liefer- und Bearbeitungsstatus im ERP oder Kundenportal anzeigen.

Endpoint:

GET /orders/v2/{id}/status

curl-Beispiel:

curl -X GET "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ.../status" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Antwort (Auszug):

{
  "id": "ord_01HXYZ...",
  "status": "SHIPPED",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "updated_at": "2026-05-31T08:14:00Z"
}

---

9. Bestelldokumente abrufen

Liefert die zur Bestellung verfügbaren Dokumente: Auftragsbestätigung, Rechnung und Lieferschein — sofern vom Distributor bereitgestellt.

Anwendungsfall: Dokumente im Kundenportal verfügbar machen oder automatisch in die ERP-Dokumentenablage übernehmen.

Endpoint:

GET /orders/v2/{id}/documents

curl-Beispiel:

curl -X GET "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ.../documents" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Antwort (Auszug):

{
  "documents": [
    {
      "type": "ORDER_CONFIRMATION",
      "filename": "AB-2026-000123.pdf",
      "download_url": "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ.../documents/ab.pdf"
    },
    {
      "type": "INVOICE",
      "filename": "RE-2026-000123.pdf",
      "download_url": "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ.../documents/re.pdf"
    },
    {
      "type": "DELIVERY_NOTE",
      "filename": "LS-2026-000123.pdf",
      "download_url": "https://api.connector.mateit.de/api/v1/orders/v2/ord_01HXYZ.../documents/ls.pdf"
    }
  ]
}

---

Hinweise

---

Weiterführende Seiten

• Authentifizierung — API-Keys, Header und Rate-Limits
• Produktsuche & Katalog — Produkt- und Preisabfragen vor der Bestellung
• Webhooks — Asynchrone Events zu Status- und Lieferänderungen
• Fehlercodes — HTTP-Statuscodes und Fehlerbehandlung