Specyfikacja techniczna integracji

Integracja pozwala na automatyczną obsługę zwrotów za pośrednictwem Wygodnych Zwrotów - samodzielnie albo przez platformę typu marketplace. Ty przechowujesz dane sklepu, adres zwrotów i statusy w swoim panelu, a Wygodne Zwroty dostarczają formularz zwrotów, logistykę przesyłki zwrotnej oraz webhooki.

API korzysta z nagłówka x-api-key. Do pracy z API wystarczy Merchant Key, który dostajesz razem z mailbox_hid. Poprawność klucza możesz sprawdzić przez GET /partner-api/v1/auth/check.

• Draft to nie zwrot: draft tylko przygotowuje formularz; kolejne wywołanie dla tego samego zamówienia nadpisuje poprzednie.
• Wiele zwrotów do zamówienia: jedno orderNumber może mieć więcej niż jeden zwrot.
• Adres jest po Twojej stronie: konfigurujesz go u siebie, a zmiany aktualizujesz w Wygodnych Zwrotach.
• Wyszukiwarka zamówień dla niezalogowanych klientów działa po Twojej stronie - Wygodne Zwroty jej nie udostępniają.

1. Inicjacja zwrotu: klient zgłasza chęć zwrotu (zalogowany - z poziomu zamówienia, niezalogowany - przez Twoją wyszukiwarkę). Wysyłasz dane zamówienia przez POST /returns/draft i przekierowujesz klienta pod otrzymany redirect_url.
2. Zwrot: formularz zależy od pola flow: shipment (domyślnie) kończy się nadaniem przesyłki, withdrawal - odstąpieniem od umowy, po którym klient decyduje, czy nadać paczkę.
3. Synchronizacja: status zwrotu pobierasz cyklicznie przez endpoint zwrotów przypisanych do zamówienia, albo nasłuchujesz webhooków return.created / return.updated - włączasz je, ustawiając webhook_url w ustawieniach sklepu.

Zamiast pollingu możesz nasłuchiwać zdarzeń return.created i return.updated - pełny schemat i przykładowy payload znajdziesz w referencji poniżej. Tu krótko, jak je wdrożyć:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody: Buffer, signature: string, secret: string) {
  if (!/^[a-f0-9]{64}$/i.test(signature)) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const received = Buffer.from(signature, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}