API voor eigen verkoopkanalen

Met een eigen kanaal kan je eigen webshop, ERP of magazijnsysteem bestellingen rechtstreeks naar Zippendo sturen, wanneer er geen kant-en-klare koppeling voor bestaat. Deze pagina behandelt elke knop in het aanmaakvenster en de kanaalinstellingen, en hoe een ontwikkelaar een bestelling verstuurt. De route klik voor klik is Verkoopkanalen koppelen. De volledige referentie van de payload is Eigen kanalen. Klik in de zijbalk op Verkoopkanalen en dan op het tabblad Catalogus. De kaart Eigen kanaal zegt Koppel je eigen webshop of ERP-systeem. De knop is Kanaal aanmaken.

Catalogus van verkoopkanalen met de kaart Eigen kanaal en de knop Kanaal aanmaken — De kaart Eigen kanaal in de catalogus

Het kanaal aanmaken

Klik op Kanaal aanmaken. Het venster Eigen kanaal aanmaken opent: Een verkoopkanaal voor je eigen webshop of ERP-systeem.

Venster Eigen kanaal aanmaken met Naam van het kanaal ingevuld als My webshop, Kanaal aanmaken en Annuleren — Eigen kanaal aanmaken: vul een Naam van het kanaal in

Veld	Verplicht	Wat je invult
Naam van het kanaal	Ja	Een naam die je herkent, bijvoorbeeld “My webshop”. Kanaal aanmaken blijft inactief totdat je er een invult.
Merk	Nee	Alleen getoond als je organisatie merken heeft. Bestellingen uit dit kanaal horen bij dit merk.

Klik op Kanaal aanmaken (de knop toont Aanmaken…). Je ziet Verkoopkanaal aangemaakt en Zippendo opent de instellingen van het nieuwe kanaal. Zie je Kan het verkoopkanaal niet aanmaken, probeer het dan opnieuw. Annuleren sluit het venster.

Bestellingen ontvangen

De instellingenpagina heeft bovenaan de naam van het kanaal en Je eigen integratie: stuur bestellingen naar de ingest-URL of gebruik de API en de SDK’s. Documentatie bekijken opent de referentie Eigen kanalen.

De kaart Bestellingen ontvangen: Je systeem stuurt ondertekende bestellingen naar de ingest-URL hieronder. Onderteken de onbewerkte body van elk verzoek met HMAC-SHA256 en het ondertekeningsgeheim.

Knop	Wat het doet
Ingest-URL	Het adres waarnaar je systeem bestellingen stuurt, in de vorm `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Kopieer het van je eigen kanaal. Kopiëren toont Gekopieerd naar het klembord., of Kan niet naar het klembord kopiëren.
Geheim genereren	Maakt het ondertekeningsgeheim aan. Toont Genereren…, daarna Ondertekeningsgeheim gegenereerd. of Kan het ondertekeningsgeheim niet genereren.
Geheim vervangen	Vervangt een bestaand geheim. Zippendo vraagt je te bevestigen: je systeem wordt geweigerd totdat het met het nieuwe geheim ondertekent.
Intrekken	Schakelt het geheim uit. Elke bestelling die je systeem verstuurt wordt geweigerd totdat je een nieuw geheim genereert. Toont Ondertekeningsgeheim ingetrokken. of Kan het ondertekeningsgeheim niet intrekken.
Actief ondertekeningsgeheim aangemaakt op	Gevolgd door de datum en tijd waarop het huidige geheim is aangemaakt.

Het kanaal accepteert pas bestellingen zodra er een ondertekeningsgeheim bestaat. Er is geen aparte schakelaar om het ontvangen van bestellingen aan te zetten. Na Geheim genereren of Geheim vervangen wordt het geheim één keer getoond:

Bestellingen ontvangen met het eenmalige ondertekeningsgeheim, Kopiëren, Intrekken en Geheim vervangen — Kopieer het ondertekeningsgeheim nu. Het wordt maar één keer getoond

Kopieer het geheim nu. Het wordt maar één keer getoond. Als je het later vervangt, werkt het huidige geheim meteen niet meer. Het geheim begint met zwhs_. Bewaar het in de configuratie van je systeem.

Een bestelling versturen

Doe een POST naar de Ingest-URL met twee headers:

Header	Waarde
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` of `ping`
`X-Zippendo-Signature`	HMAC-SHA256 van de onbewerkte body van het verzoek, hexadecimaal gecodeerd, met het ondertekeningsgeheim als sleutel

order.created en order.updated maken de bestelling allebei aan of werken hem bij op basis van zijn externalId. De body van order.cancelled is { "externalId": "…" }. ping geeft 200 { "received": true } terug zonder iets te wijzigen.

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
})

Verplichte velden in de payload: externalId, orderNumber en orderLines (minstens één regel met name en quantity). Optioneel: customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle en serviceCode. Volledige veldentabel: Eigen kanalen.

