Guia de integração — Orquestra WhatsApp Gateway

Guia para quem vai ligar um sistema (condomínio, oficina, loja, ERP) ao gateway e enviar mensagens de WhatsApp. Descreve a API como está em produção, conferida contra o código em 08/11/2026. Começa por um resumo em 5 passos; a lista de todas as rotas está na seção 16.

# 1) token (vale 5 minutos)
curl -X POST https://gateway.orquestrasistemas.com.br/v1/autenticacao/token -H "X-API-Key: <SUA_CHAVE>"

# 2) mensagem
curl -X POST https://gateway.orquestrasistemas.com.br/v1/mensagens \
  -H "Authorization: Bearer <TOKEN>" -H "Idempotency-Key: aviso-0001" -H "Content-Type: application/json" \
  -d '{"destinatario": "(27) 99999-9999", "texto": "Olá! Seu pedido está pronto.", "consentimento": {"evidencia": "Cliente aceitou avisos no cadastro."}}'

1. O que você precisa receber

O gestor do gateway entrega três informações, de preferência pelo botão Copiar dados de integração da tela de chaves, por um canal seguro:

Também importam:

• Tipo da chave. Individual envia sempre pelo mesmo número. Geral envia por um grupo de números e o gateway escolhe qual usar; um mesmo destinatário tende a receber sempre do mesmo número.
• Permissões da chave. Peça ao gestor as que o seu sistema vai usar:

Os dois nomes de cada linha são equivalentes: uma chave com mensagens:enviar vale onde se pede messages.send e vice-versa, e quem pode registrar consentimento também pode consultá-lo. Se faltar alguma, o gestor abre Chaves de API › Editar permissões no painel e marca o que falta: o segredo não muda, o seu sistema não precisa trocar nada e a permissão vale na hora, inclusive para o token já emitido.

Para descobrir, a qualquer momento, a instância e as permissões da sua chave: GET /v1/credenciais/contexto (seção 3). Para conferir se está tudo pronto para enviar: GET /v1/diagnostico (seção 3).

2. Autenticação: chave → token temporário

A chave nunca acompanha as mensagens. Ela só troca por um token temporário (300 segundos), usado nas demais chamadas.

curl -X POST https://gateway.orquestrasistemas.com.br/v1/autenticacao/token \
  -H "X-API-Key: <CHAVE_DE_API>"

{ "token_acesso": "oat_…", "token_tipo": "Bearer", "expira_em_segundos": 300 }

• Use Authorization: Bearer <token_acesso> nas outras rotas. O corpo do pedido de token é ignorado (pode ir vazio).
• Reaproveite o token até uns 30 segundos antes de expirar; não peça um token por mensagem (limite: 30 emissões por minuto). Pedir outro não revoga o anterior.
• Token expirado responde 401 TOKEN_INVALIDO: peça outro e repita a chamada com a mesma Idempotency-Key.
• Conta suspensa, envios pausados, assinatura vencida, aplicação inativa ou chave revogada respondem 403 na hora, mesmo com token válido. Mensagens já aceitas continuam na fila e só saem quando a situação for regularizada.

3. Conferir a credencial

curl https://gateway.orquestrasistemas.com.br/v1/credenciais/contexto \
  -H "Authorization: Bearer <TOKEN>"

{
  "chave_id": "…",
  "tipo_destino": "fixo",
  "instancia_id": "…",
  "grupo_balanceamento_id": null,
  "escopos": ["messages.send", "messages.read"]
}

tipo_destino fixo é chave individual (tem instancia_id); balanceado é chave geral (tem grupo_balanceamento_id). Qualquer token válido pode consultar.

Testar a integração (botão "Testar integração")

GET /v1/diagnostico confere, sem enviar mensagem, tudo o que o gateway exige para despachar: chave ativa e com permissão de envio, conta e aplicação ativas, assinatura vigente, saldo de mensagens do plano, número conectado e não pausado, horário de envio, limites por minuto/hora/dia e fila andando. Qualquer token válido pode chamar (até 20 vezes por minuto); chave sem a permissão de envio recebe só a indicação de que falta essa permissão.

curl "https://gateway.orquestrasistemas.com.br/v1/diagnostico?destinatario=(27)%2099999-9999" \
  -H "Authorization: Bearer <TOKEN>"

{
  "pronto_para_enviar": false,
  "resumo": "Não é possível enviar agora: \"Portaria\" não está conectado (situação: disconnected). Leia o QR Code para conectar.",
  "verificacoes": [
    {
      "codigo": "chave",
      "titulo": "Chave de API ativa",
      "situacao": "ok",
      "detalhe": "Sem data de expiração."
    },
    {
      "codigo": "saldo",
      "titulo": "Saldo de mensagens do plano",
      "situacao": "ok",
      "detalhe": "488 de 500 disponíveis até 07/12/2026, 11:00 (12 enviadas, 0 na fila)."
    },
    {
      "codigo": "numero",
      "titulo": "Número conectado",
      "situacao": "erro",
      "detalhe": "\"Portaria\" não está conectado (situação: disconnected). Leia o QR Code para conectar."
    }
  ],
  "credencial": {
    "chave_id": "…",
    "tipo_destino": "fixo",
    "instancia_id": "…",
    "grupo_balanceamento_id": null,
    "escopos": ["…"]
  },
  "numeros": [
    {
      "instancia_id": "…",
      "nome": "Portaria",
      "situacao": "disconnected",
      "envios_pausados": false,
      "janela_aberta": true
    }
  ],
  "plano": {
    "modelo_cobranca": "mensal",
    "limite_mensagens": 500,
    "usadas_no_periodo": 12,
    "na_fila": 0,
    "disponiveis": 488,
    "…": "…"
  },
  "destino": {
    "destinatario": "+5527999999999",
    "finalidade": "transacional",
    "consentido": true,
    "descadastrado": false
  },
  "verificado_em": "…"
}

