Branding-API

Mukauta asiakkaalle näkyvät pinnat — SPA-kehys, kutsusähköpostit, PDF-raporttien ylä- ja alatunnisteet — logollasi, korostusväreilläsi ja tuotenimelläsi. Branding-objekti on organisaatiokohtainen ja koskee jokaista kyseisen organisaation alla luotua istuntoa.

Branding-objekti

{
  "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"
}

Kenttä	Tyyppi	Huomiot
`logo_url`	URL	Neliö tai vaaka; renderöidään 40px korkuisena SPA:n ylätunnisteessa ja 64px PDF:n ylätunnisteessa.
`wordmark_url`	URL	Valinnainen. Käytetään `logo_url`-kentän rinnalla leveämmässä kehyksessä.
`favicon_url`	URL	32×32 PNG / ICO. Tarjoillaan omasta CDN:stäsi; ei peilata.
`primary_color`	hex (#rrggbb)	Pääkorostus — käytetään painikkeissa, linkeissä ja PDF:n kansinauhassa.
`accent_color`	hex (#rrggbb)	Toissijainen korostus — käytetään korostuksissa, merkeissä ja sparkline-viivoissa.
`product_name_override`	string ≤ 120	Korvaa "NexBasira" käyttäjälle näkyvissä teksteissä (sivun otsikko, sähköpostien aiherivit).
`support_email`	email	Näytetään virhesivuilla ja kutsusähköpostien alatunnisteissa. Tyhjä = alustan oletus.
`support_url`	URL	Sama — linkittää SPA:n ohjevalikosta.
`email_from_name`	string ≤ 120	Lähtevän transaktiopostin From-nimi (reititetään edelleen todennetun domainimme kautta DMARC-linjauksen säilyttämiseksi).
`pdf_footer_text`	string ≤ 255	Yhden rivin alatunniste PDF-auditointiraportin jokaisella sivulla.

Tyhjä merkkijono missä tahansa kentässä = alustan oletus. Branding-rivi luodaan automaattisesti ensimmäisellä GET-kutsulla, joten et koskaan näe 404:ää tässä.

Lue brändäys

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

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

Päivitä brändäys

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

Osittainen päivitys — anna vain ne kentät, joita haluat muuttaa. Lähetä "" missä tahansa kentässä palauttaaksesi sen alustan oletukseen. Heksavärit validoidaan muotoa #rrggbb vasten; virheellinen arvo palauttaa 400:n.

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"
  }'

Palauttaa juuri päivitetyn Branding-objektin. Muutos näkyy heti seuraavalla sivunlatauksella — SPA:lle ei ole CDN-välimuistia tyhjennettäväksi. Kutsusähköposteissa ja PDF-tiedostoissa uusi brändäys koskee kaikkea PATCHin jälkeen luotua.

Yleiset virheet

Tila	Koodi	Milloin
400	`validation_error`	Virheellinen heksaväri, väärin muotoiltu URL tai maksimipituuden ylittävä merkkijono.
403	`permission_denied`	Tunnukselta puuttuu scope (`branding:read` GET:lle, `branding:write` PATCH:lle).

Huomiot

Ei kuvien latausta. Alusta ei isännöi assetejasi — anna HTTPS-URLit kuviin, joita jo tarjoilet CDN:stäsi. Näin välimuistin invalidointi pysyy sinun hallinnassasi.
Same-origin-pakotus. Logo- ja favicon-URLien on tarjottava Access-Control-Allow-Origin: * (tai SPA-originisi), jotta selain voi renderöidä ne iframe-embed-widgetin sisällä.
Auditoitu. Jokainen PATCH luo org.branding_updated-auditointitapahtuman kenttätason diffillä, joten peukaloitu logo on jäljitettävissä tunnukseen ja aikaleimaan.