Integrador OMNI — API para ERPs e sistemas

Onde fica: Integrador OMNI › Loja de Plugins (integrações) e a tela de chaves de API do administrador · API em /api/webservice/

O OMNI oferece três coisas a outros sistemas: uma API de envio de mensagens (WhatsApp oficial) com webhooks assinados, as integrações com ERPs (Integrador ISP, IXC, SGP e HubSoft) e o Canal Integrador, por onde os sistemas da casa abrem chamados de suporte.

Antes de começar

• A API de envio exige que a empresa tenha ao menos uma instância de WhatsApp API Oficial conectada.
• As chaves são de uma conta de serviço (um usuário que não entra pelo painel, só chama a API). Quem cria é o administrador da empresa.

Autenticação

Chave da API externa (io_live_…)

Envie no cabeçalho X-API-Key. A chave é criada pelo administrador: primeiro uma conta de serviço, depois a chave dela, com os escopos desejados. A chave completa só aparece uma vez, na criação.

Escopo	Libera
messages.send	Enviar mensagens e abrir atendimento com modelo.
messages.read	Consultar o estado de uma mensagem enviada.
tecnico	Apoio do técnico (já vem ligado com o Integrador ISP).

Os escopos de uma chave existente podem ser trocados sem trocar o token. Cada chave tem um limite de chamadas por minuto (120 por padrão); o excesso responde 429.

Chave pessoal (nxa_…)

A tela do usuário gera chaves pessoais, enviadas em Authorization: Bearer. São as usadas pelos sistemas da casa que chamam o OMNI (por exemplo, no Canal Integrador).

Recursos — mensagens (prefixo /api/webservice)

O envio é assíncrono: a chamada enfileira a mensagem e responde 202; o resultado chega por webhook ou por consulta.

Método e rota	Escopo	Para quê
POST /messages/text	messages.send	Mensagem de texto. Campos: destino (telefone), texto (até 4.096 caracteres), integration_row_id (opcional), webhook_callback_url, send_after.
POST /messages/template	messages.send	Mensagem com modelo aprovado. Campos: destino, template_id, variaveis.
POST /messages/media	messages.send	Imagem, vídeo, áudio ou documento. Campos: destino, media_type (image, video, audio, document), url, caption, filename.
GET /messages/{outbox_id}	messages.read	Estado da mensagem: status, tentativas, último erro e os horários de envio, entrega, leitura e falha.
GET /templates	qualquer chave	Modelos aprovados disponíveis (id, nome, idioma, categoria, body_texto, variáveis).
GET /instances	qualquer chave	Instâncias de WhatsApp da empresa (id, nome, phone_number_id). Serve para montar um seletor por nome.
POST /atendimentos/abrir-com-modelo	messages.send	Abre atendimento e envia o modelo de abertura para até 50 leads (usado pelo Kanban comercial do ISP).
GET /tripulantes	qualquer chave	O boneco do OMNI GAME por login (logins, até 100 separados por vírgula).
GET /health	qualquer chave	Quem é esta chave: empresa, escopos. Serve de teste de conexão.

Sem integration_row_id, o OMNI usa a primeira instância ativa e conectada. Se não houver nenhuma, responde 400 (no_active_integration).

Idempotência: envie o cabeçalho Idempotency-Key (opcional) para que um reenvio em até 24 horas devolva a resposta original em vez de mandar de novo.

Abrir atendimento com modelo

Corpo: modelo (nome do modelo aprovado), atendente (email ou login do usuário do OMNI) e itens (telefone, nome, ref). A resposta traz um resultado por item: aberto, em_andamento (já havia atendimento — nada é enviado), telefone_invalido, modelo_invalido ou erro. Um item com erro não derruba os outros.

Webhooks de saída

Registre um endereço para receber o andamento das mensagens:

Método e rota	Para quê
POST /webhooks/subscriptions	Cria a assinatura. Corpo: url e eventos (padrão: os quatro abaixo). Devolve o segredo uma única vez.
GET /webhooks/subscriptions	Lista as assinaturas da chave, com o último estado de entrega.
DELETE /webhooks/subscriptions/{id}	Remove.

Eventos: message.sent, message.delivered, message.read, message.failed.

Corpo recebido (JSON):

{"evento": "message.delivered", "outbox_id": 101, "destino": "5545999990000",
 "external_message_id": "wamid.EXEMPLO", "error": null, "ts": "2026-10-20T14:00:00"}

Cabeçalhos: X-Integrador-Omni-Signature: sha256=<hex> (HMAC-SHA256 do corpo com o segredo), X-Integrador-Omni-Event e User-Agent: IntegradorOmni-Webhook/1.0. Veja como conferir em Webhooks com HMAC. Responda 2xx para confirmar; qualquer outra resposta gera nova tentativa.

Administração das chaves (sessão de administrador)

Estas rotas servem ao painel e usam a sessão do administrador (não a chave de API):

Método e rota	Para quê
GET /api/external-admin/service-accounts	Lista as contas de serviço.
POST /api/external-admin/service-accounts	Cria uma conta de serviço (nome).
GET /api/external-admin/api-keys	Lista as chaves (sem o valor).
POST /api/external-admin/api-keys	Cria a chave: service_account_id, nome, scopes.
GET /api/external-admin/escopos	Escopos conhecidos, com o rótulo em português.
PATCH /api/external-admin/api-keys/{id}	Troca os escopos sem trocar o token.
DELETE /api/external-admin/api-keys/{id}	Revoga a chave.
GET /api/external-admin/audit-log	Histórico das chamadas feitas com as chaves.

Integrações com ERPs

