Referência da API

Estado da aplicacao

Unica rota publica. Distingue "app viva" de "banco fora" — sintomas parecidos, causas opostas.

Exemplo

curl 'https://orbicast.com.br/api/v1/saude'

Respostas

• 200 Estado atual. `status` e "ok" ou "degradado".

Lista sessoes

Escopo exigido: `sessoes:ler`.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Sessoes com status e numero em E.164.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Cria sessao

Escopo exigido: `sessoes:gerenciar`. NAO pareia — o pareamento exige o checklist do chip confirmado e e feito em `POST /sessoes/{id}/parear`.

Corpo

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/sessoes' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "integracao-n8n"
}'

Respostas

• 201 Sessao criada, aguardando pareamento.
• 400 Validacao falhou.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Detalhe da sessao, com cota e estado de entrega

Escopo exigido: `sessoes:ler`. `entrega` = BASE_INSUFICIENTE significa que ainda nao ha dados para diagnosticar — nao confunda com NORMAL.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Detalhe.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Encerra a conexao

Escopo exigido: `sessoes:gerenciar`. DESCONECTA; nao apaga. O material Signal permanece, entao reconectar nao exige novo QR.

Parâmetros

Exemplo

curl -X DELETE 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Encerrada.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Inicia o pareamento — por QR ou por codigo

Escopo exigido: `sessoes:gerenciar`. Dois caminhos, e a diferenca de tempo e do protocolo: - **Sem corpo (QR):** o QR chega ~1s depois; consulte `GET /sessoes/{id}/qr` ou acompanhe `GET /eventos/stream`. - **Com `telefone` (codigo):** `codigoPareamento` vem JA nesta resposta. No celular: WhatsApp > Aparelhos conectados > Conectar aparelho > Conectar com numero de telefone. O corpo e OPCIONAL: parear por QR nao tem o que informar.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/parear' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
  "telefone": "exemplo"
}'

Respostas

• 200 Pareamento iniciado. `codigoPareamento` e null no fluxo de QR.
• 400 Telefone malformado.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.
• 409 Checklist do chip nao confirmado.

QR corrente

Escopo exigido: `sessoes:ler`. Expira em ~60s e e regenerado. `null` = ainda nao chegou, ou ja pareou (veja `status`).

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/qr' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Texto do QR e status.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Estado Signal: pre-keys e canais por dispositivo

Escopo exigido: `protocolo:ler` — e material criptografico, entao exige escopo proprio. Devolve contagem e estrutura, jamais o material em si.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/signal' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Identidade, pre-keys e canais.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Historico de mensagens

Escopo exigido: `mensagens:ler`. O CORPO nunca sai por aqui, mesmo com `PERSISTIR_CONTEUDO=true`: so tipo, tamanho e status.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/mensagens' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Metadados das mensagens.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Envia mensagem de texto

Escopo exigido: `mensagens:enviar`. Passa pelos 8 guardas anti-banimento — os mesmos da tela. Use `?simular=true` para rodar os guardas SEM enviar e sem gastar reputacao do numero.

Parâmetros

Corpo

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/mensagens' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
  "sessaoId": "3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84",
  "destinatario": "+5535999998888",
  "texto": "Olá! Mensagem de teste."
}'

Respostas

• 200 Enviada (ou veredito da simulacao).
• 400 Validacao falhou.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 409 Sessao nao conectada ou pausada.
• 422 Guarda recusou: fora da allowlist, sem interacao previa, ou conteudo repetido. Insistir nao resolve — corrija o destinatario ou o texto.
• 429 Rate limit da chave, ou guarda de volume (cota, rajada, horario).

Envia midia (imagem, video, audio ou documento)

Escopo exigido: `mensagens:enviar`. Corpo em `multipart/form-data` — o arquivo vai no campo `arquivo`, os demais como texto: `sessaoId`, `destinatario`, `tipo` (IMAGEM|VIDEO|AUDIO|DOCUMENTO), `legenda` (opcional; nao vale para AUDIO), `nomeArquivo` (obrigatorio em DOCUMENTO — sem ele, usa o nome do proprio upload) e `comoNotaDeVoz` ("true" envia AUDIO como PTT). Passa pelos MESMOS guardas do envio de texto. O de conteudo repetido compara o hash dos BYTES: a mesma imagem para 3 destinatarios distintos e recusada, ainda que a legenda mude. Limite de 16 MB. O mimetype e o declarado no upload — os bytes nao sao inspecionados. Os bytes NAO sao persistidos: o banco guarda tipo, tamanho, mimetype, nome e o hash.

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/mensagens/midia' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Enviada. Devolve tambem o tipo e o tamanho em bytes.
• 400 Arquivo ausente, acima de 16 MB, mimetype incoerente com o tipo, DOCUMENTO sem nome, ou legenda em AUDIO.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 409 Sessao nao conectada ou pausada.
• 422 Guarda recusou — inclusive a MESMA midia repetida.
• 429 Rate limit da chave, ou guarda de volume (cota, rajada, horario).

