Bestellungen

Käufer platzieren Bestellungen in ihrem Handelsportal. Lieferanten bearbeiten die Rechnungen. Sie können optional Stripe-hosted Kunden-Zahlungen nach Bestätigung des Endbetrags anbieten. Bestellanfragen und Handelskredit bleiben verfügbar. Nutzen Sie die API, um Bestellungen in Ihr ERP-System oder Buchhaltungssystem zu laden und deren Status aktuell zu halten.

BestellstatusLink zu diesem Abschnitt#

Mitarbeiter können Zwischenschritte beim Auswählen überspringen. Das Zurückgehen oder Neustarten einer abgeschlossenen oder stornierten Bestellung erfordert einen internen correctionReason. Die vorherige Geschichte bleibt erhalten. Korrekturen verändern niemals den Zahlungsstatus. Lesen Sie revision und senden Sie expectedRevision mit Updates, um veraltete Änderungen abzulehnen.

Eine Bestellung für einen Kunden erstellenLink zu diesem Abschnitt#

POST/api/v1/orders/previewSchreibschlüssel

Erfordert orders.create und Zugriff auf den Kunden. Senden Sie customerAccountId und lines, die productId und eine ganze Zahl qty (1 bis 1.000.000) enthalten. Wählen Sie jedes gewöhnliche Produkt maximal 100 Mal pro Zeile. Eine Zeile kann optionale configuration enthalten, die die zurückgegebene Messung und Auswahl-Schlüssel enthalten; verschiedene Konfigurationen eines Produkts bleiben getrennt. Ein optionaler lineKey gibt jeder Vorschauzeile eine stabile Caller-Identität. Ein zusätzlicher additionalDiscountBp benötigt Preisberechtigung und discountReason. Konfigurierte Bestell-Lesungen enthalten ein unveränderliches configuration-Snapshot mit Eingaben, Spezifikation, Version, Rundung und Gebühren. Die Vorschau gibt total, fingerprint, aktuelle Kundenpreise und Währung zurück. Angehaltene Konten, nicht verfügbare Produkte und Mengen unter dem Minimum werden abgelehnt. Ein Preis-Katalog allein akzeptiert weiterhin eine Bestellung, die hier eingegeben wird; Käufer können keine selbstständig senden, solange dies deaktiviert ist.

POST/api/v1/ordersSchreibschlüssel

Senden Sie denselben Kunden und Zeilen, expectedTotal aus der Vorschau, expectedBasket auf seinen Fingerabdruck gesetzt und eine neue UUID requestKey. Optionale poNumber (60 Zeichen) und kundensichtbare notes (2.000 Zeichen) werden unterstützt. Wiederholen Sie genau dasselbe Anfrage und Schlüssel nach einer unklaren Antwort: ein erfolgreicher Wiederholungsversuch gibt die ursprüngliche Bestellung zurück, anstatt eine weitere zu erstellen. Geänderte Preise erfordern eine weitere Überprüfung. Das Ergebnis ist placed mit orderId und reference, oder prices_changed, empty oder unavailable.

Mitarbeiter handeln unter ihrer eigenen Identität. Der Warenkorb des Kunden bleibt unverändert. Kunden-E-Mail-Kontakte können eine Kopie erhalten; dies verursacht keine Zahlung. Der Verkäufer hat standardmäßig Erstellungsrechte; Verarbeitungs- und Lieferupdates erfordern die separate orders.process-Berechtigung.

Lieferung und VerfolgungLink zu diesem Abschnitt#

PATCH/api/v1/orders/{id}/deliverySchreibschlüssel

Erfordert orders.process. Senden Sie deliveryMethod: unspecified, courier, own_delivery oder collection. Optionale courierName (100 Zeichen), trackingReference (120 Zeichen) und trackingUrl (1.000 Zeichen) sind kundensichtbar. Tracking-Links müssen HTTPS verwenden, ohne eingebettete Anmeldeinformationen. Weggelassene optionale Details löschen sie. Senden Sie expectedRevision aus der aktuellen Bestellung. Es gibt einen Lieferprotokoll pro Bestellung; Carrier-Integrationen und geteilte Sendungen sind nicht enthalten. Leere Lieferdetails bedeuten niemals eigene Lieferung.

Bestellungen auflistenLink zu diesem Abschnitt#

GET/api/v1/orders

Neueste Bestellungen zuerst. Die Liste umfasst die 200 neuesten Bestellungen, die Ihren Filtern entsprechen. Um neue Bestellungen abzuholen, abfragen Sie mit status=new.

curl "https://tradecatalog.app/api/v1/orders?status=new" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/orders?status=new', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: orders } = await res.json()

