Aparência
Integrações (API)
Os produtos Integrador conversam entre si — e com o ERP que o provedor já usa — por APIs HTTP autenticadas. Esta seção descreve, produto por produto, o que cada API oferece: como se autenticar, quais recursos existem e um exemplo de chamada. É a referência para quem integra um sistema próprio ou confere o que está ligado entre os produtos.
Para quem é
Para o técnico de TI do provedor e para o desenvolvedor que integra. O operador do dia a dia não precisa disto: as integrações entre os produtos são ligadas nas telas de Integrações e na Loja de Plugins de cada sistema, sem escrever código.
O padrão "ilha"
Cada produto Integrador é uma ilha: tem o seu banco de dados, o seu painel e as suas regras. Uma ilha nunca lê o banco da outra — ela só conversa por API HTTP autenticada. Na prática:
- Cada produto publica as rotas que quer que os outros usem (o "webservice") e exige uma chave em toda chamada.
- Quem chama recebe só o que a chave permite — por escopo (o que pode fazer) e, no ISP, por filial (o que enxerga).
- Quando algo acontece do outro lado (mensagem entregue, contrato assinado, roteador configurado), a ilha avisa de volta por webhook assinado.
Quem conversa com quem
| De → Para | Para quê |
|---|---|
| OMNI → ISP | Consultar cliente, contrato, fatura, nota e O.S. durante o atendimento; pedir desbloqueio de confiança; abrir atendimento e O.S. |
| ISP → OMNI | Enviar mensagens e avisos de cobrança pelo WhatsApp; abrir atendimento com modelo para leads do Kanban comercial. |
| OMNI → IXC, SGP, HubSoft | Ler o cadastro, o contrato e as faturas do cliente no ERP de terceiros (somente leitura nos dois últimos). |
| ACS → ISP | Descobrir de quem é um roteador (login PPPoE, serial da ONU). |
| ISP → ACS | Aplicar PPPoE, Wi-Fi, reinício e padrão da empresa nos roteadores dos clientes; manter o espelho de conexões. |
| OMNI → ACS | Trocar senha e nome do Wi-Fi, reiniciar roteador, consultar equipamento. |
| ASSINA → ISP | Buscar as O.S. de assinatura de contrato e devolver o link e a conclusão. |
| ISP → ASSINA | Mandar o documento para assinatura e consultar o resultado. |
| SQUAD ⇄ OMNI | O OMNI entrega a conversa; o SQUAD decide e devolve a resposta pronta (IA). |
| Sistemas da casa → OMNI (Canal Integrador) | Abrir chamado de suporte entre produtos. |
Chaves por escopo
Toda chamada leva uma chave de API. A chave nasce na tela de integração do produto que recebe a chamada.
| Produto | Cabeçalho | Formato | Escopos |
|---|---|---|---|
| Integrador ISP | X-API-Key | token gerado na tela de integrações | leitura, desbloqueio, atendimento, acs, assinatura, cadastro — e recorte por filial |
| Integrador OMNI | X-API-Key | io_live_… | messages.send, messages.read, tecnico |
| Integrador ACS | Authorization: Bearer | isp_… (ISP) ou omni_… (OMNI) | leitura, wifi, reboot, pppoe, cadastro, reset |
| Integrador ASSINA | X-API-Key | chave da empresa ou chave por integração | — (a chave identifica a empresa) |
| Integrador SQUAD | Authorization: Bearer | token "T1" por empresa | — |
| Integrador PONTO | Authorization: Bearer | sessão do RH ou do terminal | — |
Atenção
- Trate a chave como senha: não a coloque em código público nem em mensagens. Se vazar, gere outra — a anterior deixa de valer.
- Dê à chave só os escopos de que o sistema precisa. Uma integração de consulta não precisa de escopo de escrita.
- Um recurso fora do alcance da chave responde como se não existisse (o ISP devolve 404 em ambos os casos), para a chave nunca descobrir o que há fora dela.
Webhooks com HMAC
Os avisos de volta chegam como POST com o corpo em JSON e uma assinatura HMAC-SHA256 do corpo, calculada com um segredo combinado entre as duas pontas. Quem recebe deve conferir a assinatura antes de confiar no conteúdo.
| Quem envia | Cabeçalho da assinatura | Evento principal |
|---|---|---|
| OMNI | X-Integrador-Omni-Signature: sha256=<hex> (e X-Integrador-Omni-Event) | message.sent, message.delivered, message.read, message.failed |
| ASSINA | X-Assina-Signature: sha256=<hex> | documento.concluido |
| ACS | X-Acs-Signature: sha256=<hex> | lote de eventos de aparelho ({"eventos": [...]}) |
Como conferir (em qualquer linguagem): calcule o HMAC-SHA256 dos bytes exatos do corpo recebido, com o segredo, em hexadecimal, e compare com o valor do cabeçalho em tempo constante. Não reserialize o JSON antes de calcular: a assinatura vale para os bytes originais.
bash
# conferindo uma assinatura de teste (valores fictícios)
printf '%s' '{"evento":"message.delivered","outbox_id":101}' \
| openssl dgst -sha256 -hmac 'segredo-de-exemplo'Convenções comuns
- JSON em tudo, com datas em ISO-8601 e dinheiro como texto decimal (
"119.90"), nunca número com ponto flutuante. - Idempotência: toda escrita importante aceita (ou exige) o cabeçalho
Idempotency-Key. Repetir a chamada com a mesma chave devolve a mesma resposta, sem fazer a ação de novo — use quando precisar reenviar após uma falha de rede. - Limite de chamadas por chave: o excesso responde
429. Respeite o tempo de espera. - Erros:
400entrada inválida;401sem chave ou chave inválida;403chave sem o escopo;404não existe (ou fora do alcance);409recusa de regra de negócio, com ummotivo;422corpo inválido.
Um exemplo para começar
Descobrir o que uma chave do ISP alcança:
bash
curl -s https://isp.exemplo.com.br/api/webservice/v1/sobre/ \
-H "X-API-Key: chave-de-exemplo"Páginas desta seção
- Integrador ISP — o webservice
/api/webservice/v1/. - Integrador OMNI — envio de mensagens, webhooks, ERPs e Canal Integrador.
- Integrador ACS — comandos aos roteadores.
- Integrador ASSINA — documentos para assinatura.
- Integrador PONTO — terminal de ponto e exportações.
- Integrador SQUAD — a IA que decide o atendimento.