Mukautetut kanavat

Mukautetun kanavan avulla oma verkkokauppasi, ERP-järjestelmäsi tai mikä tahansa muu hallitsemasi tilauslähde voi lähettää tilauksia Zippendoon, kun sille ei ole valmista yhteyttä. Se toimii kahteen suuntaan:

Tilausten lähetys sisään: järjestelmäsi lähettää allekirjoitettuja webhook-tapahtumia kanavan omaan ingest-URL-osoitteeseen tai kutsuu REST API:a (viralliset SDK:t saatavilla).
Tiedon saanti takaisin: tilaa Zippendon lähtevät webhookit (shipment.dispatched, tracking.updated ja muut) saadaksesi seurantakoodit ja tilamuutokset.

1. Luo kanava

Valitse app.zippendo.com-sovelluksessa Myyntikanavat, avaa Katalogi-välilehti ja valitse Mukautettu kanava -kortista Luo kanava. Tai luo se API:n kautta:

curl -X POST https://api.zippendo.com/orgs/{orgId}/order-channels \
  -H "Authorization: Bearer zipp_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My webshop", "type": "custom" }'

2. Luo allekirjoitussalaisuus

Valitse kanavan asetussivulla Luo salaisuus tai kutsu POST /orgs/{orgId}/order-channels/{channelId}/webhook-secret. Vastaus sisältää ingest-URL-osoitteen ja salaisuuden:

{
  "secret": "zwhs_...",
  "webhookUrl": "https://api.zippendo.com/webhooks/order-channels/{channelId}",
  "createdAt": "2026-09-02T12:00:00.000Z"
}

Salaisuus näytetään vain kerran. Tallenna se järjestelmäsi asetuksiin. Salaisuuden vaihtaminen luo uuden ja lopettaa vanhan toiminnan heti. Sen peruuttaminen saa ingest-URL-osoitteen hylkäämään kaikki lähetykset, kunnes uusi salaisuus on olemassa.

3. Lähetä tilauksia

Lähetä POST ingest-URL-osoitteeseen kahdella otsakkeella:

