Zapowiedź

Dokumentacja poglądowa. Interfejs jest w trakcie udostępniania — przykłady mają charakter zapowiedzi, a finalne wartości potwierdzimy przy starcie.

Klienci, locale, zgody

Zasób Customers przechowuje minimum potrzebne do rozmowy: numer telefonu, język kontaktu i dowód zgody na kontakt. Klienta identyfikujesz swoim external_customer_id, więc upsert jest bezpieczny do wielokrotnego wywołania.

Base URL: https://api.callbotagent.ai/api/v1/commerce. Wszystkie żądania podpisujesz HMAC (X-CBA-Key-Id, X-CBA-Timestamp, X-CBA-Signature); mutacje dodają Idempotency-Key. Budowa podpisu: ./authentication.md.

Model klienta

Ciało w JSON snake_case. Numer telefonu w formacie E.164, locale w BCP 47.

Pole	Typ	Opis
`external_customer_id`	string	Twój identyfikator klienta (klucz upsertu).
`phone`	string	Numer w formacie E.164, np. `"+48512123456"`.
`locale`	string	Znacznik języka BCP 47, np. `"pl-PL"`.
`consent.status`	enum	`granted` \| `withdrawn` \| `unknown`.
`consent.proof`	object	Dowód zgody: `source`, `reference`, `collected_at` (RFC 3339 UTC).

Bez ważnej zgody (consent.status: granted) klient nie przejdzie kwalifikacji do kontaktu — zobacz ./qualification-scheduling.md.

Operacje

PUT /customers/{externalCustomerId}

Idempotentny upsert klienta (dane kontaktu, locale, dowód zgody). Scope customers:write.

curl -X PUT https://api.callbotagent.ai/api/v1/commerce/customers/CUSTOMER-8821 \
  -H "X-CBA-Key-Id: cba_test_••••••••" \
  -H "X-CBA-Timestamp: 2026-07-10T12:34:56Z" \
  -H "X-CBA-Signature: v1=9f8c2a...e41" \
  -H "Idempotency-Key: customer-upsert-8821-01" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "CUSTOMER-8821",
    "phone": "+48512123456", "locale": "pl-PL",
    "consent": { "status": "granted", "proof": {
      "source": "checkout_optin", "reference": "form-2026-07-09-2231",
      "collected_at": "2026-07-09T22:31:07Z" } }
  }'
# 200 OK → { "external_customer_id": "CUSTOMER-8821", "outcome": "upserted",
#   "consent": { "status": "granted" } }

const body = {
  external_customer_id: "CUSTOMER-8821",
  phone: "+48512123456", locale: "pl-PL",
  consent: { status: "granted", proof: {
    source: "checkout_optin", reference: "form-2026-07-09-2231",
    collected_at: "2026-07-09T22:31:07Z" } },
};
const res = await fetch(
  "https://api.callbotagent.ai/api/v1/commerce/customers/CUSTOMER-8821",
  { method: "PUT", headers: {
    "X-CBA-Key-Id": "cba_test_••••••••",
    "X-CBA-Timestamp": "2026-07-10T12:34:56Z",
    "X-CBA-Signature": "v1=9f8c2a...e41",
    "Idempotency-Key": "customer-upsert-8821-01",
    "Content-Type": "application/json",
  }, body: JSON.stringify(body) },
);
const data = await res.json(); // { external_customer_id: "...", outcome: "upserted" }

$body = [
  "external_customer_id" => "CUSTOMER-8821",
  "phone" => "+48512123456", "locale" => "pl-PL",
  "consent" => ["status" => "granted", "proof" => [
    "source" => "checkout_optin", "reference" => "form-2026-07-09-2231",
    "collected_at" => "2026-07-09T22:31:07Z"]],
];
$ch = curl_init("https://api.callbotagent.ai/api/v1/commerce/customers/CUSTOMER-8821");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-CBA-Key-Id: cba_test_••••••••",
    "X-CBA-Timestamp: 2026-07-10T12:34:56Z",
    "X-CBA-Signature: v1=9f8c2a...e41",
    "Idempotency-Key: customer-upsert-8821-01",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($body),
]);
$data = json_decode(curl_exec($ch), true); // { external_customer_id: "...", ... }

GET /customers/{externalCustomerId}

Zwraca zsanityzowany rekord klienta (numer zredukowany, status zgody bez wrażliwych szczegółów). Scope customers:read. Brak zasobu → 404 resource_not_found.

POST /customers/{externalCustomerId}/anonymize

Idempotentna anonimizacja: usuwa dane osobowe klienta, zachowując nieodwracalny znacznik w historii. Scope customers:erase. Ponowne wywołanie na już zanonimizowanym kliencie zwraca ten sam wynik (bez błędu).

Anonimizacja jest nieodwracalna. Po jej wykonaniu numer telefonu i dowód zgody nie są już dostępne, a klient nie może zostać zakwalifikowany do kontaktu bez ponownego upsertu i nowej zgody.