• pronto_para_enviar é true quando nenhum item está como erro; aviso não impede o envio (por exemplo, fora do horário: a mensagem espera a janela abrir).
• resumo já vem pronto para mostrar ao usuário; cada item de verificacoes traz titulo e detalhe em português. Códigos possíveis: chave, permissao_envio, conta, aplicacao, assinatura, saldo, numero, janela, limites, fila e destinatario.
• destinatario (opcional, exige permissão de envio) simula a checagem do contato: telefone válido, consentimento para a finalidade (padrão transacional) e descadastro. Sem consentimento, o item fica como aviso se a chave pode registrá-lo no envio (objeto consentimento) e como erro se não pode. Nada é gravado nem enviado.
• Um botão "Testar integração" no seu sistema faz: pedir o token (seção 2; erro aqui significa chave inválida ou conta bloqueada) → chamar GET /v1/diagnostico → mostrar resumo e a lista. Para a prova final, envie uma mensagem real para o seu próprio número.

No painel, a ação Testar de cada chave mostra o mesmo resultado (proprietário, administrador e auditor).

4. Enviar uma mensagem

curl -X POST https://gateway.orquestrasistemas.com.br/v1/mensagens \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: pedido-1234-pronto" \
  -H "Content-Type: application/json" \
  -d '{
    "destinatario": "(27) 99999-9999",
    "texto": "Seu veículo está pronto para retirada.",
    "consentimento": { "evidencia": "Cliente aceitou avisos de serviço no cadastro." }
  }'

Resposta 202 (aceita na fila, ainda não entregue):

{
  "mensagem_id": "…",
  "situacao": "na_fila",
  "criado_em": "…",
  "consulta": "/v1/mensagens/…",
  "requisicao_id": "…"
}

• Idempotency-Key é obrigatório. Use um identificador único por mensagem (1 a 120 caracteres: letras, números, _ . : -; por exemplo, pedido-1234-pronto). Se a rede cair e você repetir o mesmo pedido com a mesma chave, o gateway devolve a mesma mensagem (com a situação atual) em vez de enviar duas vezes — mesmo que você tenha trocado de token. A mesma chave com conteúdo diferente responde 409. Sem o cabeçalho, 400.
• Não envie instância, número remetente nem organização no corpo: quem decide é a chave. Campos desconhecidos respondem 400 ENTRADA_INVALIDA.
• Cada mensagem leva exatamente um conteúdo: texto, arquivo_id, localizacao, contato ou enquete. Dois conteúdos (ou nenhum) respondem 400.
• O 202 é imediato. A mensagem sai respeitando o horário de envio, os limites e o espaçamento do número (seção 11).

4.1 Enviar em lote

Até 100 mensagens numa chamada, cada uma com sua própria chave de idempotência. Um item recusado não impede os outros.

curl -X POST https://gateway.orquestrasistemas.com.br/v1/mensagens/lote \
  -H "Authorization: Bearer <TOKEN>" -H "Idempotency-Key: lote-2026-11-08-0001" -H "Content-Type: application/json" \
  -d '{ "itens": [
        { "chave_idempotencia": "revisao-1001", "mensagem": { "destinatario": "(27) 99999-9999", "texto": "Revisão amanhã às 9h." } },
        { "chave_idempotencia": "revisao-1002", "mensagem": { "destinatario": "(27) 98888-7777", "texto": "Revisão amanhã às 10h." } }
      ] }'

{
  "itens": [
    {
      "chave_idempotencia": "revisao-1001",
      "aceita": true,
      "mensagem_id": "…",
      "situacao": "na_fila",
      "criado_em": "…",
      "consulta": "/v1/mensagens/…"
    },
    {
      "chave_idempotencia": "revisao-1002",
      "aceita": false,
      "erro": {
        "codigo": "CONSENTIMENTO_AUSENTE",
        "mensagem": "Destinatário sem consentimento válido para esta finalidade. …",
        "status": 422
      }
    }
  ],
  "requisicao_id": "…"
}

• O cabeçalho Idempotency-Key (8 a 200 caracteres) identifica o lote: repetir o mesmo lote devolve a mesma resposta; outro conteúdo com a mesma chave responde 409. Cada chave_idempotencia (8 a 200 caracteres) identifica a mensagem e precisa ser diferente das outras do lote (senão 422 IDEMPOTENCIA_DUPLICADA).
• Os itens voltam ordenados por chave_idempotencia, não na ordem enviada: case pelo campo, não pela posição.
• Itens que passarem do saldo do plano são recusados com LIMITE_DO_PLANO_ATINGIDO; os anteriores continuam aceitos.

4.2 Enviar arquivos (anexos)

São duas chamadas: primeiro o arquivo, depois a mensagem com o arquivo_id.

# 1) Envia o arquivo (multipart, campo "arquivo"). Exige a permissão media.write.
curl -X POST https://gateway.orquestrasistemas.com.br/v1/arquivos \
  -H "Authorization: Bearer <TOKEN>" \
  -F "arquivo=@orcamento.pdf;type=application/pdf"
# → 202 { "arquivo_id": "…", "situacao": "disponivel", "tipo_mime": "application/pdf", "tamanho_bytes": 48211 }

