API für eigene Kanäle

Ein eigener Kanal lässt deinen eigenen Onlineshop, dein ERP oder dein Lagerverwaltungssystem Bestellungen direkt an Zippendo senden, wenn es dafür keine fertige Verbindung gibt. Diese Seite behandelt jedes Bedienelement im Fenster zum Erstellen und in den Einstellungen des Kanals und wie ein Entwickler eine Bestellung sendet. Den Ablauf zum Durchklicken findest du unter Verkaufskanäle verbinden. Die vollständige Referenz der Nutzdaten ist Eigene Kanäle. Klicke in der Seitenleiste auf Verkaufskanäle und dann auf den Tab Katalog. Die Karte Eigener Kanal lautet Deinen eigenen Onlineshop oder dein ERP-System verbinden. Ihre Schaltfläche ist Kanal erstellen.

Kanal erstellen

Klicke auf Kanal erstellen. Das Fenster Eigenen Kanal erstellen öffnet sich: Ein Verkaufskanal für deinen eigenen Onlineshop oder dein ERP-System.

Feld	Erforderlich	Was du eingibst
Kanalname	Ja	Ein Name, den du wiedererkennst, zum Beispiel „Mein Onlineshop“. Kanal erstellen bleibt inaktiv, bis du einen eingibst.
Marke	Nein	Wird nur angezeigt, wenn deine Organisation Marken hat. Bestellungen aus diesem Kanal gehören zu dieser Marke.

Klicke auf Kanal erstellen (es zeigt Wird erstellt…). Du siehst Verkaufskanal erstellt, und Zippendo öffnet die Einstellungen des neuen Kanals. Siehst du Der Verkaufskanal konnte nicht erstellt werden, versuch es noch einmal. Abbrechen schließt das Fenster.

Bestellempfang

Die Einstellungsseite trägt als Überschrift den Namen des Kanals und Deine eigene Integration: Sende Bestellungen an die Empfangs-URL oder nutze die API und die SDKs. Dokumentation ansehen öffnet die Referenz Eigene Kanäle.

Die Karte Bestellempfang: Dein System sendet signierte Bestellungen an die Empfangs-URL unten. Signiere den unveränderten Body jeder Anfrage mit HMAC-SHA256 und dem Signaturschlüssel.

Bedienelement	Was es bewirkt
Empfangs-URL	Die Adresse, an die dein System Bestellungen sendet, in der Form `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Kopiere sie aus deinem eigenen Kanal. Kopieren zeigt In die Zwischenablage kopiert. oder Konnte nicht in die Zwischenablage kopiert werden.
Schlüssel generieren	Erstellt den Signaturschlüssel. Zeigt Wird generiert… und dann Signaturschlüssel generiert. oder Der Signaturschlüssel konnte nicht generiert werden.
Schlüssel ersetzen	Ersetzt einen bestehenden Schlüssel. Zippendo bittet dich um Bestätigung: Dein System wird abgelehnt, bis es mit dem neuen Schlüssel signiert.
Widerrufen	Schaltet den Schlüssel ab. Jede Bestellung, die dein System sendet, wird abgelehnt, bis du einen neuen Schlüssel generierst. Zeigt Signaturschlüssel widerrufen. oder Der Signaturschlüssel konnte nicht widerrufen werden.
Aktiver Signaturschlüssel, erstellt am	Gefolgt von Datum und Uhrzeit, zu der der aktuelle Schlüssel erstellt wurde.

Der Kanal nimmt Bestellungen erst an, wenn ein Signaturschlüssel existiert. Es gibt keinen separaten Schalter, um den Empfang einzuschalten. Nach Schlüssel generieren oder Schlüssel ersetzen wird der Schlüssel einmal angezeigt:

Bestellempfang mit dem einmalig angezeigten Signaturschlüssel, Kopieren, Widerrufen und Schlüssel ersetzen — Kopiere den Signaturschlüssel jetzt. Er wird nur einmal angezeigt

Kopiere den Schlüssel jetzt. Er wird nur einmal angezeigt. Wenn du ihn später ersetzt, funktioniert der aktuelle Schlüssel sofort nicht mehr. Der Schlüssel beginnt mit zwhs_. Bewahre ihn in der Konfiguration deines Systems auf.

Eine Bestellung senden

Sende ein POST an die Empfangs-URL mit zwei Headern:

Header	Wert
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` oder `ping`
`X-Zippendo-Signature`	HMAC-SHA256 des unveränderten Request-Body, hexadezimal kodiert, mit dem Signaturschlüssel als Schlüssel

order.created und order.updated erstellen oder aktualisieren beide die Bestellung anhand ihrer externalId. Der Body von order.cancelled ist { "externalId": "…" }. ping gibt 200 { "received": true } zurück, ohne etwas zu ändern.

import crypto from "node:crypto"

const body = JSON.stringify(order)
const signature = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
  .update(body)
  .digest("hex")

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Zippendo-Topic": "order.created",
    "X-Zippendo-Signature": signature
  },
  body
})

Erforderliche Felder der Nutzdaten: externalId, orderNumber und orderLines (mindestens eine Position mit name und quantity). Optional: customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle und serviceCode. Vollständige Feldtabelle: Eigene Kanäle.

