> ## Documentation Index
> Fetch the complete documentation index at: https://www.zippendo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mukautetun kanavan API

> Luo mukautettu myyntikanava, kopioi vastaanotto-URL ja allekirjoitussalaisuus, aseta Toiminta-kytkimet ja lähetä allekirjoitettu tilaus omasta verkkokaupastasi tai ERP-järjestelmästäsi.

Mukautetun kanavan avulla oma verkkokauppasi, ERP- tai varastojärjestelmäsi voi lähettää tilauksia suoraan Zippendoon, kun sille ei ole valmista yhteyttä. Tällä sivulla käydään läpi luontiikkunan ja kanavan asetusten kaikki kentät sekä se, miten kehittäjä lähettää tilauksen. Vaiheittainen ohje on [Yhdistä myyntikanavat](/docs/fi/tutorials/connect-order-channels). Täydellinen payload-kuvaus on sivulla [Mukautetut kanavat](/docs/fi/order-channels/custom-channels).

Valitse sivupalkista **Myyntikanavat** ja sitten **Katalogi**-välilehti. **Mukautettu kanava** -kortissa lukee **Yhdistä oma verkkokauppasi tai ERP-järjestelmäsi**. Kortin painike on **Luo kanava**.

<Frame caption="Mukautettu kanava -kortti katalogissa">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/01-available-integrations-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=4347ac58d9be4627e3888405db07801a" alt="Myyntikanavien katalogi, jossa Mukautettu kanava -kortti ja Luo kanava -painike" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/01-available-integrations-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/01-available-integrations-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=53aafeff9db915c9767b87279fd0f6a6" alt="Myyntikanavien katalogi, jossa Mukautettu kanava -kortti ja Luo kanava -painike" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/01-available-integrations-dark.png" />
</Frame>

## Luo kanava

Valitse **Luo kanava**. **Luo mukautettu kanava** -ikkuna avautuu: **Myyntikanava omalle verkkokaupallesi tai ERP-järjestelmällesi.**

<Frame caption="Luo mukautettu kanava: anna Kanavan nimi">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/02-create-modal-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=7910951db4aa483c261ccc8b4a32e2c0" alt="Luo mukautettu kanava -ikkuna, jossa Kanavan nimeksi on täytetty Verkkokauppani, sekä Luo kanava ja Peruuta" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/02-create-modal-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/02-create-modal-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=45794893b13f7fb8ec15959d53f896f5" alt="Luo mukautettu kanava -ikkuna, jossa Kanavan nimeksi on täytetty Verkkokauppani, sekä Luo kanava ja Peruuta" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/02-create-modal-dark.png" />
</Frame>

| Kenttä | Pakollinen | Mitä syötetään |
| - | - | - |
| **Kanavan nimi** | Kyllä | Nimi, jonka tunnistat, esimerkiksi "Verkkokauppani". **Luo kanava** pysyy harmaana, kunnes olet antanut nimen. |
| **Brändi** | Ei | Näkyy vain, jos organisaatiossasi on brändejä. **Tämän kanavan tilaukset kuuluvat tälle brändille.** |

Valitse **Luo kanava** (painikkeessa lukee **Luodaan…**). Näet viestin **Myyntikanava luotu**, ja Zippendo avaa uuden kanavan asetukset. Jos näet viestin **Myyntikanavan luominen epäonnistui**, yritä uudelleen. **Peruuta** sulkee ikkunan.

## Tilausten vastaanotto

Asetussivun otsikkona on kanavan nimi ja teksti **Oma integraatiosi: lähetä tilaukset vastaanotto-URL-osoitteeseen tai käytä API:a ja SDK:ita.** **Avaa ohjeet** avaa [Mukautetut kanavat](/docs/fi/order-channels/custom-channels) -kuvauksen.

<Frame caption="Tilausten vastaanotto: Vastaanotto-URL ja Luo salaisuus">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/03-order-ingestion-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=2a3d68186624ec0f925c003cb4add0f4" alt="Tilausten vastaanotto -kortti, jossa Vastaanotto-URL, Kopioi ja Luo salaisuus" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/03-order-ingestion-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/03-order-ingestion-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=67ae35ab77a1fdb31e6513944e165257" alt="Tilausten vastaanotto -kortti, jossa Vastaanotto-URL, Kopioi ja Luo salaisuus" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/03-order-ingestion-dark.png" />
</Frame>