# 2) Envia a mensagem com o arquivo.
curl -X POST https://gateway.orquestrasistemas.com.br/v1/mensagens \
  -H "Authorization: Bearer <TOKEN>" -H "Idempotency-Key: orcamento-1234" -H "Content-Type: application/json" \
  -d '{ "destinatario": "(27) 99999-9999", "arquivo_id": "…", "legenda": "Seu orçamento" }'

• Até 16 MB por arquivo, um arquivo por envio e por mensagem. O formato é conferido pelo conteúdo (não pelo nome) e precisa bater com o tipo informado no envio; arquivos do Office com macros são recusados (415 TIPO_INVALIDO).
• Todo arquivo passa por antivírus durante a chamada: quando ela responde, o arquivo já pode ser usado. Se o antivírus não responder, 503 ANTIVIRUS_INDISPONIVEL — tente de novo em instantes. Um envio de arquivo por vez por organização (429 UPLOAD_OCUPADO).
• O arquivo fica guardado cifrado, visível só para a sua chave (outra chave da mesma organização não consegue usá-lo). O espaço conta no limite de armazenamento do plano (413 ARMAZENAMENTO_ESGOTADO).
• O mesmo arquivo_id pode ser usado em várias mensagens (por exemplo, um comunicado em PDF para vários moradores).
• Consultar: GET /v1/arquivos/{arquivo_id} (nome, tipo, tamanho, situação) e GET /v1/arquivos/{arquivo_id}/conteudo (baixa o arquivo), com a permissão media.read.

4.3 Verificar se o número tem WhatsApp

curl -X POST https://gateway.orquestrasistemas.com.br/v1/contatos/verificar \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{ "destinatario": "(27) 99999-9999" }'
# → 200 { "destinatario": "+5527999999999", "tem_whatsapp": true, "verificado_em": "…", "origem": "consulta" }

• Consulta o WhatsApp sem enviar mensagem, pelo número da sua chave (exige messages.send e o número conectado; senão 409 INSTANCIA_DESCONECTADA). Leva até ~12 segundos; se o WhatsApp não responder, 503 VERIFICACAO_INDISPONIVEL — tente de novo.
• O resultado vale por 7 dias (origem: "recente"). Limite de 500 consultas novas por dia por organização e 30 por minuto: consultas em massa parecem varredura e podem levar ao bloqueio do número.
• No painel, cada número pode ligar "Conferir se o destinatário tem WhatsApp antes de cada envio": mensagens para números sem WhatsApp terminam como falhou (motivo numero_sem_whatsapp) sem tentar enviar, e o gateway usa o identificador real do contato — o que evita falhas com números antigos registrados sem o nono dígito.

4.4 Agendar e cancelar

• Agendar: "agendar_para": "2026-11-20T09:00:00-03:00" (até 30 dias à frente; mais que isso, 422 AGENDAMENTO_DISTANTE). A mensagem aparece como na_fila e em GET /v1/filas com agendado_para. Ela também respeita o horário de envio do número.
• Prazo: uma mensagem que não conseguir sair até 24 horas depois do horário previsto (número desconectado, limites, fora do horário) passa a expirada e não é mais enviada.
• Cancelar: POST /v1/mensagens/{mensagem_id}/cancelar (permissão messages.cancel) enquanto estiver na_fila ou agendada → 200 {"cancelada": true}. Depois que o envio começou, ou se já terminou, 409 CANCELAMENTO_INDISPONIVEL.

curl -X POST https://gateway.orquestrasistemas.com.br/v1/mensagens/<MENSAGEM_ID>/cancelar \
  -H "Authorization: Bearer <TOKEN>"

Rotas POST sem corpo (cancelar, conectar, desconectar, iniciar campanha): envie sem Content-Type, ou com Content-Type: application/json e o corpo {}. Cabeçalho JSON com corpo vazio responde 400.

4.5 Saldo do plano

Cada plano tem um limite de mensagens por período da assinatura (do início ao fim da assinatura, não do mês do calendário), somando todas as chaves e números da organização. Consulte com GET /v1/saldo (permissão messages.send ou analytics.read):

{
  "modelo_cobranca": "mensal",
  "limite_mensagens": 500,
  "limite_efetivo": 500,
  "teto_excedente_mensagens": 0,
  "excedente_usado": 0,
  "valor_mensagem_excedente": 0,
  "valor_excedente_estimado_centavos": 0,
  "usadas_no_periodo": 402,
  "na_fila": 15,
  "disponiveis": 83,
  "percentual_usado": 83,
  "periodo_inicio": "2026-11-07T15:56:04.885Z",
  "periodo_fim": "2026-12-07T15:56:04.885Z",
  "recebimento": {
    "incluido": true,
    "limite_recebidas": 100,
    "guardadas_no_periodo": 12,
    "excedentes": 0,
    "descartadas": 0,
    "valor_excedente_centavos": 0,
    "a_cobrar_centavos": 0,
    "retencao_maxima_dias": 30
  }
}

modelo_cobranca diz como o plano cobra:

Exemplo de franquia com excedente: franquia de 1.000, teto de 200 excedentes a R$ 0,12 cada; já foram 1.035 mensagens.

{
  "modelo_cobranca": "franquia_excedente",
  "limite_mensagens": 1000,
  "teto_excedente_mensagens": 200,
  "limite_efetivo": 1200,
  "usadas_no_periodo": 1035,
  "excedente_usado": 35,
  "valor_mensagem_excedente": 0.12,
  "valor_excedente_estimado_centavos": 420,
  "na_fila": 12,
  "disponiveis": 153,
  "percentual_usado": 87,
  "…": "…"
}