Status	Bedeutung
`200`	Angenommen und verarbeitet
`400`	Fehlendes oder unbekanntes Topic, Nutzdaten, die die Validierung nicht bestanden haben, oder Kanal aktiviert ist aus
`401`	Signaturprüfung fehlgeschlagen: falscher Schlüssel, fehlender Header oder noch kein Schlüssel generiert
`404`	Unbekannter Kanal
`429`	Zu viele Bestellungen auf einmal. Versuch es nach der Wartezeit `Retry-After` erneut
`5xx`	Die Verarbeitung ist fehlgeschlagen. Versuch es erneut: Dieselbe Bestellung noch einmal zu senden ist sicher

Du bevorzugst Anfrage und Antwort? Erstelle Bestellungen mit POST /orgs/{orgId}/orders, übergib orderChannelId und nutze ein API-Token. Eine zweite Bestellung mit derselben externalId im selben Kanal gibt 409 ORDER_EXISTS zurück. Um Sendungsnummern und Statusänderungen zurückzubekommen, abonniere die Webhooks deiner Organisation (shipment.dispatched, tracking.updated). Ein eigener Kanal hat keinen eigenen Rückruf für die Sendungsverfolgung und keinen Bildschirm zur Zuordnung von Versandarten. Eine Bestellung, die du sendest, erscheint unter Bestellungen. Ihr Status kann Fehler sein, wenn Zippendo die Bestellung importiert hat, aber keine versandfertige Sendung erstellen konnte, zum Beispiel weil keine Versandregel gepasst hat oder die Adresse unvollständig ist. Die Bestellung gehört trotzdem zum Kanal.

Liste der Bestellungen mit einer Bestellung, die über einen eigenen Kanal eingegangen ist — Eine von deinem System gesendete Bestellung auf der Seite Bestellungen

Abläufe

Einstellung	Gespeichert	Was sie bewirkt
Kanal aktiviert	Sofort	Schaltet den Kanal ein oder aus. Ist er ausgeschaltet, lehnt Zippendo jede Bestellung an diesen Kanal ab.
Sendungen automatisch versenden	Mit Änderungen speichern	Versendet die Sendung automatisch an den Versanddienstleister, sobald eine eingehende Bestellung zu einer Versandregel passt. Standardmäßig aus.
Marke	Sofort	Bestellungen aus diesem Kanal gehören zu dieser Marke. Die Liste erscheint nur, wenn deine Organisation Marken hat.
Standard-Absenderadresse	Mit Änderungen speichern	Der Absender für Sendungen, wenn keine Versandregel zur Bestellung passt. Ist noch keine gespeichert, steht in der Liste Noch keine Adressen.
Letzte Bestellung	Nur lesbar	Wann der Kanal zuletzt eine Bestellung empfangen hat, oder Nie.

Änderungen speichern (Wird gespeichert…) speichert Sendungen automatisch versenden und Standard-Absenderadresse. Du siehst Verkaufskanal aktualisiert oder Der Verkaufskanal konnte nicht aktualisiert werden.

Einen Kanal ausschalten

Schalte Kanal aktiviert aus. Auf dem Tab Verbunden steht in der Zeile des Kanals in der Karte Eigener Kanal dann Deaktiviert. Eigene Kanäle bleiben immer auf dem Tab Verbunden und werden nie zu übrig gebliebenen Kanälen.

Seite Verkaufskanäle mit einem als Deaktiviert markierten eigenen Kanal — Ein eigener Kanal, der ausgeschaltet ist

Übrig gebliebene Shopify- oder WooCommerce-Kanäle, markiert mit Keine aktive Verbindung und Getrennt, sind etwas anderes. Siehe Einstellungen für Verkaufskanäle.

Löschen

Unter Gefahrenbereich findest du Kanal löschen: Diesen eigenen Kanal löschen. Deine Integration kann dann keine Bestellungen mehr an ihn senden.

Klicke auf Löschen und bestätige: Diesen eigenen Kanal löschen? Seine Empfangs-URL nimmt ab sofort keine Bestellungen mehr an. Du siehst Verkaufskanal gelöscht oder Der Verkaufskanal konnte nicht gelöscht werden.

Verkaufskanäle verbinden

Erstelle den Kanal aus dem Katalog und öffne dann Bestellungen.

Referenz zu eigenen Kanälen

Vollständige Nutzdaten, Stornierung, Ping und REST-Beispiele.

Einstellungen für Verkaufskanäle

Die Seite Verkaufskanäle, Marken und übrig gebliebene Kanäle.

API-Token erstellen

Ein Token für POST /orgs/{orgId}/orders statt signierter Pushes.

Überblick

Sendungen

Bestellungen & Verkaufskanäle

Versanddienstleister

Versanddienstleister verbinden

Integration verbinden

Drucken

Automatisierung

Konto

Suche & Dashboard

API & Ereignisse

API für eigene Kanäle

Kanal erstellen

Bestellempfang

Eine Bestellung senden

Abläufe

Einen Kanal ausschalten

Löschen

Verwandte Themen

Verkaufskanäle verbinden

Referenz zu eigenen Kanälen

Einstellungen für Verkaufskanäle

API-Token erstellen

​Kanal erstellen

​Bestellempfang

​Eine Bestellung senden

​Abläufe

​Einen Kanal ausschalten

​Löschen

​Verwandte Themen

Verkaufskanäle verbinden

Referenz zu eigenen Kanälen

Einstellungen für Verkaufskanäle

API-Token erstellen

Kanal erstellen

Bestellempfang

Eine Bestellung senden

Abläufe

Einen Kanal ausschalten

Löschen

Verwandte Themen