Destinatarios autorizados

Escopo exigido: `sessoes:gerenciar`. Allowlist VAZIA bloqueia todo envio — nao e "sem restricao", e o oposto.

Exemplo

curl 'https://orbicast.com.br/api/v1/allowlist' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Lista e total.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Autoriza um destinatario

Escopo exigido: `sessoes:gerenciar`. Idempotente — numero ja cadastrado devolve a linha existente. Vale na hora, sem reiniciar.

Corpo

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/allowlist' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
  "numero": "exemplo",
  "rotulo": "exemplo"
}'

Respostas

• 201 Autorizado.
• 400 Numero invalido.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Remove a autorizacao

Escopo exigido: `sessoes:gerenciar`. Aceita qualquer formato — o numero e normalizado, como na gravacao. Idempotente.

Parâmetros

Exemplo

curl -X DELETE 'https://orbicast.com.br/api/v1/allowlist/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Removido.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Configuracao GLOBAL: janela, gravacao e limites

Escopo exigido: `sessoes:ler`. Devolve TRES visoes, e a distincao importa: `salva` (o que esta no banco), `efetiva` (o que VALE, com o padrao preenchendo os buracos — e o que os guardas usam) e `padrao` (o do codigo). Ler so `salva` vazia levaria a concluir que nao ha janela; ha, so nao foi customizada.

Exemplo

curl 'https://orbicast.com.br/api/v1/configuracao' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Salva, efetiva e padrao.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Numeros com quem houve conversa

Escopo exigido: `mensagens:ler`. A unidade aqui e o INTERLOCUTOR, nao a mensagem — e o caminho quando algo deu errado com UMA pessoa. Filtre por `?sessaoId=`.

Exemplo

curl 'https://orbicast.com.br/api/v1/conversas' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Resumo por numero.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

O que foi trocado com um numero

Escopo exigido: `mensagens:ler`. Aceita qualquer formato de numero. O CORPO so aparece quando a sessao permite gravar — a mesma regra de `/mensagens`, sem porta lateral.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/conversas/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Conversa em ordem.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Volume, razao envio/recebimento, entrega e latencia

Escopo exigido: `sessoes:ler`. A razao envio/recebimento e o numero mais preditivo do conjunto: acima de 3,0 o perfil ja se parece com disparo. `entrega = BASE_INSUFICIENTE` significa que ainda NAO HA dados — nao confunda com NORMAL.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/desempenho' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Desempenho.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Historico de conexao e quedas

Escopo exigido: `sessoes:ler`. Queda de rede e normal; o que preocupa e a FREQUENCIA subir sem explicacao — sinal de restricao de conta, nao de internet ruim. Por isso devolve a serie, e nao um contador.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/estabilidade' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Transicoes.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Cota, indice de risco e destinatarios suspeitos

Escopo exigido: `sessoes:ler`. As tres coisas se leem JUNTAS: cota estourada com risco alto e um quadro; cota folgada com suspeitos acumulando e outro. O indice (0-100) e heuristica da comunidade — a Meta nao publica criterio.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/protecao' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Estado da protecao.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Libera um destinatario marcado como suspeito

Escopo exigido: `sessoes:gerenciar`. O detector marca quem acumula mensagens sem entrega — mas celular desligado por dias produz o mesmo padrao. Liberar e dizer "eu verifiquei". Remove a MARCA, nao o destinatario.

Parâmetros

Exemplo

curl -X DELETE 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/suspeitos/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Liberado.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

As 5 confirmacoes previas ao pareamento

Escopo exigido: `sessoes:ler`.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/checklist' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Respostas e data de ativacao.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Override desta sessao sobre o global

Escopo exigido: `sessoes:ler`. Devolve `sessao` (o override), `efetiva` (o que vale) e `herdada` (o que valeria sem override) — a diferenca entre as duas ultimas e o que esta sessao customizou.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/configuracao' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 As tres visoes.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Retrato forense do fim do chip