O envio é bloqueado ao atingir limite_efetivo (limite do plano + teto de excedente, na franquia).

• Mensagens na fila já reservam saldo; cada mensagem conta uma vez, mesmo com reenvio, e as que falharam não contam.
• Com disponiveis em zero, o envio responde 402 LIMITE_DO_PLANO_ATINGIDO com a data de renovação no title. Não repita automaticamente: avise o responsável, aguarde a renovação ou contrate um plano maior.
• No lote, só os itens que passarem do saldo são recusados. Uma campanha só começa se o saldo cobrir todos os destinatários.
• A repetição de uma mensagem já aceita (mesma Idempotency-Key) continua respondendo 202, sem consumir saldo de novo.
• recebimento mostra o módulo de mensagens recebidas (seção 8.1); incluido: false quando o plano não tem o módulo.
• GET /v1/assinatura (permissão analytics.read) devolve a vigência (inicio_em, fim_em) e os limites contratados.

5. Formato do telefone

Envie o número como o seu sistema tiver guardado. O gateway remove pontuação, espaços, traços e parênteses e inclui o +55 quando houver DDD + número:

Número sem DDD ou estrangeiro sem + responde 400 TELEFONE_INVALIDO: o gateway não adivinha país. As consultas devolvem o número no formato internacional (+55…).

Isso vale para os campos destinatario e destinatarios no corpo das requisições, para o telefone do cartão de contato, e para os filtros remetente (mensagens recebidas) e destinatario (diagnóstico). Exceção: a consulta GET /v1/contatos/consentimentos exige o telefone já em E.164, com o + codificado como %2B (seção 6).

6. Consentimento

Toda mensagem precisa de autorização do destinatário para a finalidade (LGPD e regras do WhatsApp). Duas formas:

1. Antes do envio: POST /v1/contatos/consentimentos com destinatario, finalidade, evidencia e concedido_em opcional (por exemplo, no cadastro do cliente). Exige consents.write.

bash curl -X POST https://gateway.orquestrasistemas.com.br/v1/contatos/consentimentos \ -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \ -d '{ "destinatario": "(27) 99999-9999", "finalidade": "transacional", "evidencia": "Aceitou avisos por WhatsApp no formulário de cadastro em 01/11/2026." }' # → 201 { "id": "…" }

1. No primeiro envio: o objeto consentimento na mensagem (exige a permissão consents.write). Nos envios seguintes ele já existe e pode ser omitido (se vier, é ignorado).

Consultar antes de registrar ou enviar: GET /v1/contatos/consentimentos?destinatario=%2B5527999999999&finalidade=transacional (permissão contatos:ler ou contatos:escrever) responde sempre 200:

{
  "destinatario": "+5527999999999",
  "finalidade": "transacional",
  "consentido": true,
  "descadastrado": false,
  "registro_id": "…",
  "concedido_em": "2026-11-07T10:00:00Z",
  "expira_em": null
}

O telefone vai em E.164 (+55…, com o + codificado como %2B) e a finalidade precisa ser exatamente a usada no registro. Descadastro prevalece (consentido=false, descadastrado=true). A consulta não cria nada: não registre consentimento só porque ela voltou falso; registre quando houver a autorização da pessoa.

Regras:

• A evidencia descreve como a pessoa autorizou (10 a 2.000 caracteres, sem dados sensíveis). concedido_em no futuro responde 422 DATA_INVALIDA.
• A finalidade é livre (até 120 caracteres), mas precisa ser a mesma no consentimento e na mensagem: um consentimento transacional não vale para marketing.
• Quem pedir para sair: POST /v1/contatos/descadastros com destinatario (e motivo opcional) → 200 {"descadastrado": true}. Vale para todas as finalidades e na hora: novos envios respondem 422 CONSENTIMENTO_AUSENTE e mensagens que estavam na fila são canceladas antes de sair. Novo consentimento para quem saiu responde 409 DESTINATARIO_DESCADASTRADO (exige revisão administrativa).
• Quem responder SAIR, PARAR, CANCELAR, DESCADASTRAR, REMOVER ou STOP no WhatsApp é descadastrado automaticamente (seção 8.1).
• Campanhas exigem consentimento registrado antes (o objeto consentimento não vale com campanha_id).

7. Acompanhar a entrega

GET /v1/mensagens/{mensagem_id} devolve situacao, motivo_fila e datas. GET /v1/mensagens lista as 100 mais recentes da sua chave (sem filtros nesta versão). Ambos exigem messages.read.

{
  "mensagem_id": "…",
  "situacao": "entregue",
  "motivo_fila": null,
  "criado_em": "…",
  "atualizado_em": "…"
}

motivo_fila explica a espera (ou o fim) da mensagem:

Também ajudam: GET /v1/filas (até 100 mensagens da chave em na_fila, agendada ou incerta, com o motivo) e GET /v1/consumo (total de mensagens da chave no mês, por situação).

Para não ficar consultando, use webhooks (seção 9).

8. Conectar o número pelo seu sistema (QR Code)

Para o administrador do cliente ler o QR Code dentro do seu sistema, sem acesso ao painel do gateway. Exige a permissão instancias:conectar (ou instances.connect) e, para acompanhar a situação, messages.read. Chave individual acessa só o próprio número; chave geral, só os números ativos do seu grupo.

