Endpoints e Contratos Nitro BFF

/api/branding

GET

Resolução multi-tenant de identidade visual a partir do domínio canônico da requisição (Host). Retorna dados de tema, paleta, logos e identificador do parceiro.

/manifest.webmanifest

GET

Endpoint canônico de Web App Manifest W3C. Resolve o tenant por Host, atribui id: "/" para isolamento soberano de PWA e serve o manifesto JSON com ícones dinâmicos versionados.

/api/pwa-icon

GET / HEAD

Geração em tempo real e entrega de ícones PWA (180, 192, 512) rasterizados em PNG nativo via @resvg/resvg-js. Implementa Safe Zone de 80% para maskable e fallback para monograma.

/api/og

GET

Geração em tempo real de cards Open Graph rasterizados em PNG nativo (1200x630) via @resvg/resvg-js. Implementa salvaguarda anti-SSRF com validação estrita de DNS/IP e cache em camadas na Vercel Edge CDN (Vary: Host).

/api/auth/me

GET

Retorna o perfil, permissões e papel efetivo do usuário autenticado no contexto do parceiro e organização ativa.

/api/organizations

GET

Lista as organizações autorizadas para o parceiro resolvido no domínio.

/api/organizations

POST

Dispara o provisionamento idempotente de uma nova organização via RPC connect.provision_organization.

/api/organizations/:id

PATCH

Atualiza metadados ou razão social da organização especificada sob autorização administrativa.

/api/organizations/:id

DELETE

Desprovisionamento seguro de organização com confirmação estrita de segurança.

/api/store-groups

GET / POST

Listagem e criação de agrupamentos de lojas/clusters operacionais.

/api/store-groups/:id

PATCH / DELETE

Atualização cadastral ou exclusão de grupo de lojas.

/api/locations

GET / POST

Listagem de filiais e provisionamento transacional de nova unidade física associada a um grupo de lojas.

/api/locations/:id

PATCH / DELETE

Atualização de parâmetros operacionais ou exclusão de unidade física com checagem de integridade relacional.

/api/locations/by-slug/:slug

GET

Resolução canônica de unidade a partir do slug semântico para a topologia /location/:slug/…​.

/api/locations/:id/tags

GET / PUT

Consulta e sincronização atômica de tags/segmentos associados a uma unidade.

/api/tags

GET / POST

Catálogo analítico de tags e criação de classificadores corporativos.

/api/tags/:id

PATCH / DELETE

Atualização ou desprovisionamento de tag analítica.

/api/users

GET

Listagem de membros e cargos atribuídos na organização com suporte a paginação e filtros.

/api/users/:id

PATCH / DELETE

Alteração de papéis RBAC ou revogação de acesso de membro da organização.

/api/invitations

GET / POST

Listagem de convites pendentes e disparo de novos convites de onboarding com geração de tokens CSPRNG de uso único.

/api/invitations/:id

DELETE

Cancelamento e revogação de convite pendente.

/api/invitations/:id/resend

POST

Reenvio de convite por e-mail com renovação da janela de expiração temporal.

/api/invitations/verify

GET

Validação pública e segura de token de convite para apresentação da tela de onboarding.

/api/invitations/accept

POST

Consumo atômico do convite e associação do usuário autenticado aos papéis organizacionais via RPC connect.accept_user_invitation.

/api/integrations/whatsapp/instances

GET

Lista instâncias de WhatsApp com isolamento multi-tenant. Aceita organizationId e locationId (para filtro restrito da unidade). Bloqueia acesso cruzado com HTTP 403.

/api/integrations/whatsapp/instances

POST

Criação transacional de instância vinculada à organização e unidade física ativa.

/api/integrations/whatsapp/instances/sync

POST

Sincronização em massa de status das instâncias junto aos provedores de mensageria.

/api/integrations/whatsapp/instances/:id

PATCH / DELETE

Atualização de parâmetros ou remoção de instância de WhatsApp.

/api/integrations/whatsapp/instances/:id/qr

GET

Obtenção do QR Code de pareamento. Suporta provedores múltiplos com ativação prévia de energia (power-on na Zapster API) e entrega em Data URL Base64.

/api/integrations/whatsapp/instances/:id/qr/refresh

POST

Força a regeneração da matriz óptica de QR Code no provedor.

/api/integrations/whatsapp/instances/:id/sync

POST

Consulta imediata e pontual de status da instância específica no provedor.

/api/integrations/whatsapp/instances/:id/disconnect

POST

Desconexão forçada da sessão de mensageria junto ao gateway.

/api/integrations/whatsapp/webhook

POST

Proxy Forwarder de webhooks para o Edge Ingress Gateway nativo da VPS com limite de 10 MB e zero I/O relacional em ambiente Serverless.

/api/integrations/whatsapp/webhook/:provider

POST

Rota especializada de recepção direta por provedor (zapster ou evolution).

/api/integrations/email

GET / DELETE

Consulta das credenciais configuradas (SMTP ou OAuth) ou desconexão do provedor de mensageria.

/api/integrations/email/test

POST

Envio de mensagem de teste para atestação de conectividade com proteção anti-SSRF em servidores SMTP customizados.

/api/integrations/email/oauth/authorize

POST

Inicia o fluxo de autorização OAuth 2.0 (Google Workspace / Microsoft 365) com geração de state criptográfico.

/api/integrations/oauth/callback

GET

Recepção do callback OAuth, validação de integridade e handoff opaco via cookies transitórios protegidos.

/api/integrations/oauth/exchange

POST

Troca atômica do código de autorização pelos tokens de acesso e persistência segura em banco.

/api/notifications/active

GET

Consulta autenticada de notificações ativas da Home consumindo a RPC connect.get_active_feed_notifications. Cabeçalho SWR: private, max-age=5, stale-while-revalidate=15.

/api/notifications/markers

GET

Consulta leve de marcadores de severidade crítica (CRITICAL + ACTIVE) para sinalização visual imediata em seletores de contexto e menus de navegação.

/api/notifications/:id/dismiss

POST

Registro transacional e idempotente de dispensa individual da notificação para o usuário na tabela connect.user_notification_dismissals.