{
  "data": [
    {
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "reference": "SO-000142",
      "status": "new",
      "total": 31460,
      "currency": "GBP",
      "poNumber": "PO-88231",
      "createdAt": "2026-09-27T07:48:12.000Z",
      "customer": "Oakfield Joinery"
    }
  ],
  "nextOffset": null
}

Einen Auftrag abrufenLink zu diesem Abschnitt#

GET/api/v1/orders/{id}

Der Auftrag mit seinen Zeilen und Statusverlauf.

curl https://tradecatalog.app/api/v1/orders/5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch(`https://tradecatalog.app/api/v1/orders/${orderId}`, {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: order } = await res.json()

{
  "data": {
    "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "customerAccountId": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
    "placedBy": "Fq3L0cZ7tN1pW9aYx2Rk",
    "reference": "SO-000142",
    "poNumber": "PO-88231",
    "notes": "Deliver to the Hebden Road site, gate 2.",
    "status": "new",
    "cancelReason": null,
    "currency": "GBP",
    "total": 31460,
    "createdAt": "2026-09-27T07:48:12.000Z",
    "updatedAt": "2026-09-27T07:48:12.000Z",
    "customer": { "name": "Oakfield Joinery", "accountCode": "OAK01" },
    "lines": [
      {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "orderId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
        "productId": "3f8a2c1e-9b4d-4e6f-a7c8-1d2e3f4a5b6c",
        "sku": "HX-8510",
        "name": "Hex bolt M10 x 50 zinc",
        "unitLabel": "Box of 100",
        "qty": 20,
        "unitPrice": 1573,
        "listPrice": 1850,
        "priceLabel": "Brand discount −15%",
        "lineTotal": 31460
      }
    ],
    "events": [
      {
        "status": "new",
        "note": null,
        "createdAt": "2026-09-27T07:48:12.000Z",
        "actor": "Sam Patel"
      }
    ]
  }
}

Auftrag aktualisieren oder korrigierenLink zu diesem Abschnitt#

PATCH/api/v1/orders/{id}Schreibschlüssel

Ändert den Status einer Bestellung. Gibt die aktualisierte Bestellung in der gleichen Form wie GET /orders/{id} zurück.

• Normale Weiterbewegungen folgen den Erfüllungsstufen oben. Andere Bewegungen erfordern einen privaten Korrektionsgrund; eine wiederholte aktuelle Statusmeldung hat keine Auswirkung.
• Stornieren erfordert einen note, der dem Käufer als Grund angezeigt wird.
• Statusänderungen können E-Mails an Kundenkontakte senden, einschließlich der öffentlichen Notiz. Eine generierte E-Mail beweist keine Lieferung.
• Die Änderung wird im Bestellverlauf gegen die Person aufgezeichnet, die den Schlüssel erstellt hat.

curl -X PATCH https://tradecatalog.app/api/v1/orders/5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "dispatched", "note": "DPD tracking 1554 2210 0931" }'

const res = await fetch(`https://tradecatalog.app/api/v1/orders/${orderId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'acknowledged' }),
})
const { data: order } = await res.json()

Das Wiederholen eines PATCH, das bereits erfolgreich war, gibt 400 invalid_request zurück, da der Auftrag weitergegangen ist. Prüfen Sie den Auftragsstatus, bevor Sie dies als Fehler behandeln.

Nicht verfügbarLink zu diesem Abschnitt#

Die API kann keine Aufträge für einen Käufer platzieren oder die Zeilen, Mengen oder Preise eines Auftrags ändern. Käufer platzieren Aufträge in ihrem Handelsportal; Änderungen an einem Auftrag werden mit dem Kunden abgesprochen und in Ihrem eigenen System abgerechnet.

Auftragslisten enthalten auch paymentStatus: null für gewöhnliche Kontobedingungen oder den optionalen Stripe-Zahlungsstatus. Die Erfüllungsstatus ist separat und beweist niemals die Zahlung. Die Auftragsdetailsseite ist der Ort, um den endgültigen bestätigten Gesamtbetrag zu überprüfen und die Zahlung zu genehmigen. Die API kann keine Zahlung erstellen oder genehmigen.

internalNote (2.000 Zeichen) und correctionReason (1.000 Zeichen) sind Felder für das Personal. note bleibt öffentlich, einschließlich alter Notizen. Senden Sie expectedRevision, um eine gleichzeitige Bearbeitung mit einer ungültigen Anfrage abzulehnen. Staff-API-Lesungen enthalten private Geschichte; Käufer-Tools und Portal-Lesungen exkludieren die Identitäten des Personals und die privaten Felder. Das Stornieren erfordert immer einen öffentlichen Grund und die Rücknahme oder vollständige Erstattung einer ausstehenden Zahlung.