O OMNI lê o ERP do provedor durante o atendimento (e nas campanhas). Cada ERP é configurado na Loja de Plugins, com a credencial cifrada.

ERP	Como o OMNI autentica	O que faz
Integrador ISP	X-API-Key na API /api/webservice/v1/ do ISP (veja Integrador ISP).	Leitura completa, desbloqueio de confiança, abertura de atendimento e O.S.
IXC	Token de API do IXC (autenticação Basic).	Cliente, contratos, boletos, notas, O.S.
SGP	Aplicativo e token no corpo da requisição (família de rotas de URA do SGP).	Somente leitura: cadastro, contratos, conexão e faturas.
HubSoft	OAuth2 com usuário e senha da API.	Somente leitura: cadastro, faturas, contratos e conexão.

Quando a empresa tem mais de um ERP, o OMNI usa o vínculo do contato (ou o ERP preferencial da empresa) para decidir quem responde. Rotas do painel que cuidam disso: GET /api/integracoes/isp/status, GET /api/integracoes/isp/testar (testa a chave e mostra as permissões) e GET /api/contacts/{id}/erp-vinculos.

As consultas do painel ao ERP passam por um serviço único, GET/POST /api/erp/v1/… (contexto do cliente, status do contrato, boletos, notas, logins, região em manutenção, identificar cliente, enviar boleto, desbloqueio de confiança, diagnóstico). Essas rotas usam a sessão do usuário do OMNI e a permissão dele — não são uma API para sistemas externos.

Integrações com ACS, ASSINA e Canal ISP (configuração)

Estas rotas do painel gravam a ligação com os outros produtos. Exigem sessão de administrador.

Rota	Para quê
GET/PUT /api/integracoes/acs	Endereço do ACS e a chave dedicada (omni_…) gerada na Loja de Plugins do ACS. Só a origem do endereço (https://acs.exemplo.com.br) é guardada.
GET /api/integracoes/acs/status	A integração está pronta?
POST /api/integracoes/acs/testar	Testa a conexão.
GET/POST /api/integracoes/assina/config, POST …/assina/testar	Endereço e chave do ASSINA. A chave nunca volta em claro.
PUT/GET /api/integracoes/canal-isp	Configuração do Canal ISP (apoio ao técnico em campo).

O SQUAD é ligado pelo par de chaves descrito em Integrador SQUAD.

Canal Integrador

O Canal Integrador permite que os sistemas da casa (ISP, ACS, PONTO, ASSINA, DNS e outros) abram um chamado de suporte que cai numa fila do OMNI de quem atende. Não guarda senha de ninguém.

Autenticação: Authorization: Bearer nxa_… (chave pessoal do administrador da empresa que atende). Só funciona se a empresa estiver autorizada a atender pelo canal e o canal estiver ligado.

Método e rota	Para quê
GET /api/canal-integrador/ping	Teste de conexão: confirma chave, autorização e o endereço público do canal. Não grava nada.
POST /api/canal-integrador/chamado	Abre (ou atualiza) o chamado. Devolve url com um passe de uso único e expira_em.
POST /api/canal-integrador/entrar/passe	A pessoa entra com o passe.
POST /api/canal-integrador/entrar/pedir-codigo e …/entrar/conferir	Entrada por código enviado ao e-mail (quando o sistema de origem está fora do ar).
GET /api/canal-integrador/eu, GET …/conversa, POST …/conversa/mensagens, GET …/meus-atendimentos	O que a pessoa vê depois de entrar.

Campos do chamado: email e sistema (obrigatórios), nome, empresa_cliente, nivel (o nível de quem pede, que limita o que o atendente pode informar), sistema_id_pessoa, versao, tela_origem, endereco, ip_publico, assunto.

Exemplos

Enviar um texto e acompanhar

curl -s -X POST https://omni.exemplo.com.br/api/webservice/messages/text \
  -H "X-API-Key: io_live_exemplo_0000000000" \
  -H "Idempotency-Key: aviso-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{"destino": "5545999990000", "texto": "Olá! Sua fatura vence amanhã."}'

{"ok": true, "outbox_id": 101, "status": "pending", "idempotent_replay": false}

curl -s https://omni.exemplo.com.br/api/webservice/messages/101 \
  -H "X-API-Key: io_live_exemplo_0000000000"

Registrar um webhook

curl -s -X POST https://omni.exemplo.com.br/api/webservice/webhooks/subscriptions \
  -H "X-API-Key: io_live_exemplo_0000000000" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://sistema.exemplo.com.br/hooks/omni"}'

Abrir um chamado no Canal Integrador

curl -s -X POST https://omni.exemplo.com.br/api/canal-integrador/chamado \
  -H "Authorization: Bearer nxa_exemplo0000" \
  -H "Content-Type: application/json" \
  -d '{"email": "pessoa@exemplo.com.br", "nome": "Pessoa Exemplo",
       "empresa_cliente": "Provedor Exemplo", "sistema": "Integrador ISP",
       "nivel": "Atendente", "assunto": "Dúvida na tela de faturas"}'

Erros comuns

Código	Quando
400	destino ausente, ou nenhuma instância ativa (no_active_integration).
401	Chave ausente, em formato inválido, desconhecida ou revogada.
403	A chave é de usuário web, não de conta de serviço; ou não tem o escopo (insufficient_scope).
409	A mesma Idempotency-Key ainda está sendo processada.
422	Erro de validação do envio (por exemplo, modelo inexistente).
429	Limite de chamadas por minuto excedido.

Leia também

• Integrações — visão geral
• Integrador ISP
• Integrador SQUAD