SentraX Portal — Documentação

Guia para times de produto (SentraX e integradores) que querem que o Portal venda, cobre e gerencie o ciclo de vida das contas da sua plataforma.

O que o Portal faz por você

O SentraX Portal cuida de tudo entre o seu produto e o dinheiro: página de assinatura white-label, cobrança (PIX/boleto/cartão, recorrente ou carnê), inadimplência com carência, suspensão e reativação automáticas, trocas de plano e autoatendimento do cliente final.

Para a sua plataforma entrar nesse ciclo, você só precisa expor uma pequena API interna de provisionamento. O Portal chama a sua API nos momentos certos — você nunca precisa consultar o Portal.

As 5 operações canônicas

O contrato do Portal com QUALQUER plataforma são 5 operações. Cada uma vira uma (ou mais) chamadas HTTP à sua API, configuradas no catálogo de drivers do Portal — sem código novo no Portal.

Operação	Quando o Portal chama	O que sua API deve fazer
`provision`	Assinatura ativou (1º pagamento confirmado ou trial iniciado)	Criar a conta/workspace do cliente e retornar um identificador (vira o `externalRef` do Portal)
`sync_limits`	Troca de plano ou re-aplicação de limites	Aplicar os novos limites/plano na conta
`set_status`	Suspensão (inadimplência pós-carência) ou reativação (pagamento)	Bloquear/desbloquear o acesso da conta
`deprovision`	Cancelamento efetivado	Encerrar/arquivar a conta
`health`	Teste de conexão (admin) e verificação periódica	Responder 200 se a API está saudável

Blueprint recomendado

O padrão do ecossistema (implementado primeiro pelo SentraX Docs) é uma API interna REST:

POST   /api/internal/v1/tenants            → provision  (201 { "id": "..." })
PUT    /api/internal/v1/tenants/:id/limits → sync_limits
PATCH  /api/internal/v1/tenants/:id/status → set_status  (body: { "status": "active" | "suspended" })
DELETE /api/internal/v1/tenants/:id        → deprovision
GET    /api/internal/v1/health             → health

Você não é obrigado a usar exatamente esses paths/shapes — o motor do Portal se adapta à sua API via configuração (binding de campos, multi-step, captura de valores de resposta). Mas seguir o blueprint torna o onboarding trivial.

Autenticação

Header estático com token secreto (padrão do ecossistema):

x-sentrax-internal-token: <token forte, por ambiente>

O token fica cifrado no Portal e nunca aparece em logs (valores sensíveis são redigidos). OAuth2 client-credentials também é suportado se sua API preferir.

O que o Portal envia no provision

Campos típicos (configuráveis por binding):

{
  "name": "<companyName do cliente final>",
  "email": "<ownerEmail>",
  "slug": "<slug do operador ou derivado>",
  "external_reference": "<id da assinatura no Portal>",
  "limits": { "<limite declarado no plano>": 123 }
}

A resposta do provision deve conter o id da conta criada — o Portal captura (externalRef) e usa em todas as chamadas seguintes.

Idempotência e retry

O Portal retenta erros transitórios (5xx, 429, timeout, rede) com backoff exponencial; 429 respeita Retry-After. Erros 4xx não são retentados.
Se sua API suportar, declare um header de chave de idempotência (ex.: Idempotency-Key) — o Portal gera uma chave única por execução e a repete em todos os retries. Torne o provision idempotente por essa chave (ou por external_reference) para não criar conta duplicada.
Toda chamada fica registrada no log de operações do Portal (com corpo sensível redigido) — o operador vê sucesso/falha por assinatura no admin.

SSO via OIDC (opcional, padrão do ecossistema)

Apps SentraX delegam login ao Portal (IdP central, modelo Google Account):

Discovery: /.well-known/openid-configuration no domínio do Portal
Scope sentrax emite claims customizadas: tenant_id, role, operator_id
Assinatura RS256

O runbook completo de onboarding de cliente OIDC é fornecido pelo time SentraX durante a integração.

Checklist de onboarding

O que o time da plataforma entrega ao time do Portal:

Base URL da API interna (por ambiente)
Token de autenticação (gerado por vocês, forte, um por ambiente)
Mapa de limites: quais chaves de limite a plataforma entende (ex.: seats, page_views) — elas são declaradas nos planos do catálogo
Confirmação de idempotência no provision (chave ou external_reference)

Com isso, o Portal configura o driver, roda o smoke test no admin (health + provision de teste) e a plataforma entra no ciclo de vida completo.

Exemplo real: SentraX Status

O Status expõe a API interna no blueprint acima; o Portal provisiona a página de status do cliente no provision, aplica limites de monitores no sync_limits, congela a página em set_status: suspended e arquiva no deprovision. Login via OIDC com o mesmo SSO do ecossistema.