Status	Betekenis
`200`	Geaccepteerd en verwerkt
`400`	Ontbrekende of onbekende topic, een payload die de validatie niet doorstond, of Kanaal ingeschakeld staat uit
`401`	Handtekeningcontrole mislukt: onjuist geheim, ontbrekende header, of er is nog geen geheim gegenereerd
`404`	Onbekend kanaal
`429`	Te veel bestellingen tegelijk. Probeer opnieuw na de vertraging van `Retry-After`
`5xx`	Verwerking mislukt. Probeer opnieuw: dezelfde bestelling nog eens versturen is veilig

Liever verzoek en antwoord? Maak bestellingen aan met POST /orgs/{orgId}/orders, met orderChannelId, en een API-token. Een tweede bestelling met dezelfde externalId op hetzelfde kanaal geeft 409 ORDER_EXISTS terug. Om trackingnummers en statuswijzigingen terug te krijgen abonneer je je op de webhooks van je organisatie (shipment.dispatched, tracking.updated). Een eigen kanaal heeft geen eigen track & trace-callback en geen scherm voor het koppelen van verzendmethoden. Een bestelling die je verstuurt verschijnt onder Bestellingen. De status kan Fout zijn wanneer Zippendo de bestelling heeft geïmporteerd maar geen zending kon aanmaken die klaar is om te verzenden, bijvoorbeeld omdat er geen verzendregel overeenkwam of het adres onvolledig is. De bestelling hoort nog steeds bij het kanaal.

Lijst Bestellingen met een bestelling die via een eigen kanaal is binnengekomen — Een bestelling die je systeem heeft verstuurd op de pagina Bestellingen

Werking

Instelling	Opgeslagen	Wat het doet
Kanaal ingeschakeld	Direct	Schakelt het kanaal in of uit. Staat dit uit, dan weigert Zippendo elke bestelling voor dit kanaal.
Zendingen automatisch verzenden	Met Wijzigingen opslaan	Verzendt de zending automatisch naar de vervoerder wanneer een binnenkomende bestelling overeenkomt met een verzendregel. Standaard uit.
Merk	Direct	Bestellingen uit dit kanaal horen bij dit merk. De lijst verschijnt alleen als je organisatie merken heeft.
Standaard afzenderadres	Met Wijzigingen opslaan	De afzender voor zendingen wanneer geen verzendregel overeenkomt met de bestelling. Is er nog geen opgeslagen, dan staat in de lijst Nog geen adressen.
Laatste bestelling ontvangen	Alleen lezen	Wanneer het kanaal voor het laatst een bestelling ontving, of Nooit.

Wijzigingen opslaan (Opslaan…) slaat Zendingen automatisch verzenden en Standaard afzenderadres op. Je ziet Verkoopkanaal bijgewerkt, of Kan het verkoopkanaal niet bijwerken.

Een kanaal uitschakelen

Zet Kanaal ingeschakeld uit. Op het tabblad Gekoppeld zegt de rij van het kanaal in de kaart Eigen kanaal dan Uitgeschakeld. Eigen kanalen blijven altijd op het tabblad Gekoppeld staan en worden nooit overgebleven kanalen.

Pagina Verkoopkanalen met een eigen kanaal dat als Uitgeschakeld is gemarkeerd — Een eigen kanaal dat is uitgeschakeld

Overgebleven Shopify- of WooCommerce-kanalen, gemarkeerd met Geen actieve koppeling en Ontkoppeld, zijn iets anders. Zie Instellingen van verkoopkanalen.

Verwijderen

Zoek onder Gevarenzone Kanaal verwijderen: Verwijder dit eigen kanaal. Je integratie kan er dan geen bestellingen meer naartoe sturen.

Klik op Verwijderen en bevestig: Dit eigen kanaal verwijderen? De ingest-URL accepteert meteen geen bestellingen meer. Je ziet Verkoopkanaal verwijderd, of Kan het verkoopkanaal niet verwijderen.

Gerelateerd

Verkoopkanalen koppelen

Maak het kanaal aan vanuit de catalogus en open daarna Bestellingen.

Referentie van eigen kanalen

Volledige payload, annuleren, ping en REST-voorbeelden.

Instellingen van verkoopkanalen

De pagina Verkoopkanalen, merken en overgebleven kanalen.

Een API-token aanmaken

Een token voor POST /orgs/{orgId}/orders in plaats van ondertekende pushes.

Overzicht

Zendingen

Bestellingen en verkoopkanalen

Vervoerders

Een vervoerder koppelen

Een integratie koppelen

Printen

Automatisering

Account

Zoeken en dashboard

API en events

API voor eigen verkoopkanalen

Het kanaal aanmaken

Bestellingen ontvangen

Een bestelling versturen

Werking

Een kanaal uitschakelen

Verwijderen

Gerelateerd

Verkoopkanalen koppelen

Referentie van eigen kanalen

Instellingen van verkoopkanalen

Een API-token aanmaken

​Het kanaal aanmaken

​Bestellingen ontvangen

​Een bestelling versturen

​Werking

​Een kanaal uitschakelen

​Verwijderen

​Gerelateerd

Verkoopkanalen koppelen

Referentie van eigen kanalen

Instellingen van verkoopkanalen

Een API-token aanmaken

Het kanaal aanmaken

Bestellingen ontvangen

Een bestelling versturen

Werking

Een kanaal uitschakelen

Verwijderen

Gerelateerd