API brandingu

Dostosuj powierzchnie widoczne dla klienta — chrome SPA, e-maile z zaproszeniami, nagłówki i stopki raportów PDF — z użyciem Twojego logo, kolorów akcentu i nazwy produktu. Obiekt Branding jest przypisany per organizacja i obowiązuje dla każdej sesji utworzonej w ramach tej organizacji.

Obiekt Branding

{
  "logo_url": "https://cdn.acme.com/logo.png",
  "wordmark_url": "",
  "favicon_url": "https://cdn.acme.com/favicon.ico",
  "primary_color": "#0F3D91",
  "accent_color": "#FFB400",
  "product_name_override": "Acme FieldView",
  "support_email": "support@acme.com",
  "support_url": "https://help.acme.com",
  "email_from_name": "Acme Claims",
  "pdf_footer_text": "Acme Insurance — claim report",
  "updated_at": "2026-05-10T14:00:00Z"
}

Pole	Typ	Uwagi
`logo_url`	URL	Kwadratowe lub poziome; renderowane w wysokości 40px w nagłówku SPA i 64px w nagłówku PDF.
`wordmark_url`	URL	Opcjonalne. Używane obok `logo_url` na szerszym chrome.
`favicon_url`	URL	PNG / ICO 32×32. Serwowane z Twojego CDN; nie jest mirrorowane.
`primary_color`	hex (#rrggbb)	Główny akcent — używany dla przycisków, linków i pasa okładki PDF.
`accent_color`	hex (#rrggbb)	Drugorzędny akcent — używany dla wyróżnień, odznak, obrysów sparkline.
`product_name_override`	string ≤ 120	Zastępuje "NexBasira" w ciągach widocznych dla użytkownika (tytuł strony, tematy wiadomości e-mail).
`support_email`	email	Wyświetlane na stronach błędów oraz w stopkach e-maili z zaproszeniami. Puste = domyślna wartość platformy.
`support_url`	URL	Tak samo — linkowane z menu pomocy w SPA.
`email_from_name`	string ≤ 120	Nazwa nadawcy w wychodzącej poczcie transakcyjnej (nadal routowana przez naszą uwierzytelnioną domenę, aby zachować zgodność DMARC).
`pdf_footer_text`	string ≤ 255	Jednowierszowa stopka na każdej stronie raportu audytowego PDF.

Pusty ciąg w dowolnym polu = domyślna wartość platformy. Wiersz Branding jest tworzony automatycznie przy pierwszym GET, więc nigdy nie zobaczysz tu błędu 404.

Odczyt brandingu

GET /api/v1/public/branding — zakres branding:read

curl https://app.nexbasira.com/api/v1/public/branding \
  -H "Authorization: Bearer nb_sec_..."

Aktualizacja brandingu

PATCH /api/v1/public/branding — zakres branding:write

Aktualizacja częściowa — podaj tylko te pola, które chcesz zmienić. Wyślij "" w dowolnym polu, aby przywrócić w nim domyślną wartość platformy. Kolory hex są walidowane względem #rrggbb; nieprawidłowa wartość zwraca 400.

curl -X PATCH https://app.nexbasira.com/api/v1/public/branding \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#0F3D91",
    "logo_url": "https://cdn.acme.com/logo-2026.png"
  }'

Zwraca świeżo zaktualizowany obiekt Branding. Zmiana jest natychmiastowa przy kolejnym załadowaniu strony — nie ma cache CDN do wyczyszczenia dla SPA. W przypadku e-maili z zaproszeniami i PDF-ów nowy branding stosuje się do wszystkiego, co wygenerowano po zaksięgowaniu PATCH.

Częste błędy

Status	Kod	Kiedy
400	`validation_error`	Nieprawidłowy kolor hex, źle sformułowany URL lub ciąg przekraczający maksymalną długość.
403	`permission_denied`	Poświadczenie nie ma wymaganego zakresu (`branding:read` dla GET, `branding:write` dla PATCH).

Uwagi

Brak przesyłania obrazów. Platforma nie hostuje Twoich zasobów — podaj adresy HTTPS do obrazów, które już serwujesz z własnego CDN. Dzięki temu unieważnianie cache pozostaje pod Twoją kontrolą.
Wymuszenie same-origin. Adresy logo i favicon muszą serwować Access-Control-Allow-Origin: * (lub origin Twojego SPA), aby przeglądarka mogła je wyrenderować wewnątrz widgetu osadzonego w iframe.
Audytowane. Każdy PATCH generuje zdarzenie audytowe org.branding_updated z różnicą na poziomie pól, więc zmanipulowane logo jest możliwe do powiązania z poświadczeniem i znacznikiem czasu.