Chamar a API

Use o access token para agir em nome do usuário, conheça os endpoints exclusivos de parceiro e entenda a máscara que protege os dados do tenant.

Depois que o usuário consentiu e você trocou o código pelo token (veja Do código ao token), você já pode chamar a API em nome dele — dentro do limite dos scopes aprovados e consentidos.

Autenticação: Bearer token

Envie o access_token (orb_at_...) no header Authorization:

curl https://api.orbitsender.com/api/external/partner/statistics?days=30 \
  -H "Authorization: Bearer orb_at_..."

Token curto e rotativo

O access token vive cerca de 1 hora (expires_in: 3600). Quando expirar, use o refresh_token para obter um novo — sem incomodar o usuário. O refresh é rotativo: cada uso invalida o anterior. Veja Do código ao token.

Spec OpenAPI para gerar cliente / validar contrato

A especificação completa está publicada em /openapi.yaml (o mesmo arquivo que gera esta referência). Importe em Postman/Insomnia ou use em CI para gerar um cliente tipado — sem transcrever campos à mão.

Endpoints exclusivos de parceiro

Estes endpoints vivem sob /api/external/partner/* e foram desenhados para o programa de parceiros — respostas agregadas, mascaradas e sem PII.

Identidade da conta

GET /api/external/partner/me — tenant_ref opaco por-app + plano + limites. Não exige scope.

Estatísticas agregadas

GET /api/external/partner/statistics?days=30 — KPIs do tenant, sem PII. Scope: statistics:read.

Listar campanhas

GET /api/external/partner/campaigns — lista paginada e mascarada. Scope: campaigns:read.

Criar link de fastlogin

POST /api/external/partner/fastlogin — link SSO de uso único. Scope: fastlogin:create.

Reconcilie contas com /me

Chame GET /api/external/partner/me logo após emitir o token para obter um tenant_ref — identificador opaco, estável e escopado ao seu app. Guarde-o para mapear cada token à conta do seu lado (sem depender do state) e para detectar quando dois usuários seus conectam a mesma conta OrbitSender (mesmo tenant_ref). O mesmo tenant_ref chega nos webhooks que você configura, então dá pra correlacionar evento ↔ conta direto.

Exemplo — gerar um link de fastlogin (SSO delegado):

curl -X POST https://api.orbitsender.com/api/external/partner/fastlogin \
  -H "Authorization: Bearer orb_at_..."

{
  "success": true,
  "url": "https://app.orbitsender.com/auth/fastlogin?code=orb_fl_...",
  "expires_in": 120
}

Os demais endpoints `/api/external/*`

Os outros recursos da API (canais, segmentos, campanhas, configurações) aceitam o Bearer de parceiro — desde que o scope correspondente tenha sido aprovado pelo superadmin e consentido pelo usuário. Se o scope não foi concedido, a chamada é recusada.

O webhook da conta (edit-webhooks/test-webhook) é uma exceção: ele pertence ao dono da conta e não é acessível pelo Bearer de parceiro. Para receber eventos você configura o webhook do seu app no Portal do Desenvolvedor — veja Receber webhooks.

Ou seja: o mesmo token abre exatamente as portas que os scopes descrevem, nem mais nem menos. Consulte a referência de scopes para saber qual permissão cada endpoint exige.

Máscara: o que o parceiro NÃO vê

Quando a chamada chega com um token de parceiro (via='partner_app'), a resposta passa por um filtro default-deny (allowlist). Ele existe para proteger o tenant: você recebe o que precisa para operar, mas nunca os dados sensíveis do usuário.

O que é removido / bloqueado	Por quê
PII — telefones, JIDs de grupo, nomes de contatos	O parceiro nunca vê dados pessoais dos contatos do tenant.
Cadência anti-ban (`dispatch_rates`)	Fica fora de `settings`; é a proteção contra banimento do WhatsApp.
Credenciais de marketplace (`integrations:*`)	O scope `integrations:` é sempre bloqueado* para parceiro.
IDs internos de canal	Viram referências opacas (`channel_ref`), sem expor o id real.

integrations:* nunca é concedido a parceiro

Os scopes integrations:read e integrations:write são bloqueados no programa de parceiros — eles dariam acesso a segredos brutos de marketplace. Não adianta solicitá-los na revisão.

channel_ref é opaco, estável e por-app

O channel_ref é um identificador opaco e estável do canal: é o mesmo valor entre chamadas, sobrevive ao refresh do token e a revogar + reautorizar o app. Use-o como chave para de-duplicar/mapear canais do seu lado. Ele é escopado ao seu app — apps diferentes recebem valores diferentes para o mesmo canal físico (sem correlação cruzada entre parceiros) — e não expõe o token nem o telefone do canal. É somente-leitura: os endpoints de escrita de canal (desconectar/editar/excluir/QR) usam o id_channel (token), nunca o channel_ref.

Limitação: escrita de canal só nos canais que você criou

Hoje os endpoints de escrita de canal são chaveados pelo id_channel (token), que só é devolvido na resposta de create-channel. Para canais pré-existentes (que o usuário já tinha), a listagem entrega apenas o channel_ref mascarado — então, por ora, a escrita só é viável nos canais criados pela sua integração. Aceitar o channel_ref diretamente nas escritas está no planejamento futuro.

Token de parceiro vs. API key

O mesmo backend atende dois tipos de credencial. Entenda a diferença antes de escolher:

Aspecto	API key (`sk_live_...`)	Token de parceiro (`orb_at_...`)
Dono	O próprio tenant (chave dele)	Você (o app), agindo pelo usuário
Consentimento	Não há — é a chave do dono	O usuário consentiu por-scope no `/authorize`
Alcance	Todos os dados do tenant	Somente os scopes aprovados e consentidos
Resposta	Dados completos (sem máscara)	Mascarada (sem PII, sem cadência, `channel_ref`)
*`integrations:`**	Permitido	Bloqueado
Header	`x-api-key: sk_live_...`	`Authorization: Bearer orb_at_...`

Rate limit e erros

Cada app tem seus próprios limites — por exemplo 300 req/min nas chamadas /api/external/* e 30 req/min no /api/oauth/token. Dimensione a integração para respeitá-los e trate o HTTP 429 com backoff. Os números completos por grupo de endpoint, os códigos de erro do fluxo OAuth e as boas práticas de tratamento estão em Gerenciar vínculos e erros.