Universal integration

Dla kogo jest integracja uniwersalna

Integracja uniwersalna jest najlepszym wyborem, gdy sklep ma własny silnik, indywidualny koszyk, niestandardowy checkout albo zespół techniczny, który może dodać niewielki fragment kodu po stronie sklepu.

Nie wymaga wtyczki

Działa przez skrypt i postback API.

Bezpieczna dla klucza API

Klucz zostaje na backendzie sklepu.

Uniwersalna

Można ją wdrożyć w dowolnym e-commerce.

Jak wygląda proces

1

Afiliant generuje link

Link prowadzi przez Linkolino, np. `https://app.linkolino.pl/r/abc123`. Po kliknięciu zapisujemy click i przekierowujemy klienta do sklepu.

2

Sklep zapamiętuje identyfikator

Na stronie sklepu zapisujesz `visitor_id` w cookie, sesji albo danych koszyka. Ten identyfikator pozwala później przypisać zamówienie do kliknięcia.

3

Klient składa zamówienie

Checkout działa normalnie. Linkolino nie musi uczestniczyć w procesie płatności ani znać danych karty.

4

Backend sklepu wysyła postback

Po złożeniu albo opłaceniu zamówienia backend sklepu wysyła `order_id`, `amount` i `visitor_id` do Linkolino.

5

Linkolino tworzy konwersję

System sprawdza program, liczy prowizję według ustawień programu i pokazuje konwersję w panelach merchanta oraz afilianta.

Konfiguracja po stronie sklepu

Minimalne wdrożenie składa się z dwóch części. Pierwsza działa w przeglądarce i tylko zapamiętuje identyfikator. Druga działa na backendzie i wysyła potwierdzone dane zamówienia.

1. Skrypt zapamiętujący `visitor_id`

Skrypt można wkleić globalnie w szablonie sklepu albo przez Google Tag Manager. Nie umieszczaj w nim klucza API.

Przykład prostego snippetu

<script>
  (function () {
    var params = new URLSearchParams(window.location.search);
    var visitorId = params.get("ll_visitor_id") || params.get("visitor_id");

    if (visitorId) {
      var expires = new Date();
      expires.setDate(expires.getDate() + 30);
      document.cookie =
        "linkolino_visitor_id=" + encodeURIComponent(visitorId) +
        "; expires=" + expires.toUTCString() +
        "; path=/; SameSite=Lax";
    }
  })();
</script>

2. Zapis identyfikatora przy zamówieniu

Przy checkout najlepiej przepisać `linkolino_visitor_id` z cookie do sesji, koszyka albo metadanych zamówienia. Dzięki temu backend ma dostęp do tej wartości w momencie wysyłki postbacku.

Postback z backendu sklepu

Postback to server-side request wysyłany z backendu sklepu do Linkolino. To jest rekomendowana metoda rejestracji konwersji, bo nie zależy od przeglądarki klienta i nie ujawnia klucza API.

Endpoint i payload

POST https://app.linkolino.pl/api/postback/PROGRAM_ID
X-Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "order_id": "ORD-12345",
  "amount": "249.90",
  "currency": "PLN",
  "visitor_id": "VISITOR_ID_FROM_COOKIE_OR_SESSION",
  "customer_id": "optional-customer-id",
  "sub_id": "optional-campaign"
}

Pola wymagane

Pole	Wymagane	Opis
order_id	tak	Unikalny numer zamówienia w sklepie.
amount	tak	Wartość zamówienia, od której Linkolino oblicza prowizję.
visitor_id	zalecane	Identyfikator kliknięcia zapisany wcześniej w sklepie.
currency	nie	Kod waluty, domyślnie `PLN`.
customer_id	nie	Wewnętrzny identyfikator klienta, jeśli sklep go posiada.
sub_id	nie	Dodatkowe oznaczenie kampanii lub źródła.

Przykład curl

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

Odpowiedź sukcesu

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

Bezpieczeństwo i poprawność danych

Nie pokazuj `api_key` w JavaScript

Klucz API powinien być używany tylko na backendzie sklepu. Frontendowy skrypt może zapisać identyfikator, ale nie powinien tworzyć finalnej konwersji z sekretem.

Używaj unikalnego `order_id`

To chroni przed podwójnym naliczeniem prowizji dla tego samego zamówienia.

Wysyłaj postback po właściwym statusie

Najczęściej będzie to zamówienie opłacone albo zaakceptowane. Samo utworzenie koszyka zwykle nie powinno naliczać prowizji.

Obsłuż zwroty i anulacje

Jeśli sklep pozwala anulować lub refundować zamówienie, trzeba ustalić operacyjny proces korekty konwersji w Linkolino.

Jak przetestować integrację

1. Utwórz program afiliacyjny i skopiuj `PROGRAM_ID` oraz klucz API z panelu Integracje.
2. Wygeneruj link afiliacyjny i kliknij go w nowej sesji przeglądarki.
3. Sprawdź, czy sklep zapisał `visitor_id` w cookie, sesji albo zamówieniu testowym.
4. Złóż testowe zamówienie.
5. Wyślij postback z backendu albo ręcznie przez `curl` na środowisku testowym.
6. Jesli rotujesz klucz API, natychmiast zaktualizuj konfiguracje backendu i ponow testowy postback nowym kluczem.
7. Sprawdź, czy konwersja pojawiła się w panelu merchanta.

Najczęstsze pytania

Czy da się wdrożyć integrację tylko przez wklejenie skryptu?

Da się wykrywać zamówienia po stronie przeglądarki, ale nie rekomendujemy tego jako finalnego rozliczania prowizji. Skrypt może pomagać w attribution, a finalna konwersja powinna przyjść z backendu sklepu.

Czy Linkolino musi znać dane klienta?

Nie. Do podstawowego działania wystarczy `order_id`, kwota i `visitor_id`. Jeśli chcesz przekazać identyfikator klienta, użyj wewnętrznego ID albo hasha, nie pełnych danych osobowych.

Czy Linkolino obsługuje płatność?

Nie w tym flow. Sklep obsługuje płatność normalnie, a Linkolino dostaje informację o zamówieniu po fakcie.

Kiedy wysłać postback?

Najlepiej po statusie, który biznesowo oznacza sprzedaż kwalifikującą się do prowizji: opłacone, zaakceptowane albo zrealizowane, zależnie od zasad programu.