API documentation

Wdrażasz własny sklep albo indywidualny checkout?

Zacznij od instrukcji integracji uniwersalnej. Opisuje identyfikator kliknięcia, skrypt po stronie sklepu i backendowy postback.

Otwórz integrację uniwersalną

Korzystasz z WooCommerce?

Skorzystaj z dedykowanej instrukcji pluginu, webhooków i statusów zamówień WooCommerce.

Otwórz dokumentację WooCommerce

Przegląd

Linkolino API obejmuje tracking kliknięć, rejestrację konwersji i integracje oparte o webhooki. Kliknięcia afiliacyjne są śledzone przez `/r/:code`, a sprzedaż powinna być raportowana z backendu sklepu.

Autentykacja

Zapytania do API wymagają klucza API. Dla zapytań server-side używaj nagłówka `X-Api-Key`. Autentykacja przez query parameter jest wspierana tylko dla prostych scenariuszy kompatybilności.

Zalecany nagłówek

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://app.linkolino.pl/api/postback/PROGRAM_ID?order_id=123&amount=99.99

Jesli zrotujesz klucz API w panelu merchanta, poprzedni klucz przestaje dzialac natychmiast. Zaktualizuj backend sklepu przed wyslaniem kolejnego postbacku.

1. Tracking kliknięć

Kliknięcia są rejestrowane automatycznie, gdy użytkownik otwiera link afiliacyjny. Linkolino zapisuje kliknięcie i przekierowuje klienta na adres docelowy.

https://app.linkolino.pl/r/abc123def

Użyj `sub_id`, `sub_id_2` i `sub_id_3`, gdy chcesz przekazać oznaczenia kampanii albo placementu.

2. Rejestracja konwersji

Po transakcji wyślij postback z backendu, aby zarejestrować konwersję i naliczyć prowizję afiliantowi.

GET  /api/postback/:program_id\nPOST /api/postback/:program_id

Parametr	Typ/limit	Wymagany/okno	Opis
order_id	string	tak	Unikalny identyfikator zamówienia w Twoim systemie.
amount	decimal	tak	Wartość zamówienia, np. `199.99`.
visitor_id	string	zalecane	Identyfikator odwiedzającego zapisany z kliknięcia afiliacyjnego.
currency	string	nie	Kod waluty, domyślnie `PLN`.
customer_id	string	nie	Wewnętrzne ID klienta albo hash.
sub_id	string	nie	Opcjonalne oznaczenie kampanii.

GET

curl -H "X-Api-Key: sk_live_abc123" \
  "https://app.linkolino.pl/api/postback/PROGRAM_ID?order_id=ORD-001&amount=299.99"

POST JSON

curl -X POST \
  -H "X-Api-Key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"ORD-001","amount":299.99,"visitor_id":"VISITOR_ID"}' \
  "https://app.linkolino.pl/api/postback/PROGRAM_ID"

Odpowiedź sukcesu

{
  "success": true,
  "conversion_id": "550e8400-e29b-41d4-...",
  "status": "pending"
}

Kanoniczny payload konwersji

Wszystkie integracje powinny mapować dane zamówienia do jednego wspólnego kontraktu konwersji. Minimalny payload wymaga `program_id`, `order_id`, `currency`, jednego pola identyfikacji (`visitor_id` albo `click_id`) oraz jednej kwoty (`gross_amount`, `net_amount`, `items_amount` albo starsze `amount`).

{
  "program_id": "PROGRAM_ID",
  "order_id": "ORD-001",
  "visitor_id": "VISITOR_ID",
  "click_id": null,
  "customer_id_hash": "sha256(customer-id)",
  "gross_amount": "246.00",
  "net_amount": "200.00",
  "items_amount": "220.00",
  "shipping_amount": "20.00",
  "discount_amount": "10.00",
  "tax_amount": "46.00",
  "currency": "PLN",
  "order_status": "completed",
  "payment_status": "paid",
  "refunded_amount": "0.00",
  "consent_mode": "merchant_consent_required",
  "integration_mode": "plugin",
  "source": "woocommerce"
}

`customer_id_hash` może pomóc w deduplikacji, ale powinien być hashem albo wewnętrznym pseudonimowym identyfikatorem. Nie wysyłaj imion, nazwisk, emaili, telefonów ani adresów dostawy w payloadach konwersji, chyba że istnieje odrębna podstawa prawna i umowa powierzenia.

Wspierane tryby zgód to `merchant_consent_required`, `server_side_required` i `custom`. Merchant odpowiada za konfigurację CMP, zgody cookies i informacje prywatności w sklepie.

3. Integracje platform

WooCommerce

Użyj pluginu WordPress albo wariantu webhook-only, jeśli metadane zamówienia zawierają już `visitor_id`.

Shopify

Rekomendowana ścieżka to aplikacja Shopify z OAuth, webhookami i trackingiem Customer Events.

Stripe

Przekaż `visitor_id` i `program_id` w metadanych Checkout Session.

Sklepy customowe

Użyj uniwersalnego skryptu i backendowego postbacku.

Stripe Checkout Session

const session = await stripe.checkout.sessions.create({
  // ... other parameters
  metadata: {
    visitor_id: req.cookies._mm_track || '',
    program_id: 'YOUR_PROGRAM_ID'
  }
});

4. Limity i błędy

Parametr	Typ/limit	Wymagany/okno	Opis
/r/:code	30/IP	1 min	Limit redirectów afiliacyjnych.
/api/postback/:id	100/IP + program	1 min	Limit postbacków.

Po przekroczeniu limitu API zwraca `429 Too Many Requests`.