Escopo exigido: `sessoes:ler`. `null` e resposta legitima: a maioria das sessoes esta viva, e ausencia de incidente e o estado normal.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/incidente' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Incidente ou null.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Registra o fim do ciclo de vida do chip

Escopo exigido: `sessoes:gerenciar`. Desfecho: BANIDO, ENCERRADO_MANUAL ou EXPIRADO. Captura o estado no momento do fim (dias de vida, reputacao final, congelamentos, volume) porque DEPOIS nao ha como reconstruir — e o unico dado que responde "o que fizemos diferente no numero que durou seis meses?".

Parâmetros

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/sessoes/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84/incidente' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 201 Registrado.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.
• 404 Recurso nao encontrado.

Lista as assinaturas de webhook

Escopo exigido: `sessoes:gerenciar`. O segredo HMAC nunca sai — a resposta diz apenas se ha (`temSegredo`).

Exemplo

curl 'https://orbicast.com.br/api/v1/webhooks' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Assinaturas.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Assina eventos, entregues por POST no seu endpoint

Escopo exigido: `sessoes:gerenciar`. Existe porque o SSE nao serve para integracao — um n8n do outro lado da rede nao consome `EventSource`. **Eventos:** `mensagem.recebida`, `mensagem.enviada`, `mensagem.status`, `sessao.conectada`, `sessao.desconectada`, `sessao.qr`, `sessao.pausada` (o freio automatico agiu) e `protocolo.evento`. `'*'` cobre todos MENOS `protocolo.evento`, que e alto volume e exige pedido pelo nome com `ignorarProtocolo: false`. **Envelope:** `{ id, evento, sessaoId, em, dados }`. O CORPO da mensagem nunca vai em `dados` — o webhook nao e uma porta lateral para o que a API se recusa a devolver. **Assinatura (com `segredoHmac`):** `X-Webhook-Hmac` traz HMAC-SHA512 de `{timestamp}.{corpo bruto}`, com `X-Webhook-Hmac-Algorithm: sha512` e `X-Webhook-Timestamp` em ms. Leia os BYTES antes de desserializar: reserializar o JSON muda o corpo e a assinatura nao bate — e a causa mais comum de "HMAC invalido". **Retry:** ate 5 tentativas, exponencial com jitter (2s a 60s). Respostas 4xx nao sao retentadas. Cada tentativa vira linha no historico, e falhas consecutivas demais DESATIVAM a assinatura com o motivo registrado.

Corpo

Exemplo

curl -X POST 'https://orbicast.com.br/api/v1/webhooks' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "exemplo",
  "eventos": "exemplo",
  "sessaoId": "3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84",
  "segredoHmac": "exemplo",
  "ignorarProtocolo": true,
  "tiposProtobuf": "exemplo"
}'

Respostas

• 201 Assinatura criada.
• 400 URL invalida ou evento fora do catalogo.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Historico de entregas da assinatura

Escopo exigido: `sessoes:gerenciar`. Responde "por que meu webhook parou de chegar?". `statusHttp` nulo com `erro` preenchido = nao houve resposta (rede, DNS, timeout); com status = chegou e foi recusado.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/webhooks/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Tentativas, da mais recente.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Remove a assinatura

Escopo exigido: `sessoes:gerenciar`. O historico vai junto.

Parâmetros

Exemplo

curl -X DELETE 'https://orbicast.com.br/api/v1/webhooks/3f1a9c42-8b7e-4d21-9a55-1c0e7b2f6d84' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Removida.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Historico de eventos de protocolo

Escopo exigido: `protocolo:ler`. O par do stream: o que ja aconteceu.

Parâmetros

Exemplo

curl 'https://orbicast.com.br/api/v1/eventos' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Eventos por camada.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.

Eventos ao vivo (SSE)

Escopo exigido: `protocolo:ler`. `text/event-stream`; entrega tambem os ultimos 30s ao conectar, porque o pareamento ocorre antes de a conexao abrir.

Exemplo

curl 'https://orbicast.com.br/api/v1/eventos/stream' \
  -H 'Authorization: Bearer wsk_live_SUA_CHAVE_AQUI'

Respostas

• 200 Stream SSE.
• 401 Credencial ausente ou invalida.
• 403 Chave sem o escopo exigido.