1. Descubra o número: GET /v1/credenciais/contexto (instancia_id) ou GET /v1/instancias.
2. POST /v1/instancias/{instancia_id}/conectar (sem corpo, ou {}) → 200 com {"solicitada", "instancia_id", "situacao"}. Se já estiver conectado, ou já houver conexão/QR em andamento, solicitada vem false e nada é reiniciado: não chame conectar a cada atualização da tela.
3. A cada 3 segundos, GET /v1/instancias/{instancia_id}/qr:
4. 200 com qr e expira_em: desenhe o conteúdo de qr como QR Code no seu servidor (ele troca sozinho a cada 20 a 60 segundos);
5. 404 QR_INDISPONIVEL: ainda gerando, já lido ou conectado. Confira a situacao em GET /v1/instancias (ou no diagnóstico): connected significa pareado; feche a tela.
6. Para trocar de número: POST /v1/instancias/{instancia_id}/desconectar e repita. Desconectar só funciona com chave individual (chave geral: 409 CHAVE_SEM_INSTANCIA); limite de 10 por minuto.

A chave e o token ficam no seu servidor; o navegador recebe só a imagem do QR. Não guarde o QR em logs nem em URLs. Instância restrita pelo WhatsApp responde 409 INSTANCIA_RESTRITA e exige análise do gestor. Número de outra chave responde 404 INSTANCIA_INDISPONIVEL. Cada pedido de conexão, desconexão e cada QR exibido ficam na auditoria (sem o conteúdo do QR).

Situações do número (situacao em GET /v1/instancias), com os nomes que a API devolve hoje: created (nunca conectado), qr_pending (aguardando leitura do QR), connecting, connected (único que envia), reconnecting, disconnected, logged_out (sessão encerrada no celular: leia o QR de novo), restricted (restringido pelo WhatsApp), paused e error.

8.1 Receber mensagens (módulo do plano)

Cada número tem um modo de recebimento, escolhido pelo gestor no painel (Instâncias › Editar):

Grupos e o histórico antigo do celular são ignorados (grupos podem ser ligados por número). O módulo é cobrado pelo plano: uma cota de mensagens guardadas por período e, se o plano prever, um valor por mensagem acima da cota; sem esse valor, acima da cota as mensagens deixam de ser guardadas. O consumo aparece em GET /v1/saldo (campo recebimento).

Com a permissão messages.receive:

# Novas desde a última consulta (ordem de chegada; guarde o recebido_em da última):
curl "https://gateway.orquestrasistemas.com.br/v1/mensagens-recebidas?apos=2026-11-07T18:00:00Z" \
  -H "Authorization: Bearer <TOKEN>"

{
  "itens": [
    {
      "mensagem_recebida_id": "…",
      "instancia_id": "…",
      "remetente": "+5527999999999",
      "nome_exibicao": "Maria",
      "tipo": "texto",
      "texto": "Meu carro está pronto?",
      "legenda": null,
      "nome_arquivo": null,
      "voz": false,
      "localizacao": null,
      "contato": null,
      "reacao": null,
      "tem_midia": false,
      "midia_tipo": null,
      "midia_tamanho": null,
      "resposta_a_mensagem_id": "…",
      "recebido_em": "…",
      "expira_em": "…"
    }
  ]
}

• Filtros: apos (data/hora), remetente (telefone em qualquer formato), instancia_id, limite (1 a 100; padrão 50). Sem apos, vêm as mais recentes primeiro.
• tipo: texto, imagem, audio, video, documento, figurinha, localizacao, contato, reacao ou outro; os campos legenda, nome_arquivo, voz, localizacao, contato e reacao vêm conforme o tipo. resposta_a_mensagem_id indica a mensagem nossa que a pessoa respondeu (citou).
• Mídia: GET /v1/mensagens-recebidas/{id}/midia devolve o arquivo (até 16 MB; maiores ficam só com os dados da mensagem). Sem mídia guardada, 404 MIDIA_INDISPONIVEL.
• GET /v1/mensagens-recebidas/{id} traz uma; DELETE /v1/mensagens-recebidas/{id} apaga antes do prazo (pedido do titular, LGPD) e responde 204.
• O número do remetente pode vir null quando o WhatsApp o oculta (contas com identificador privado).

8.2 Responder (atendimento, "responda 1 para confirmar")

Envie a mensagem normalmente com responder_a = mensagem_recebida_id. Ela sai pelo mesmo número que recebeu e chega citando a original:

{ "destinatario": "+5527999999999", "texto": "Está pronto, pode retirar.", "responder_a": "…" }

Quem escreveu nas últimas 24 horas autoriza a resposta: o gateway registra esse consentimento sozinho, com a mensagem recebida como evidência, válido por 24 horas e preso àquela conversa (finalidade resposta:<id>). Ele vale só para atendimento (finalidade transacional ou atendimento), não autoriza outros envios para a pessoa e não vale em campanhas (RESPOSTA_EM_CAMPANHA). Depois disso, ou para quem pediu para sair, valem as regras normais da seção 6. O destinatario precisa ser quem escreveu (422 RESPOSTA_OUTRO_DESTINATARIO). Para um robô de confirmação, leia o texto recebido (por exemplo, 1) e responda com responder_a.

8.3 Enquetes

{
  "destinatario": "+5527999999999",
  "enquete": { "pergunta": "Aprova a reforma da fachada?", "opcoes": ["Sim", "Não", "Abstenção"] }
}

