API własnego kanału

Własny kanał pozwala Twojemu sklepowi internetowemu, systemowi ERP lub magazynowemu wysyłać zamówienia prosto do Zippendo, gdy nie ma dla niego gotowego połączenia. Ta strona opisuje każdy element okna tworzenia i ustawień kanału oraz to, jak programista wysyła zamówienie. Instrukcja krok po kroku to Połącz kanały sprzedaży. Pełny opis ładunku to Własne kanały. Kliknij Kanały sprzedaży w panelu bocznym, a potem kartę Katalog. Karta Własny kanał zawiera napis Połącz własny sklep internetowy lub system ERP. Jej przycisk to Utwórz kanał.

Utwórz kanał

Kliknij Utwórz kanał. Otworzy się okno Utwórz własny kanał: Kanał sprzedaży dla Twojego własnego sklepu internetowego lub systemu ERP.

Pole	Wymagane	Co wpisać
Nazwa kanału	Tak	Nazwa, którą rozpoznasz, na przykład „My webshop”. Utwórz kanał pozostaje nieaktywne, dopóki jej nie wpiszesz.
Marka	Nie	Widoczne tylko wtedy, gdy Twoja organizacja ma marki. Zamówienia z tego kanału należą do tej marki.

Kliknij Utwórz kanał (pokazuje Tworzenie…). Zobaczysz Utworzono kanał sprzedaży, a Zippendo otworzy ustawienia nowego kanału. Jeśli zobaczysz Nie udało się utworzyć kanału sprzedaży, spróbuj ponownie. Anuluj zamyka okno.

Przyjmowanie zamówień

Na górze strony ustawień widać nazwę kanału i Twoja własna integracja: wysyłaj zamówienia na ingest URL albo korzystaj z API i SDK. Zobacz dokumentację otwiera opis Własne kanały.

Karta Przyjmowanie zamówień: Twój system wysyła podpisane zamówienia na poniższy ingest URL. Podpisuj surową treść każdego żądania algorytmem HMAC-SHA256, używając sekretu podpisu.

Element	Co robi
Ingest URL	Adres, na który Twój system wysyła zamówienia, w postaci `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Skopiuj go ze swojego kanału. Kopiuj pokazuje Skopiowano do schowka. albo Nie udało się skopiować do schowka.
Wygeneruj sekret	Tworzy sekret podpisu. Pokazuje Generowanie…, a potem Wygenerowano sekret podpisu. albo Nie udało się wygenerować sekretu podpisu.
Zastąp sekret	Zastępuje istniejący sekret. Zippendo prosi o potwierdzenie: Twój system jest odrzucany, dopóki nie zacznie podpisywać nowym sekretem.
Unieważnij	Wyłącza sekret. Każde zamówienie wysłane przez Twój system jest odrzucane, dopóki nie wygenerujesz nowego sekretu. Pokazuje Unieważniono sekret podpisu. albo Nie udało się unieważnić sekretu podpisu.
Aktywny sekret podpisu utworzony	Po tym napisie widać datę i godzinę utworzenia bieżącego sekretu.

Kanał przyjmuje zamówienia dopiero wtedy, gdy istnieje sekret podpisu. Nie ma osobnego przełącznika włączającego przyjmowanie. Po Wygeneruj sekret lub Zastąp sekret sekret jest pokazywany raz:

Przyjmowanie zamówień z jednorazowo pokazanym sekretem podpisu oraz przyciskami Kopiuj, Unieważnij i Zastąp sekret — Skopiuj sekret podpisu teraz. Jest pokazywany tylko raz

Skopiuj sekret teraz. Jest pokazywany tylko raz. Jeśli później go zastąpisz, obecny sekret natychmiast przestanie działać. Sekret zaczyna się od zwhs_. Zapisz go w konfiguracji swojego systemu.

Wyślij zamówienie

Wyślij POST na Ingest URL z dwoma nagłówkami:

Nagłówek	Wartość
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` lub `ping`
`X-Zippendo-Signature`	HMAC-SHA256 surowej treści żądania, zakodowany szesnastkowo, z kluczem w postaci sekretu podpisu

order.created i order.updated tworzą lub aktualizują zamówienie według jego externalId. Treść order.cancelled to { "externalId": "…" }. ping zwraca 200 { "received": true } bez zmieniania czegokolwiek.

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

Wymagane pola ładunku: externalId, orderNumber i orderLines (co najmniej jedna pozycja z name i quantity). Opcjonalne: customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle i serviceCode. Pełna tabela pól: Własne kanały.

Status	Znaczenie
`200`	Przyjęto i przetworzono
`400`	Brakujący lub nieznany temat, ładunek, który nie przeszedł walidacji, albo Kanał włączony jest wyłączone
`401`	Weryfikacja podpisu nie powiodła się: zły sekret, brakujący nagłówek albo nie wygenerowano jeszcze sekretu
`404`	Nieznany kanał
`429`	Zbyt wiele zamówień naraz. Ponów po opóźnieniu `Retry-After`
`5xx`	Przetwarzanie się nie powiodło. Ponów: ponowne wysłanie tego samego zamówienia jest bezpieczne

