Dokumentacja API

Wersja 1 · dla agencji, generatorów stron i firm z wieloma witrynami · plan Enterprise

API pozwala zakładać strony z gotowym banerem zgody prosto z Twojego systemu - na przykład w chwili, gdy generator stron tworzy witrynę klienta. Jednym zapytaniem zakładasz stronę, ustawiasz podstawowy wygląd i teksty, publikujesz baner i dostajesz kod do wstawienia w <head>. Pełna konfiguracja (lista ciasteczek, kategorie, Consent Mode, rejestr zgód, dokumenty) zostaje w panelu.

Szybki start

1. Plan Enterprise włączamy po rozmowie - napisz do nas.
2. W panelu wejdź w Ustawienia konta - API i utwórz klucz. Skopiuj go od razu - pokazujemy go tylko raz.
3. Załóż pierwszą stronę:

curl -X POST https://cookiebanerpro.pl/api/v1/sites \
  -H "Authorization: Bearer cbp_live_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{"domain": "sklep-klienta.pl", "externalId": "projekt-1001"}'

W odpowiedzi dostajesz stronę z opublikowanym banerem i gotowym kodem instalacyjnym w polu site.install.html. Wstaw go jak najwyżej w <head> każdej podstrony - i gotowe.

Klucze i uwierzytelnianie

Adres bazowy: https://cookiebanerpro.pl/api/v1. Każde zapytanie wysyła klucz w nagłówku:

Authorization: Bearer cbp_live_...

• Klucze tworzy i unieważnia administrator konta w panelu (Ustawienia konta - API). Konto może mieć do 20 aktywnych kluczy - np. osobny dla każdego systemu.
• Klucz daje dostęp do wszystkich stron konta. Trzymaj go wyłącznie po stronie serwera - nigdy w kodzie strony ani w aplikacji mobilnej.
• Przechowujemy tylko skrót klucza. Zgubiony klucz unieważnij i utwórz nowy.
• Treść zapytań i odpowiedzi to JSON w UTF-8. Daty w formacie ISO 8601.

GET/me - sprawdzenie klucza: konto, plan, limity i zużycie.

Zakładanie strony

POST/sites

{
  "domain": "sklep-klienta.pl",
  "name": "Sklep Kowalskich",
  "externalId": "projekt-1001",
  "lang": "pl",
  "template": "light",
  "style": "box",
  "image": true,
  "colors": { "primary": "#1E2B2F", "background": "#FFFFFF", "text": "#3A4A4F" },
  "texts": { "title": "Szanujemy Twoją prywatność" },
  "policyUrl": "https://sklep-klienta.pl/polityka-cookies",
  "rejectButton": true,
  "publish": true,
  "clientEmail": "wlasciciel@sklep-klienta.pl",
  "clientAccess": "odczyt"
}

Wymagane jest tylko domain (z https://, www. i ścieżką też zadziała - zapiszemy samą domenę). Pozostałe pola są opcjonalne.

Odpowiedź 201:

{
  "site": {
    "id": "4f1c...e9", "key": "k3x9a1b2c3d4", "domain": "sklep-klienta.pl",
    "name": "Sklep Kowalskich", "externalId": "projekt-1001", "createdVia": "api",
    "published": true, "version": 1, "publishedAt": "2026-10-02T10:15:00.000Z",
    "settings": { "style": "box", "image": true, "colors": {...}, "texts": {...},
                  "policyUrl": "https://...", "rejectButton": true, "enabled": true },
    "install": {
      "scriptUrl": "https://cookiebanerpro.pl/c/k3x9a1b2c3d4.js",
      "html": "<script>window.dataLayer = ... </script>\n<script src=\"...\" async></script>",
      "gtm": { "tagType": "Custom HTML", "trigger": "Consent Initialization - All Pages", "html": "..." }
    },
    "panelUrl": "https://cookiebanerpro.pl/panel#strona=4f1c...e9"
  }
}

Kod z install.html ustawia też domyślne zgody Google Consent Mode v2 (wszystko odrzucone do decyzji odwiedzającego). Jeśli strona korzysta z Google Tag Managera, zaimportuj szablon tagu cookiebanerpro.tpl i dodaj tag „CookieBanerPro - baner zgody” z kluczem strony i regułą Consent Initialization - All Pages. Tag Niestandardowy HTML nie gwarantuje, że domyślne zgody zadziałają przed innymi tagami.

Pola konfiguracji

Te same pola przyjmuje zakładanie strony i jej zmiana.

Zmiany i publikacja

PATCH/sites/{id} - zmienia pola konfiguracji oraz name i externalId. Domyślnie od razu publikuje; z "publish": false zmienia tylko szkic.

curl -X PATCH https://cookiebanerpro.pl/api/v1/sites/4f1c...e9 \
  -H "Authorization: Bearer cbp_live_TWOJ_KLUCZ" -H "Content-Type: application/json" \
  -d '{"colors": {"primary": "#E85D04"}, "texts": {"accept": "Zgadzam się"}}'

POST/sites/{id}/publish - publikuje szkic (np. po zmianach z "publish": false albo w panelu).

DELETE/sites/{id} - usuwa stronę razem z banerem, statystykami i rejestrem zgód. Kod na stronie przestaje wyświetlać baner. Odpowiedź 204.

Lista i szczegóły

GET/sites?externalId=projekt-1001 - lista stron konta, od najnowszych. Filtry: externalId, domain; stronicowanie: page, limit (do 100). Odpowiedź zawiera total.

GET/sites/{id} - szczegóły strony z bieżącymi ustawieniami i kodem instalacyjnym.

GET/templates - dostępne szablony.

Klient agencji

Właściciel strony może dostać własny dostęp do panelu - tylko do swojej strony. Podaj clientEmail przy zakładaniu strony albo wyślij zaproszenie później:

POST/sites/{id}/client z treścią {"email": "wlasciciel@sklep.pl", "access": "odczyt"}

• odczyt (domyślnie) - widzi ustawienia, statystyki i rejestr zgód; edycja - zmienia baner bez publikacji; publikacja - zmienia i publikuje.
• Klient dostaje e-mail z jednorazowym linkiem (ważnym 7 dni). Konto założy w minutę, jeśli go nie ma.
• Gdy ten sam adres ma już dostęp do innej strony konta, dopisujemy mu kolejną - nie wysyłamy drugiego zaproszenia.
• Plan, płatności i pozostałe strony konta zostają niewidoczne dla klienta.

Statystyki

GET/sites/{id}/stats?days=30 - odsłony i decyzje dzień po dniu (do 365 dni) oraz podsumowanie z odsetkiem zgód (acceptRate, w procentach).

Błędy i limity

Błędy mają postać {"error": {"code": "...", "message": "..."}}.

Limity stron i odsłon wynikają z umowy Enterprise - sprawdzisz je w GET /me.

OpenAPI i przykłady

Pełna specyfikacja w formacie OpenAPI 3.1: /api/v1/openapi.json - wczytasz ją do Postmana, Insomnii albo generatora klienta.

PHP

$ch = curl_init('https://cookiebanerpro.pl/api/v1/sites');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CBP_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['domain' => $domena, 'externalId' => (string) $projektId, 'template' => 'site:' . $idWzorca]),
]);
$odp = json_decode(curl_exec($ch), true);
$kod = $odp['site']['install']['html']; // wstaw do <head> strony klienta

JavaScript (Node.js)

const r = await fetch('https://cookiebanerpro.pl/api/v1/sites', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CBP_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ domain, externalId: String(projektId), lang: 'pl' }),
});
const { site, error } = await r.json();
if (error) throw new Error(error.message);
console.log(site.install.html);