• 2 a 12 opções diferentes (até 100 caracteres cada; pergunta até 255); "multipla": true permite marcar várias.
• Os votos chegam cifrados e o gateway decifra com o segredo gerado no envio; funcionam em qualquer modo de recebimento.
• GET /v1/mensagens/{mensagem_id}/votos (permissão messages.read): pergunta, contagem por opção e o voto mais recente de cada pessoa (opcoes vazio = voto retirado). Mensagem que não é enquete: 422 NAO_E_ENQUETE. Webhook: enquete.voto.

{
  "mensagem_id": "…",
  "pergunta": "Aprova a reforma da fachada?",
  "multipla": false,
  "total_eleitores": 2,
  "opcoes": [
    { "opcao": "Sim", "votos": 1 },
    { "opcao": "Não", "votos": 1 },
    { "opcao": "Abstenção", "votos": 0 }
  ],
  "votos": [{ "eleitor": "+5527999999999", "opcoes": ["Sim"], "votado_em": "…" }]
}

• No painel, a ação Votos aparece nas enquetes da tela Mensagens.

9. Webhooks (avisos automáticos)

Em vez de ficar consultando, cadastre no painel (Webhooks, proprietário ou administrador) uma URL do seu sistema e os eventos desejados. O segredo do webhook (owh_…) aparece uma única vez na criação: guarde-o no servidor.

Exemplo de mensagem.situacao:

{
  "evento_id": "…",
  "evento": "mensagem.situacao",
  "mensagem_id": "…",
  "situacao": "entregue",
  "ocorrido_em": "2026-11-08T15:57:02.114Z"
}

mensagem.situacao é enviado para na_fila (no aceite), em_envio, aceita_provedor, entregue, lida, falhou e incerta. Cancelamentos e expirações não geram webhook nesta versão: consulte GET /v1/mensagens/{mensagem_id} se precisar confirmá-los. Só entram eventos ocorridos depois de o webhook ser criado.

Como o gateway chama a sua URL: POST com Content-Type: application/json e os cabeçalhos

O que o seu sistema deve fazer:

1. Ler o corpo bruto (antes de converter o JSON) e calcular HMAC-SHA256(segredo, timestamp + "." + corpo); comparar com a assinatura em tempo constante. Diferente: responda 401 e ignore.
2. Recusar timestamp com mais de 5 minutos de diferença do seu relógio (proteção contra repetição).
3. Tratar evento_id já processado como duplicado (a entrega é "ao menos uma vez").
4. Responder 2xx rápido (em até 10 segundos) e processar depois, se for demorado.

Retentativas: erro 5xx, 429, tempo esgotado ou falha de conexão são repetidos com espera crescente (10 s, 20 s, 40 s… até 1 hora, com pequena variação), até 8 tentativas no total. Outro 4xx encerra as tentativas daquele evento. Redirecionamentos não são seguidos.

Requisitos da URL: https://, porta 443, com nome de domínio (não IP) que aponte só para endereços públicos; sem usuário/senha nem # na URL.

// Node.js (Express): conferir a assinatura com o corpo bruto.
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const vistos = new Set(); // em produção, guarde no banco
app.post('/webhooks/orquestra', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Orquestra-Timestamp') ?? '';
  const recebida = req.get('X-Orquestra-Assinatura') ?? '';
  const esperada =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.ORQUESTRA_SEGREDO_WEBHOOK)
      .update(`${timestamp}.${req.body.toString('utf8')}`)
      .digest('hex');
  const valida =
    recebida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada));
  if (!valida || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);
  const evento = JSON.parse(req.body.toString('utf8'));
  if (!vistos.has(evento.evento_id)) {
    vistos.add(evento.evento_id);
    // processar: evento.evento, evento.mensagem_id, evento.situacao…
  }
  res.sendStatus(204);
});

<?php
// PHP: conferir a assinatura com o corpo bruto.
$corpo = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ORQUESTRA_TIMESTAMP'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpo, getenv('ORQUESTRA_SEGREDO_WEBHOOK'));
if (!hash_equals($esperada, $_SERVER['HTTP_X_ORQUESTRA_ASSINATURA'] ?? '') || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}
$evento = json_decode($corpo, true);
// ignore $evento['evento_id'] já processado; depois trate $evento['evento']
http_response_code(204);

