Dokumentacja API webhooków
Zintegruj swój sklep z Deneeu, aby automatycznie zgłaszać konwersje i naliczać prowizje influencerom w czasie rzeczywistym.
Wprowadzenie do webhooków
Deneeu śledzi konwersje w modelu CPS (Cost Per Sale) — płacisz wyłącznie za zarejestrowane sprzedaże. Aby to działało, Twój sklep musi po każdym udanym zamówieniu wysłać żądanie POST do naszego API z danymi zamówienia i identyfikatorem influencera.
Udostępniamy dwa endpointy webhookowe: /api/conversion — rekomendowany endpoint bazujący na identyfikatorze influencera (ref), oraz /api/track — alternatywny endpoint bazujący bezpośrednio na kodzie linku afiliacyjnego (code). Oba tworzą prowizję ze statusem PENDING, którą marka zatwierdza w panelu.
Szybki start
Najszybszy sposób na sprawdzenie integracji to wysłanie żądania cURL bezpośrednio z terminala:
Nagłówek x-signature jest wymagany
Żądanie bez podpisu zwraca 401, nawet przy prawidłowym kluczu API. Podpis to HMAC-SHA256 surowego ciała żądania w zapisie szesnastkowym, liczony sekretem webhooka marki (Ustawienia → Integracja). Gotowe przykłady w Node, PHP i Pythonie znajdziesz w sekcji „Przykłady integracji”.
W odpowiedzi otrzymasz potwierdzenie zarejestrowania konwersji wraz z rozbiciem prowizji:
Autentykacja
Każde żądanie musi zawierać nagłówek x-api-key z Twoim kluczem API. Klucz znajdziesz w panelu marki, w sekcji Ustawienia → Integracja.
Każde żądanie musi być dodatkowo podpisane, aby zabezpieczyć je przed modyfikacją w tranzycie. Oblicz HMAC-SHA256 z surowej treści żądania (JSON), używając swojego webhookSecret, i prześlij wynik jako nagłówek x-signature. Nagłówek jest wymagany — żądanie bez niego lub z nieprawidłowym podpisem zostanie odrzucone z kodem 401.
/api/track
Rejestruje konwersję na podstawie kodu linku afiliacyjnego (code). Link musi należeć do produktu Twojej marki, w przeciwnym razie żądanie zostanie odrzucone.
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
| code | string | wymagane | Kod unikalnego linku afiliacyjnego (AffiliateLink.code). |
| orderValue | number | wymagane | Wartość zamówienia. Musi być liczbą dodatnią. |
| orderId | string | opcjonalne | Twój identyfikator zamówienia. Używany do ochrony przed duplikatami (sprawdzany w obrębie Twojej marki). |
Przykładowe żądanie
Odpowiedź 200 OK
/api/conversion
RekomendowanyRejestruje konwersję na podstawie identyfikatora influencera (ref). To domyślny endpoint prezentowany w panelu marki i zalecany dla większości integracji sklepowych.
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
| orderId | string | wymagane | Twój identyfikator zamówienia. Używany globalnie do ochrony przed duplikatami. |
| amount | number | wymagane | Wartość zamówienia (musi być różna od zera). |
| ref | string | wymagane | Identyfikator influencera (InfluencerProfile.id) przypisany do konwersji. |
| currency | string | opcjonalne | Kod waluty, domyślnie "PLN". Zwracany w odpowiedzi, nie jest zapisywany w bazie danych. |
| string | opcjonalne | Adres e-mail klienta — zapisywany jako dane konwersji. | |
| productSlug | string | opcjonalne | Slug produktu — pozwala rozróżnić linki, jeśli influencer promuje kilka produktów Twojej marki. |
Przykładowe żądanie
Odpowiedź 200 OK
Kody błędów
Oba endpointy zwracają błędy w formacie { "error": "..." } wraz z odpowiednim kodem HTTP.
| Kod | Kiedy występuje |
|---|---|
| 400 | Nieprawidłowy JSON lub brak wymaganych pól w treści żądania. |
| 401 | Brak nagłówka x-api-key, nieprawidłowy klucz API lub niezgodny podpis HMAC (x-signature). |
| 403 | Link afiliacyjny należy do innej marki niż ta uwierzytelniona kluczem API (dotyczy /api/track). |
| 404 | Nie znaleziono linku afiliacyjnego dla podanego code / ref. |
| 409 | Zamówienie o podanym orderId zostało już zarejestrowane. |
| 500 | Wewnętrzny błąd serwera podczas przetwarzania żądania. |
Przykłady integracji
Poniżej znajdziesz gotowe fragmenty kodu do wysłania webhooka po zakończeniu zamówienia — dla WooCommerce, Node.js/JavaScript, Pythona oraz cURL.
WooCommerce (PHP)
Zapisz identyfikator influencera z parametru ?ref= w ciasteczku Twojego sklepu, a następnie wyślij webhook po zakończeniu zamówienia.
JavaScript / Node.js
Python
cURL
Checklist testowania
- Skopiuj swój x-api-key z panelu marki (Ustawienia → Integracja).
- Kliknij testowy link afiliacyjny (/r/kod) i odczytaj parametr ?ref= dołączony do przekierowania.
- Wyślij testowe żądanie POST /api/conversion z unikalnym orderId i poprawnym ref.
- Sprawdź, czy odpowiedź zwraca "success": true oraz poprawny breakdown prowizji.
- Wyślij dokładnie to samo żądanie ponownie i potwierdź, że otrzymujesz błąd 409.
- Sprawdź w panelu marki i influencera, czy konwersja pojawiła się ze statusem PENDING.
- Wyślij żądanie bez pola ref (lub amount / orderId) i potwierdź odpowiedź 400.
- Dołącz nagłówek x-signature (HMAC-SHA256) — jest wymagany — i sprawdź, że jego brak lub nieprawidłowy podpis zwraca 401.