Wolisz żądanie i odpowiedź? Twórz zamówienia przez POST /orgs/{orgId}/orders, przekazując orderChannelId, oraz token API. Drugie zamówienie z tym samym externalId w tym samym kanale zwraca 409 ORDER_EXISTS. Aby odbierać numery przesyłek i zmiany statusu z powrotem, zasubskrybuj webhooki swojej organizacji (shipment.dispatched, tracking.updated). Własny kanał nie ma własnego wywołania zwrotnego śledzenia ani ekranu mapowania metod dostawy. Wysłane zamówienie pojawia się w Zamówienia. Jego status może mieć wartość Błąd, gdy Zippendo zaimportowało zamówienie, ale nie mogło utworzyć przesyłki gotowej do wysłania, na przykład dlatego, że nie pasowała żadna reguła wysyłki lub adres jest niekompletny. Zamówienie nadal należy do kanału.

Lista zamówień z zamówieniem, które dotarło przez własny kanał — Zamówienie wysłane przez Twój system na stronie Zamówienia

Operacje

Ustawienie	Zapis	Co robi
Kanał włączony	Od razu	Włącza lub wyłącza kanał. Gdy kanał jest wyłączony, Zippendo odrzuca każde wysłane do niego zamówienie.
Wysyłaj przesyłki automatycznie	Przez Zapisz zmiany	Automatycznie wysyła przesyłkę do przewoźnika, gdy przychodzące zamówienie pasuje do reguły wysyłki. Domyślnie wyłączone.
Marka	Od razu	Zamówienia z tego kanału należą do tej marki. Lista pojawia się tylko wtedy, gdy Twoja organizacja ma marki.
Domyślny adres nadawcy	Przez Zapisz zmiany	Nadawca przesyłek, gdy do zamówienia nie pasuje żadna reguła wysyłki. Jeśli nic jeszcze nie zapisano, lista pokazuje Brak adresów.
Ostatnie otrzymane zamówienie	Tylko do odczytu	Kiedy kanał ostatnio otrzymał zamówienie, albo Nigdy.

Zapisz zmiany (Zapisywanie…) zapisuje Wysyłaj przesyłki automatycznie i Domyślny adres nadawcy. Zobaczysz Zaktualizowano kanał sprzedaży albo Nie udało się zaktualizować kanału sprzedaży.

Wyłącz kanał

Wyłącz Kanał włączony. Na karcie Połączony wiersz kanału w karcie Własny kanał pokazuje wtedy Wyłączona. Własne kanały zawsze pozostają na karcie Połączony i nigdy nie stają się pozostałymi kanałami.

Strona Kanały sprzedaży z własnym kanałem oznaczonym Wyłączona — Własny kanał, który jest wyłączony

Pozostałe kanały Shopify lub WooCommerce, oznaczone Brak aktywnego połączenia i Odłączony, to coś innego. Zobacz Ustawienia kanału sprzedaży.

Usuń

W sekcji Strefa zagrożenia znajdź Usuń kanał: Usuń ten własny kanał. Twoja integracja nie będzie już mogła wysyłać do niego zamówień.

Kliknij Usuń i potwierdź: Usunąć ten własny kanał? Jego ingest URL natychmiast przestanie przyjmować zamówienia. Zobaczysz Usunięto kanał sprzedaży albo Nie udało się usunąć kanału sprzedaży.

Powiązane

Połącz kanały sprzedaży

Utwórz kanał z katalogu, a potem otwórz Zamówienia.

Opis własnych kanałów

Pełny ładunek, anulowanie, ping i przykłady REST.

Ustawienia kanału sprzedaży

Strona Kanały sprzedaży, marki i pozostałe kanały.

Utwórz token API

Token do POST /orgs/{orgId}/orders zamiast podpisanych wywołań.

Przegląd

Przesyłki

Zamówienia i kanały

Przewoźnicy

Połącz przewoźnika

Połącz integrację

Drukowanie

Automatyzacja

Konto

Wyszukiwanie i panel

API i zdarzenia

API własnego kanału

Utwórz kanał

Przyjmowanie zamówień

Wyślij zamówienie

Operacje

Wyłącz kanał

Usuń

Powiązane

Połącz kanały sprzedaży

Opis własnych kanałów

Ustawienia kanału sprzedaży

Utwórz token API

​Utwórz kanał

​Przyjmowanie zamówień

​Wyślij zamówienie

​Operacje

​Wyłącz kanał

​Usuń

​Powiązane

Połącz kanały sprzedaży

Opis własnych kanałów

Ustawienia kanału sprzedaży

Utwórz token API

Utwórz kanał

Przyjmowanie zamówień

Wyślij zamówienie

Operacje

Wyłącz kanał

Usuń

Powiązane