# Python (Flask): conferir a assinatura com o corpo bruto.
import hashlib, hmac, os, time
from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/orquestra")
def receber():
    corpo = request.get_data()  # bytes, sem converter
    timestamp = request.headers.get("X-Orquestra-Timestamp", "")
    esperada = "sha256=" + hmac.new(
        os.environ["ORQUESTRA_SEGREDO_WEBHOOK"].encode(), timestamp.encode() + b"." + corpo, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(esperada, request.headers.get("X-Orquestra-Assinatura", "")):
        return "", 401
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return "", 401
    evento = request.get_json()
    # ignore evento["evento_id"] já processado; depois trate evento["evento"]
    return "", 204

10. Campanhas

Para avisos a muitas pessoas de uma vez (até 500 destinatários por campanha), com a permissão campaigns.write:

1. Criar: POST /v1/campanhas com nome, finalidade, texto, destinatarios (lista de telefones) e agendar_para opcional → 201 {"campanha_id", "situacao": "rascunho", "instrucao"}.
2. Aprovar: sempre por uma pessoa no painel (proprietário ou administrador). A API não aprova.
3. Iniciar: POST /v1/campanhas/{campanha_id}/iniciar (sem corpo) → 202 {"iniciada": true, "mensagens": 120}. É tudo ou nada: só começa se a campanha estiver aprovada (senão 409 CAMPANHA_BLOQUEADA), se o saldo cobrir todos (402) e se todos tiverem consentimento registrado para a finalidade (senão 422 CONSENTIMENTO_AUSENTE e nada é enfileirado).
4. Acompanhar: GET /v1/campanhas (as 100 mais recentes da chave) e as mensagens em GET /v1/filas.

Atenção: com o conector atual do WhatsApp (não oficial), as mensagens de campanha ficam na fila com motivo_fila = campanha_aguarda_provedor_oficial e expiram em 24 horas: o despacho de campanhas aguarda a integração com o provedor oficial. Para avisos a vários contatos hoje, use o lote (seção 4.1), que segue as regras de consentimento e os limites do número.

Situações da campanha: rascunho, aprovada, agendada, executando, pausada, concluida, cancelada.

11. Limites e espaçamento

Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset mostram quanto resta da janela de 1 minuto. Os limites do seu número aparecem em GET /v1/limites (permissão analytics.read).

Espaçamento: os envios de cada número saem espaçados por igual — o intervalo é 60 segundos divididos pelo limite por minuto. Com o padrão de 5 por minuto, uma mensagem a cada 12 segundos; com 2, a cada 30; com 3, a cada 20. Mensagens que chegam juntas aguardam a vez (motivo_fila = aguardando_intervalo_entre_envios); o 202 continua imediato. Isso protege o número contra bloqueio por envio em rajada. Na chave geral, cada número do grupo tem seu próprio espaçamento, o que aumenta a vazão total.

12. Erros

Os erros vêm com Content-Type: application/problem+json, no formato:

{
  "type": "about:blank",
  "codigo": "CONSENTIMENTO_AUSENTE",
  "title": "Destinatário sem consentimento válido para esta finalidade. Registre-o antes ou envie o objeto \"consentimento\" junto com a mensagem.",
  "status": 422,
  "requisicao_id": "req-1a"
}

Use codigo para tratar o erro no seu sistema e title para mostrar ao usuário. Guarde o requisicao_id: ele identifica a chamada para o suporte.

Quando repetir automaticamente: só em falha de rede, 429, 500 e 503, com espera crescente e a mesma Idempotency-Key. Nunca repita automaticamente 400, 402, 403, 409 ou 422: o resultado será o mesmo até alguém corrigir a causa. Rota inexistente responde 404 sem codigo (formato padrão do servidor).

13. Exemplos completos

Os exemplos leem a chave e o endereço de variáveis de ambiente (ORQUESTRA_CHAVE_API e ORQUESTRA_API_URL), nunca do código. Versões em 8 linguagens: pasta exemplos/ do repositório.

cURL (fluxo completo)

BASE="https://gateway.orquestrasistemas.com.br"
TOKEN=$(curl -s -X POST "$BASE/v1/autenticacao/token" -H "X-API-Key: $ORQUESTRA_CHAVE_API" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token_acesso"])')

curl -s "$BASE/v1/diagnostico" -H "Authorization: Bearer $TOKEN"          # tudo pronto?
curl -s "$BASE/v1/saldo" -H "Authorization: Bearer $TOKEN"                # saldo do plano

curl -s -X POST "$BASE/v1/mensagens" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: pedido-1234-pronto" -H "Content-Type: application/json" \
  -d '{"destinatario":"(27) 99999-9999","texto":"Seu veículo está pronto.","consentimento":{"evidencia":"Cliente aceitou avisos no cadastro."}}'

curl -s "$BASE/v1/mensagens/<MENSAGEM_ID>" -H "Authorization: Bearer $TOKEN"  # situação

PHP

<?php
// Configuração: guarde a chave em variável de ambiente, nunca no código.
const BASE = 'https://gateway.orquestrasistemas.com.br';

function orquestra(string $metodo, string $rota, ?array $corpo = null, ?string $token = null, ?string $idempotencia = null): array
{
    $cabecalhos = [$token ? "Authorization: Bearer $token" : 'X-API-Key: ' . getenv('ORQUESTRA_CHAVE_API')];
    if ($idempotencia) {
        $cabecalhos[] = "Idempotency-Key: $idempotencia";
    }
    $ch = curl_init(BASE . $rota);
    $opcoes = [CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15];
    if ($corpo !== null) {
        // Só manda Content-Type quando há corpo (POST sem corpo com JSON vazio responde 400).
        $cabecalhos[] = 'Content-Type: application/json';
        $opcoes[CURLOPT_POSTFIELDS] = json_encode($corpo, JSON_UNESCAPED_UNICODE);
    }
    $opcoes[CURLOPT_HTTPHEADER] = $cabecalhos;
    curl_setopt_array($ch, $opcoes);
    $resposta = json_decode((string) curl_exec($ch), true) ?? [];
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status >= 400) {
        throw new Exception(($resposta['codigo'] ?? $status) . ': ' . ($resposta['title'] ?? ''));
    }
    return $resposta;
}

$token = orquestra('POST', '/v1/autenticacao/token')['token_acesso'];
$envio = orquestra('POST', '/v1/mensagens', [
    'destinatario' => '(27) 99999-9999',
    'texto' => 'Seu veículo está pronto para retirada.',
    'consentimento' => ['evidencia' => 'Cliente aceitou avisos de serviço no cadastro.'],
], $token, 'pedido-1234-pronto');
echo $envio['mensagem_id'], PHP_EOL;
echo orquestra('GET', '/v1/mensagens/' . $envio['mensagem_id'], null, $token)['situacao'], PHP_EOL;

Python (3.10 ou superior, biblioteca requests)

import os, time
import requests

BASE = "https://gateway.orquestrasistemas.com.br"
_token = {"valor": None, "expira": 0.0}


def obter_token() -> str:
    if _token["valor"] and time.time() < _token["expira"] - 30:
        return _token["valor"]
    r = requests.post(f"{BASE}/v1/autenticacao/token", headers={"X-API-Key": os.environ["ORQUESTRA_CHAVE_API"]}, timeout=15)
    r.raise_for_status()
    dados = r.json()
    _token.update(valor=dados["token_acesso"], expira=time.time() + dados["expira_em_segundos"])
    return dados["token_acesso"]


def enviar_mensagem(destinatario: str, texto: str, idempotencia: str) -> dict:
    r = requests.post(
        f"{BASE}/v1/mensagens",
        headers={"Authorization": f"Bearer {obter_token()}", "Idempotency-Key": idempotencia},
        json={"destinatario": destinatario, "texto": texto},
        timeout=15,
    )
    if r.status_code != 202:
        erro = r.json()
        raise RuntimeError(f"{erro.get('codigo')}: {erro.get('title')}")
    return r.json()  # { mensagem_id, situacao: 'na_fila', consulta, ... }


aceita = enviar_mensagem("(27) 99999-9999", "Seu veículo está pronto.", "pedido-1234-pronto")
situacao = requests.get(f"{BASE}{aceita['consulta']}", headers={"Authorization": f"Bearer {obter_token()}"}, timeout=15)
print(aceita["mensagem_id"], situacao.json()["situacao"])

Node.js (18 ou superior)

const BASE = 'https://gateway.orquestrasistemas.com.br';
let token = null;
let expiraEm = 0;

async function obterToken() {
  if (token && Date.now() < expiraEm - 30_000) return token;
  const r = await fetch(`${BASE}/v1/autenticacao/token`, {
    method: 'POST',
    headers: { 'X-API-Key': process.env.ORQUESTRA_CHAVE_API },
  });
  if (!r.ok) throw new Error(`Token: ${r.status}`);
  const dados = await r.json();
  token = dados.token_acesso;
  expiraEm = Date.now() + dados.expira_em_segundos * 1000;
  return token;
}

export async function enviarMensagem(destinatario, texto, idempotencia) {
  const r = await fetch(`${BASE}/v1/mensagens`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${await obterToken()}`,
      'Idempotency-Key': idempotencia,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ destinatario, texto }),
  });
  const dados = await r.json();
  if (!r.ok) throw new Error(`${dados.codigo}: ${dados.title}`);
  return dados; // { mensagem_id, situacao: 'na_fila', consulta, ... }
}

export async function consultarSituacao(idMensagem) {
  const r = await fetch(`${BASE}/v1/mensagens/${idMensagem}`, {
    headers: { Authorization: `Bearer ${await obterToken()}` },
  });
  return r.json(); // { situacao, motivo_fila, ... }
}

14. Boas práticas

• Uma chave por sistema; se um sistema sair, o gestor revoga só a chave dele. Peça só as permissões que o sistema usa.
• Gere a Idempotency-Key a partir do seu próprio evento (pedido, boleto, aviso) para nunca duplicar mensagens; repita a mesma chave nas novas tentativas.
• Reaproveite o token; renove uns 30 segundos antes de expirar e, se receber 401 TOKEN_INVALIDO, peça outro uma vez e repita.
• Mande só mensagens que a pessoa espera receber, com consentimento registrado e finalidade honesta; muitas denúncias levam o WhatsApp a restringir o número. Respeite o descadastro.
• O 202 não é entrega: acompanhe a situação ou use webhook.
• Limites por minuto, hora e dia valem por número; quando atingidos, a mensagem espera na fila (motivo_fila) em vez de falhar. Não tente "furar" a fila com várias chaves.
• Para muitos avisos, prefira o lote (100 por chamada) a 100 chamadas separadas.
• Acompanhe GET /v1/saldo e avise o responsável antes de chegar a zero.
• Verifique números (/v1/contatos/verificar) só quando fizer sentido, não em massa.
• Webhook: confira a assinatura, recuse timestamps antigos, trate evento_id repetido e responda rápido.
• Nunca grave a chave, o token, o segredo do webhook ou o QR em logs, URLs, no navegador ou no Git.

15. Quem acessa o quê

No painel, cada pessoa da organização tem um papel. O gestor do gateway (administração global) vê todas as organizações, gerencia planos, aprova pagamentos e acompanha a saúde de todos os números.

Na API, quem acessa é o sistema integrado, pela chave. A chave só enxerga a organização dela e, conforme o tipo, o número (individual) ou o grupo (geral) a que está ligada; mensagens, arquivos e campanhas só são vistos pela chave que os criou. Cada rota exige a permissão correspondente (tabela da seção 1). O segredo da chave é exibido uma única vez; o painel guarda só um resumo irreversível e o prefixo. Revogar a chave bloqueia na hora todos os tokens emitidos por ela.

Dados pessoais. Mensagens, mídias e mensagens recebidas ficam cifradas; mensagens recebidas são apagadas no fim do prazo de retenção ou a pedido (DELETE /v1/mensagens-recebidas/{id}). Os registros técnicos não guardam conteúdo das mensagens.

16. Todas as rotas

Base: https://gateway.orquestrasistemas.com.br. Todas, exceto a primeira, usam Authorization: Bearer <token>. Quando há duas permissões, qualquer uma basta.

GET /v1/grupos devolve o grupo da chave geral (id, nome, politica, situacao); para chave individual, lista vazia.