Autenticação

A API oferece dois modos de autenticação:

• Chave de API (sk_live_..., header x-api-key) — self-service. Você integra a sua própria conta; a chave dá acesso total ao seu tenant.
• OAuth de parceiro (Authorization: Bearer) — para apps de terceiro que agem em nome de outros usuários, com consentimento por-scope, alcance limitado e resposta mascarada. Veja a seção Partner.

Esta página cobre a chave de API. Cada chave pertence a um tenant (sua conta) e herda os limites do seu plano.

Header de autenticação

Envie a chave em todas as requisições:

x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obtendo uma chave

1. Acesse o painel do OrbitSender.
2. Vá em Configurações → Chaves de API (requer um plano com api_access).
3. Clique em Gerar chave. O valor sk_live_... é exibido uma única vez — copie e guarde com segurança.

Você pode ter até 5 chaves por conta, ativá-las/desativá-las e revogá-las a qualquer momento.

Exemplo de requisição

curl https://api.orbitsender.com/api/external/ping \
  -H "x-api-key: sk_live_sua_chave_aqui"

Resposta:

{
  "success": true,
  "message": "Pong! Sua chave de API é válida.",
  "timestamp": "2026-06-26T14:30:45.123Z"
}

Modo de teste (sandbox) — sk_test_

Antes de mexer na sua conta real, teste a integração sem nenhum risco: envie uma chave que começa com sk_test_ no header x-api-key. Requisições com chave de teste são respondidas inteiramente com dados sintéticos e nunca tocam o seu banco, os seus canais ou o pipeline de envio.

curl https://api.orbitsender.com/api/external/list-channels \
  -H "x-api-key: sk_test_qualquer_coisa"

• Qualquer string sk_test_... é aceita — você não precisa de plano, canal conectado nem QR escaneado para começar a ler a documentação e rodar exemplos.
• Os endpoints de leitura devolvem exemplos fixos; os de criação respondem 201 sintético; nada é persistido e nenhuma campanha é enviada.
• Troque para a sua chave sk_live_... quando quiser exercitar o fluxo real.

Convenções de resposta

Todas as respostas são JSON.

• Sucesso: incluem "success": true e os dados da operação.
• Erro: incluem "success": false, um error e uma message (descrição). Nos erros de autenticação, escopo e rate limit o próprio error já é o identificador estável — ramifique por ele: invalid_token, insufficient_scope, rate_limited. Os 403 de limite de plano trazem limitExceeded: true com limitType (channels, campaigns, segments, groups, group_monitorings), current e max. Os 501 trazem code: "not_implemented".

{
  "success": false,
  "error": "Bad Request",
  "message": "O campo \"name\" é obrigatório no body da requisição."
}

Códigos de status

Rate limit

Cada credencial tem um teto de requisições por janela:

Ao estourar, a resposta é 429 com o header Retry-After (segundos até poder repetir) e os headers RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Faça backoff antes de retentar.

Idempotência (evitar disparo duplicado)

Os endpoints de criação (create-channel, create-segment e create-campaign/message · poll · carousel) aceitam o header opcional Idempotency-Key. Reenviar o mesmo POST com a mesma chave devolve a resposta original em vez de criar um segundo recurso — essencial quando um POST dá timeout e você precisa retentar sem duplicar a campanha/canal/segmento.

curl -X POST https://api.orbitsender.com/api/external/create-campaign/message \
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: 8f3a...seu-uuid-unico" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Paginação

Apenas dois endpoints paginam: GET /api/external/list-channels e GET /api/external/partner/campaigns. Ambos aceitam o query param page (inteiro, padrão 1) e devolvem total, page, per_page e pages (total de páginas) ao lado do array — itere page de 1 até pages para varrer tudo.

Os demais endpoints de listagem (list-segments, list-webhooks, list-settings) não paginam: ignoram page e devolvem a coleção inteira, sem o campo pages.