API de branding

Personalize as superfícies visíveis ao cliente — chrome da SPA, e-mails de convite, cabeçalhos + rodapés dos relatórios PDF — com o seu logótipo, cores de destaque e nome de produto. O objeto Branding é por organização e aplica-se a todas as sessões criadas sob essa organização.

O objeto 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"
}

Campo	Tipo	Notas
`logo_url`	URL	Quadrado ou horizontal; renderizado a 40px de altura no cabeçalho da SPA, 64px no cabeçalho do PDF.
`wordmark_url`	URL	Opcional. Usado juntamente com `logo_url` em chrome mais largo.
`favicon_url`	URL	PNG / ICO 32×32. Servido a partir da sua CDN; não é replicado.
`primary_color`	hex (#rrggbb)	Cor de destaque principal — usada em botões, ligações e na faixa de capa do PDF.
`accent_color`	hex (#rrggbb)	Destaque secundário — usado em realces, badges e traços de sparkline.
`product_name_override`	string ≤ 120	Substitui "NexBasira" nas strings visíveis ao utilizador (título da página, assuntos dos e-mails).
`support_email`	email	Mostrado nas páginas de erro + nos rodapés dos e-mails de convite. Vazio = predefinição da plataforma.
`support_url`	URL	Idem — ligado a partir do menu de ajuda da SPA.
`email_from_name`	string ≤ 120	Nome de remetente no correio transacional de saída (continua encaminhado pelo nosso domínio autenticado para preservar o alinhamento DMARC).
`pdf_footer_text`	string ≤ 255	Rodapé de uma linha em cada página do relatório de auditoria em PDF.

String vazia em qualquer campo = predefinição da plataforma. A linha de Branding é criada automaticamente no primeiro GET, por isso nunca verá um 404 aqui.

Ler o branding

GET /api/v1/public/branding — âmbito branding:read

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

Atualizar o branding

PATCH /api/v1/public/branding — âmbito branding:write

Atualização parcial — forneça apenas os campos que quer alterar. Envie "" em qualquer campo para o repor na predefinição da plataforma. As cores hexadecimais são validadas contra #rrggbb; um valor inválido devolve 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"
  }'

Devolve o objeto Branding recém-atualizado. A alteração é imediata no próximo carregamento de página — não há cache de CDN a invalidar para a SPA. Para os e-mails de convite + PDFs, o novo branding aplica-se a tudo o que for gerado depois de o PATCH ser processado.

Erros comuns

Estado	Código	Quando
400	`validation_error`	Cor hexadecimal inválida, URL malformado ou string acima do comprimento máximo.
403	`permission_denied`	A credencial não tem o âmbito necessário (`branding:read` para GET, `branding:write` para PATCH).

Notas

Sem upload de imagens. A plataforma não aloja os seus recursos — forneça URLs HTTPS para imagens que já serve a partir da sua CDN. Isto mantém a invalidação de cache sob o seu controlo.
Imposição de mesma origem. Os URLs de logótipo + favicon têm de servir Access-Control-Allow-Origin: * (ou a origem da sua SPA) para que o navegador os possa renderizar dentro do widget de embed em iframe.
Auditado. Cada PATCH regista um evento de auditoria org.branding_updated com o diff ao nível do campo, por isso um logótipo adulterado é rastreável até uma credencial + selo temporal.