Dla programistów

Dokumentacja API

REST API do integracji dowolnego sklepu z ReviewBasis — także takiego, który nie ma gotowej integracji (Shoper, WooCommerce, BaseLinker, Allegro). Zgłaszasz zamówienia, my wysyłamy zaproszenia o opinię, a Ty odbierasz opinie przez API albo webhooki.

Wprowadzenie

Wszystkie adresy są względem bazowego URL. Ciała żądań i odpowiedzi są w formacie JSON (pola w konwencji snake_case).

Base URL: https://reviewbasis.com/api/v1

Najkrótsza integracja to jedno wywołanie po realizacji zamówienia — resztą (opóźnienie, wysyłka, przypomnienia) zajmuje się ReviewBasis:

curl https://reviewbasis.com/api/v1/invitations \
  -H "Authorization: Bearer rb_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "klient@example.com",
    "customer_name": "Anna",
    "order_ref": "ZAM-1001",
    "products": [
      { "external_id": "SKU-12", "name": "Młynek ręczny Basic", "gtin": "5901234123457" }
    ]
  }'

Uwierzytelnianie

Każde żądanie (poza openapi.json) wymaga klucza API w nagłówku Authorization. Klucz wygenerujesz w panelu: Ustawienia → API. Pełną wartość widać tylko raz — przechowuj ją bezpiecznie po stronie serwera i nigdy w kodzie front-endu.

Authorization: Bearer rb_xxxxxxxxxxxxxxxxxxxxxxxx

Sprawdź, czy klucz działa:

curl https://reviewbasis.com/api/v1/me -H "Authorization: Bearer rb_TWOJ_KLUCZ"

{
  "organization": { "name": "Sklep Demo", "slug": "sklep-demo" },
  "plan": "PRO",
  "invitations_remaining": 4832,
  "rating": { "average": 4.38, "count": 8 },
  "api_version": "2026-08-11"
}

Limity i wersjonowanie

• Rate limit: ~120–300 żądań na minutę na IP, zależnie od endpointu. Przekroczenie zwraca 429 z kodem rate_limited.
• Limit zaproszeń: miesięczny, zależny od planu. Po wyczerpaniu tworzenie zaproszeń zwraca 402; odczyt opinii działa dalej.
• Wersja: aktualna to 2026-08-11, zwracana w nagłówku X-ReviewBasis-Api-Version. Zmiany łamiące kompatybilność wprowadzimy jako nową ścieżkę wersji, nie po cichu.

Błędy

Błędy mają stały kształt z maszynowo czytelnym kodem:

{ "error": { "code": "limit_reached", "message": "Wyczerpano miesięczny limit zaproszeń w planie." } }

Zaproszenia

Zgłoś zamówienie po jego realizacji. Endpoint jest idempotentny po order_ref — powtórne zgłoszenie tego samego numeru nie wyśle klientowi drugiego maila (wróci w polu skipped).

{ "created": 1, "skipped": 0, "rejected": 0, "limit_reached": false }

{
  "order_ref": "ZAM-1001",
  "status": "COMPLETED",
  "sent_at": "2026-08-04T09:00:00.000Z",
  "completed_at": "2026-08-06T18:12:00.000Z",
  "review_count": 2
}

Opinie i oceny

Pobieraj opublikowane opinie i agregaty, żeby wyświetlać je we własnym frontendzie. Zwracamy tylko opinie opublikowane; nigdy nie ujawniamy adresu e-mail autora ani danych, na które nie wyraził zgody.

{
  "data": [
    {
      "id": "cmsn…",
      "type": "product",
      "rating": 5,
      "title": "Świetna kawa",
      "body": "Etiopia Guji pięknie kwiatowa…",
      "author": "Ewa",
      "city": "Warszawa",
      "verified": true,
      "published_at": "2026-08-06T18:12:00.000Z",
      "product": { "external_id": "KAW-ETI", "name": "Kawa Etiopia Guji, 1 kg" },
      "reply": null
    }
  ],
  "page": 1, "total_pages": 1, "total": 1
}

{
  "name": "Sklep Demo",
  "label": "Bardzo dobra",
  "rating": { "average": 4.38, "count": 8, "histogram": { "1": 0, "2": 0, "3": 1, "4": 3, "5": 4 } }
}

{
  "external_id": "KAW-ETI",
  "name": "Kawa Etiopia Guji, 1 kg",
  "label": "Znakomita",
  "rating": { "average": 5, "count": 1, "histogram": { "1":0,"2":0,"3":0,"4":0,"5":1 } }
}

Webhooki

Zamiast odpytywać API, zarejestruj adres URL — wyślemy na niego żądanie POST za każdym razem, gdy zajdzie subskrybowane zdarzenie. Zdarzenia: review.published (opinia opublikowana) i review.replied (sklep odpowiedział). Webhooki możesz też dodać w panelu (Ustawienia → API).

curl https://reviewbasis.com/api/v1/webhooks \
  -H "Authorization: Bearer rb_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://sklep.pl/hooks/reviewbasis", "events": ["review.published"] }'

{ "id": "cmsn…", "url": "https://sklep.pl/hooks/reviewbasis", "events": ["review.published"], "enabled": true, "secret": "whsec_…" }

Ładunek dostarczany na Twój URL:

{
  "id": "evt_…",                 // stałe dla zdarzenia — obsługuj idempotentnie
  "event": "review.published",
  "created_at": "2026-08-11T12:00:00.000Z",
  "api_version": "2026-08-11",
  "data": { /* obiekt opinii jak w GET /reviews */ }
}

Weryfikacja podpisu

Każda dostawa ma nagłówek X-ReviewBasis-Signature: sha256=… — to HMAC-SHA256 surowego ciała żądania, kluczowany sekretem webhooka. Zweryfikuj go, zanim zaufasz danym:

import crypto from "crypto";

function verify(rawBody, signature, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Dostawa jest best-effort z krótkim timeoutem; odpowiedz kodem 2xx. Ostatni status i licznik błędów widać w panelu i w GET /webhooks. Ze względu na możliwe ponowienia — obsługuj zdarzenia po ich id idempotentnie.

OpenAPI

Pełna specyfikacja maszynowa (OpenAPI 3.1) jest dostępna publicznie — zaimportuj ją do Postmana, Insomnii albo wygeneruj z niej klienta SDK:

https://reviewbasis.com/api/v1/openapi.json