**Tilausten vastaanotto** -kortti: **Järjestelmäsi lähettää allekirjoitetut tilaukset alla olevaan vastaanotto-URL-osoitteeseen. Allekirjoita jokaisen pyynnön raaka runko HMAC-SHA256:lla allekirjoitussalaisuuden avulla.**

| Toiminto | Mitä se tekee |
| - | - |
| **Vastaanotto-URL** | Osoite, johon järjestelmäsi lähettää tilaukset, muodossa `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Kopioi se omalta kanavaltasi. **Kopioi** näyttää viestin **Kopioitu leikepöydälle.** tai **Kopioiminen leikepöydälle epäonnistui.** |
| **Luo salaisuus** | Luo allekirjoitussalaisuuden. Näyttää **Luodaan…**, sitten **Allekirjoitussalaisuus luotu.** tai **Allekirjoitussalaisuuden luominen epäonnistui.** |
| **Vaihda salaisuus** | Vaihtaa olemassa olevan salaisuuden. Zippendo pyytää vahvistuksen: järjestelmäsi hylätään, kunnes se allekirjoittaa uudella salaisuudella. |
| **Mitätöi** | Poistaa salaisuuden käytöstä. Kaikki järjestelmäsi lähettämät tilaukset hylätään, kunnes luot uuden salaisuuden. Näyttää **Allekirjoitussalaisuus mitätöity.** tai **Allekirjoitussalaisuuden mitätöinti epäonnistui.** |
| **Aktiivinen allekirjoitussalaisuus luotu** | Perässä on nykyisen salaisuuden luontipäivä ja -aika. |

Kanava hyväksyy tilauksia vasta, kun allekirjoitussalaisuus on olemassa. Vastaanotolle ei ole erillistä kytkintä.

Kun olet valinnut **Luo salaisuus** tai **Vaihda salaisuus**, salaisuus näytetään vain kerran:

<Frame caption="Kopioi allekirjoitussalaisuus nyt. Se näytetään vain kerran">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/04-signing-secret-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=01c14600acad344f1e392563a3c43fc4" alt="Tilausten vastaanotto -kortti, jossa kertaluonteinen allekirjoitussalaisuus, Kopioi, Mitätöi ja Vaihda salaisuus" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/04-signing-secret-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/04-signing-secret-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=d11389d50ddeb62f3a7a999f5aeb561a" alt="Tilausten vastaanotto -kortti, jossa kertaluonteinen allekirjoitussalaisuus, Kopioi, Mitätöi ja Vaihda salaisuus" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/04-signing-secret-dark.png" />
</Frame>

<Warning>
  **Kopioi salaisuus nyt. Se näytetään vain kerran. Jos vaihdat sen myöhemmin, nykyinen salaisuus lakkaa toimimasta heti.** Salaisuus alkaa merkeillä `zwhs_`. Tallenna se järjestelmäsi asetuksiin.
</Warning>

## Lähetä tilaus

Lähetä `POST` **Vastaanotto-URL**-osoitteeseen kahdella otsikolla:

| Otsikko | Arvo |
| - | - |
| `X-Zippendo-Topic` | `order.created`, `order.updated`, `order.cancelled` tai `ping` |
| `X-Zippendo-Signature` | **Pyynnön raa'an rungon** HMAC-SHA256 heksakoodattuna, avaimena allekirjoitussalaisuus |

`order.created` ja `order.updated` luovat tai päivittävät tilauksen `externalId`:n perusteella. `order.cancelled`-rungon muoto on `{ "externalId": "…" }`. `ping` palauttaa `200 { "received": true }` muuttamatta mitään.

```javascript theme={null}
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
})
```

Pakolliset payload-kentät: `externalId`, `orderNumber` ja `orderLines` (vähintään yksi rivi, jossa `name` ja `quantity`). Valinnaiset: `customerName`, `customerEmail`, `shippingAddress`, `subtotalAmount`, `totalAmount`, `currency`, `notes`, `shippingMethodTitle` ja `serviceCode`. Täydellinen kenttätaulukko: [Mukautetut kanavat](/docs/fi/order-channels/custom-channels).

| Tila | Merkitys |
| - | - |
| `200` | Hyväksytty ja käsitelty |
| `400` | Aihe puuttuu tai on tuntematon, payload ei läpäissyt validointia tai **Kanava käytössä** on pois päältä |
| `401` | Allekirjoituksen tarkistus epäonnistui: väärä salaisuus, otsikko puuttuu tai salaisuutta ei ole vielä luotu |
| `404` | Tuntematon kanava |
| `429` | Liian monta tilausta kerralla. Yritä uudelleen `Retry-After`-viiveen jälkeen |
| `5xx` | Käsittely epäonnistui. Yritä uudelleen: saman tilauksen lähettäminen uudelleen on turvallista |

Haluatko mieluummin pyyntö-vastaus-mallin? Luo tilauksia kutsulla `POST /orgs/{orgId}/orders`, jossa annat `orderChannelId`:n, ja [API-tokenilla](/docs/fi/how-to/create-an-api-token). Toinen tilaus samalla `externalId`:llä samalla kanavalla palauttaa `409 ORDER_EXISTS`.

Saadaksesi seurantakoodit ja tilamuutokset takaisin tilaa organisaatiosi [webhookit](/docs/fi/how-to/webhooks) (`shipment.dispatched`, `tracking.updated`). Mukautetulla kanavalla ei ole omaa seurantakutsua eikä toimitustapojen yhdistämisnäkymää.

Lähettämäsi tilaus näkyy kohdassa **Tilaukset**. Sen tila voi olla **Virhe**, kun Zippendo tuotti tilauksen mutta ei pystynyt luomaan lähetysvalmista lähetystä, esimerkiksi koska mikään toimitussääntö ei täsmännyt tai osoite on puutteellinen. Tilaus kuuluu silti kanavalle.

<Frame caption="Järjestelmäsi lähettämä tilaus Tilaukset-sivulla">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/08-ingested-order-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=73fb7b628c5e058e25edc3a0c4a023a8" alt="Tilausluettelo, jossa mukautetun kanavan kautta saapunut tilaus" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/08-ingested-order-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/08-ingested-order-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=8aac93ccac1e75874022f886eae75310" alt="Tilausluettelo, jossa mukautetun kanavan kautta saapunut tilaus" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/08-ingested-order-dark.png" />
</Frame>

## Toiminta

<Frame caption="Toiminta: Kanava käytössä, Lähetä lähetykset automaattisesti ja Lähettäjän oletusosoite">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/05-operations-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=9d22ab4dd7c4622aa4fdfcd6bfe74610" alt="Toiminta-kortti, jossa Kanava käytössä on päällä, sekä Lähetä lähetykset automaattisesti, Lähettäjän oletusosoite, Viimeisin vastaanotettu tilaus ja Tallenna muutokset" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/05-operations-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/05-operations-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=b2bd4a2953a4d535ebd80272001bcd60" alt="Toiminta-kortti, jossa Kanava käytössä on päällä, sekä Lähetä lähetykset automaattisesti, Lähettäjän oletusosoite, Viimeisin vastaanotettu tilaus ja Tallenna muutokset" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/05-operations-dark.png" />
</Frame>

| Asetus | Tallentuu | Mitä se tekee |
| - | - | - |
| **Kanava käytössä** | Heti | Kytkee kanavan päälle tai pois. **Kun se on pois päältä, Zippendo hylkää kaikki tälle kanavalle lähetetyt tilaukset.** |
| **Lähetä lähetykset automaattisesti** | Valinnalla **Tallenna muutokset** | Lähettää lähetyksen kuljetusyhtiölle automaattisesti, kun saapuva tilaus täsmää toimitussääntöön. Oletuksena pois päältä. |
| **Brändi** | Heti | **Tämän kanavan tilaukset kuuluvat tälle brändille.** Luettelo näkyy vain, jos organisaatiossasi on brändejä. |
| **Lähettäjän oletusosoite** | Valinnalla **Tallenna muutokset** | Lähettäjä lähetyksille, kun mikään toimitussääntö ei täsmää tilaukseen. Jos osoitetta ei ole vielä tallennettu, luettelossa lukee **Ei vielä osoitteita**. |
| **Viimeisin vastaanotettu tilaus** | Vain luku | Milloin kanava vastaanotti viimeksi tilauksen, tai **Ei koskaan**. |

**Tallenna muutokset** (**Tallennetaan…**) tallentaa **Lähetä lähetykset automaattisesti** ja **Lähettäjän oletusosoite** -asetukset. Näet viestin **Myyntikanava päivitetty** tai **Myyntikanavan päivittäminen epäonnistui**.

## Kytke kanava pois päältä

Kytke **Kanava käytössä** pois päältä. **Yhdistetty**-välilehdellä kanavan rivillä **Mukautettu kanava** -kortissa lukee silloin **Poistettu käytöstä**. Mukautetut kanavat pysyvät aina **Yhdistetty**-välilehdellä, eivätkä koskaan muutu jäännöskanaviksi.

<Frame caption="Pois päältä kytketty mukautettu kanava">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/06-disabled-card-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=1181fec8f63d9eb1f0d016c600ae80d8" alt="Myyntikanavat-sivu, jossa mukautettu kanava on merkitty tilaan Poistettu käytöstä" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/06-disabled-card-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/06-disabled-card-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=a6968f7b8b3770ed93dc7af3f3cf74ef" alt="Myyntikanavat-sivu, jossa mukautettu kanava on merkitty tilaan Poistettu käytöstä" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/06-disabled-card-dark.png" />
</Frame>

Shopify- tai WooCommerce-jäännöskanavat, joissa lukee **Ei aktiivista yhteyttä** ja **Yhteys katkaistu**, ovat eri asia. Katso [Myyntikanavan asetukset](/docs/fi/how-to/order-channel-settings).

## Poista

Kohdassa **Vaaravyöhyke** on **Poista kanava**: **Poista tämä mukautettu kanava. Integraatiosi ei enää voi lähettää siihen tilauksia.**

<Frame caption="Poista kanava Vaaravyöhykkeessä">
  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/07-danger-zone-light.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=f67363b1ac896c94d1a66214c2ade928" alt="Vaaravyöhyke, jossa Poista kanava ja Poista-painike" className="block dark:hidden" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/07-danger-zone-light.png" />

  <img src="https://mintcdn.com/zippendo/y4yerikcvzGeoRXb/images/fi/how-to/custom-channel-api/07-danger-zone-dark.png?fit=max&auto=format&n=y4yerikcvzGeoRXb&q=85&s=a7583dc337713b622c8dc9e2d33511c3" alt="Vaaravyöhyke, jossa Poista kanava ja Poista-painike" className="hidden dark:block" width="2880" height="1800" data-path="images/fi/how-to/custom-channel-api/07-danger-zone-dark.png" />
</Frame>

Valitse **Poista** ja vahvista: **Poistetaanko tämä mukautettu kanava? Sen vastaanotto-URL lakkaa hyväksymästä tilauksia heti.** Näet viestin **Myyntikanava poistettu** tai **Myyntikanavan poistaminen epäonnistui**.

## Aiheeseen liittyvää

<CardGroup cols={2}>
  <Card title="Yhdistä myyntikanavat" icon="store" href="/docs/fi/tutorials/connect-order-channels">
    Luo kanava katalogista ja avaa sitten Tilaukset.
  </Card>

  <Card title="Mukautettujen kanavien kuvaus" icon="webhook" href="/docs/fi/order-channels/custom-channels">
    Täydellinen payload, peruutus, ping ja REST-esimerkit.
  </Card>

  <Card title="Myyntikanavan asetukset" icon="settings-2" href="/docs/fi/how-to/order-channel-settings">
    Myyntikanavat-sivu, brändit ja jäännöskanavat.
  </Card>

  <Card title="Luo API-token" icon="key" href="/docs/fi/how-to/create-an-api-token">
    Token kutsua POST /orgs/\{orgId}/orders varten allekirjoitettujen kutsujen sijaan.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.