Otsake	Arvo
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` tai `ping`
`X-Zippendo-Signature`	Pyynnön raakasisällön HMAC-SHA256, heksakoodattuna, allekirjoitussalaisuudellasi avainnettuna

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

Tilauksen sisältö (`order.created` / `order.updated`)

Molemmat aiheet toimivat samoin: tilaus päivitetään tai luodaan externalId-kentän perusteella, joten uudelleentoimitukset ja väärässä järjestyksessä tulevat päivitykset ovat turvallisia. Lähetä kumpi tahansa, joka on järjestelmällesi helpompi.

{
  "externalId": "SO-10422",
  "orderNumber": "#1042",
  "customerName": "Anna Jensen",
  "customerEmail": "[email protected]",
  "shippingAddress": {
    "name": "Anna Jensen",
    "address1": "Nørregade 12",
    "city": "København",
    "postalCode": "1165",
    "countryCode": "DK",
    "phone": "+45 12 34 56 78"
  },
  "orderLines": [
    { "name": "Wool Sweater", "sku": "SKU-1042-BLK", "quantity": 2, "unitPrice": 499.0, "weight": 0.5, "weightUnit": "kg" }
  ],
  "totalAmount": 998.0,
  "currency": "DKK",
  "shippingMethodTitle": "GLS Hjemmelevering"
}

Kenttä	Pakollinen	Huomautuksia
`externalId`	✔	Järjestelmäsi tilaustunnus, jota käytetään idempotenssiavaimena
`orderNumber`	✔	Ihmisen luettava tilausnumero
`orderLines`	✔	Vähintään yksi rivi (`name`, `quantity`; valinnaisesti `sku`, `unitPrice`, `weight`, …)
`shippingAddress`		Tarvitaan, jotta lähetys voidaan luoda
`shippingMethodTitle`		Verrataan kanavan toimitustapojen kohdistuksiin toimitussäännön valitsemiseksi
`serviceCode`		Nimenomainen koodi `{carrier}:{product}:{ruleId}[\|{servicePointId}]`; ohittaa kohdistuksen
`customerName`, `customerEmail`, `subtotalAmount`, `totalAmount`, `currency`, `notes`		Valinnaisia metatietoja

Peruutuksen sisältö (`order.cancelled`)

{ "externalId": "SO-10422" }

Yhteystesti (`ping`)

Mikä tahansa allekirjoitettu sisältö otsakkeella X-Zippendo-Topic: ping palauttaa 200 { "received": true } muuttamatta mitään tietoja. Käytä sitä allekirjoituskoodisi tarkistamiseen.

Vastaukset

Tila	Merkitys
`200`	Toimitus hyväksytty ja käsitelty
`400`	Puuttuva tai tuntematon aiheotsake, validoinnin läpäisemätön sisältö tai pois päältä kytketty kanava (Kanava käytössä on pois päältä)
`401`	Allekirjoituksen tarkistus epäonnistui (väärä salaisuus, puuttuva otsake tai salaisuutta ei ole vielä luotu)
`404`	Tuntematon kanavan tunnus
`429`	Ingest-nopeusrajoitus saavutettu. Yritä uudelleen `Retry-After`-viiveen jälkeen
`5xx`	Käsittely epäonnistui. Yritä toimitusta uudelleen: päivitys tai luonti tekee uudelleentoimituksen turvalliseksi

Mitä lähetetylle tilaukselle tapahtuu

Tilaus päivitetään tai luodaan kanavalle (ja se perii kanavan brändin, jos sellainen on).
Toimitussääntö ratkaistaan: nimenomainen serviceCode tai muuten kanavan toimitustapojen kohdistukset verrattuna arvoon shippingMethodTitle.
Lähetys luodaan. Lähetykset, joille on löytynyt sääntö, ovat valmiita lähetettäviksi. Jos vain Lähettäjän oletusosoite on asetettu, luodaan sen sijaan luonnos.
Jos Lähetä lähetykset automaattisesti on kanavalla käytössä, lähetys, jolle on löytynyt sääntö, lähetetään kuljetusyhtiölle heti ja osoitekortti tallentuu Zippendoon (säännön automaattinen tulostus on voimassa).

REST-vaihtoehto

Jos pidät pyyntö-vastaus-mallista enemmän kuin webhookeista, luo tilaukset API:n kautta API-tokenilla:

curl -X POST https://api.zippendo.com/orgs/{orgId}/orders \
  -H "Authorization: Bearer zipp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderChannelId": "{channelId}",
    "orderNumber": "#1042",
    "externalId": "SO-10422",
    "orderLines": [{ "name": "Wool Sweater", "quantity": 2 }],
    "shippingAddress": { "name": "Anna Jensen", "address1": "Nørregade 12", "city": "København", "postalCode": "1165", "countryCode": "DK" },
    "shippingMethodTitle": "GLS Hjemmelevering"
  }'

Sama externalId samalla kanavalla palauttaa 409 ORDER_EXISTS. Käsittele se tilauksena, joka on jo vastaanotettu.
Kun annat shippingRuleId tai shippingMethodTitle (tai otat kanavalla käyttöön Lähetä lähetykset automaattisesti), lähetys luodaan samassa kutsussa täsmälleen kuten lähetyksessä.
Myyntikanavat kuuluvat julkiseen API:in, joten SDK:t kattavat jokaisen vaiheen: kanavan luominen, salaisuuden luominen, tilausten lähettäminen ja lähetysten luettelointi.

Seurannan saaminen takaisin

Zippendo ilmoittaa järjestelmällesi lähtevien webhookien kautta: tilaa shipment.dispatched ja tracking.updated kohdassa Asetukset → Webhookit. Lähetysten reference-kenttänä on tilausnumerosi, ja sisältö sisältää orderId-arvon hakuja varten.

Aloitus

Pika-aloitukset

Toimitusprosessi

Yhteydet

Toiminnot

Organisaatio ja tili

Mukautetut kanavat

1. Luo kanava

2. Luo allekirjoitussalaisuus

3. Lähetä tilauksia

Tilauksen sisältö (`order.created` / `order.updated`)

Peruutuksen sisältö (`order.cancelled`)

Yhteystesti (`ping`)

Vastaukset

Mitä lähetetylle tilaukselle tapahtuu

REST-vaihtoehto

Seurannan saaminen takaisin

Seuraavat vaiheet

Lähtevät webhookit

API-viite

​1. Luo kanava

​2. Luo allekirjoitussalaisuus

​3. Lähetä tilauksia

​Tilauksen sisältö (order.created / order.updated)

​Peruutuksen sisältö (order.cancelled)

​Yhteystesti (ping)

​Vastaukset

​Mitä lähetetylle tilaukselle tapahtuu

​REST-vaihtoehto

​Seurannan saaminen takaisin

​Seuraavat vaiheet

Lähtevät webhookit

API-viite

1. Luo kanava

2. Luo allekirjoitussalaisuus

3. Lähetä tilauksia

Tilauksen sisältö (`order.created` / `order.updated`)

Peruutuksen sisältö (`order.cancelled`)

Yhteystesti (`ping`)

Vastaukset

Mitä lähetetylle tilaukselle tapahtuu

REST-vaihtoehto

Seurannan saaminen takaisin

Seuraavat vaiheet