Integrador ISP — webservice

Onde fica: Integrador ISP › Integrações (chaves) · API em /api/webservice/v1/

O Integrador ISP publica uma API externa para que outros sistemas — principalmente o OMNI (atendimento), o ACS (roteadores) e o ASSINA (assinatura) — consultem e atuem no cadastro, no financeiro e nas O.S. do provedor. Ela é versionada (/v1/), autenticada por chave com escopos e pode ser limitada a filiais.

Antes de começar

• Crie uma chave para cada sistema que vai chamar o ISP (uma para o OMNI, outra para o ACS, outra para o ASSINA). Assim cada uma tem só os escopos de que precisa e pode ser trocada sem afetar as outras.
• A chave é criada e consultada na tela de Integrações do ISP. Ver o valor completo exige a permissão pessoal de ver senhas. O responsável pela instalação também pode criar chaves pela linha de comando do servidor.
• Cada chave tem um rótulo (por exemplo, omni), uma lista de escopos e, opcionalmente, uma lista de filiais.

Autenticação

Envie a chave no cabeçalho X-API-Key em toda chamada.

curl -s https://isp.exemplo.com.br/api/webservice/v1/sobre/ \
  -H "X-API-Key: chave-de-exemplo"

Sem a chave, ou com chave inválida ou desativada: 401.

Escopos — o que a chave pode fazer

Escopo	Libera
leitura	Todas as consultas (GET).
desbloqueio	Liberar a internet de um contrato antes de resolver o financeiro (desbloqueio de confiança e liberação operacional).
atendimento	Abrir atendimento e a O.S. de campo que nasce junto.
acs	Consultas que o ACS faz para saber de quem é um aparelho. Traz a senha PPPoE da conexão — por isso é escopo à parte.
assinatura	O fluxo das O.S. de assinatura de contrato (usado pelo ASSINA).
cadastro	Registrar a negociação comercial de uma conversa (usado pela IA comercial).

Chamada sem o escopo exigido: 403 com {"detail": "escopo_insuficiente", "escopo": "..."}.

Filiais — o que a chave enxerga

Por padrão a chave enxerga toda a instalação. Com uma ou mais filiais marcadas, toda consulta fica limitada a elas. Um cliente só aparece se tiver ao menos um contrato numa das filiais da chave. O que está fora do alcance responde 404, igual a um registro que não existe.

Regras gerais

• Dinheiro sempre em texto decimal ("119.90"); datas AAAA-MM-DD; data e hora em ISO-8601 com fuso.
• Escritas exigem Idempotency-Key: repetir a chamada com a mesma chave devolve a mesma resposta (inclusive uma recusa). Reusar a chave em outra rota responde 422.
• Limite de chamadas por chave: 600 por minuto para leitura e 30 por minuto para escrita (429 acima).
• Identificadores: o {id} das rotas é o identificador público do registro (o mesmo que aparece nas respostas), não o número interno do banco.
• Listas vêm como objetos simples ({"resultados": [...]}), sem paginação própria — exceto as rotas que informam pagina e tamanho.

Recursos

Descobrir a chave

Método e rota	Escopo	Para quê
GET /sobre/	qualquer	Mostra o sistema, a versão, o rótulo, os escopos e as filiais da chave. É o "teste de conexão".

Clientes, contratos e faturas

Método e rota	Escopo	Para quê e campos essenciais
GET /clientes/	leitura	Busca cliente. Exige ao menos um filtro: documento, telefone, email ou nome (3+ letras); limite (padrão 10, máximo 20). Devolve id, nome, documento, telefones, emails, cidade, uf, ativo, contratos.
GET /clientes/{id}/	leitura	Detalhe do cliente, com endereço.
GET /clientes/{id}/contratos/	leitura	Contratos com situação financeira e de conexão, plano, velocidade, valor, login e serial da ONU.
GET /clientes/{id}/faturas/	leitura	Faturas. situacao: abertas (padrão), vencidas, pagas ou todas. Traz o total vencido e a data de vencimento mais antiga.
POST /clientes/status-lote/	leitura	Contratos e faturas em aberto de vários clientes de uma vez. Corpo {"clientes_ids": [...]}, até 200. Os não encontrados voltam em nao_encontrados.
GET /clientes/candidatos/	leitura	Descobre quem bate num critério (situação do contrato, financeiro, dias de atraso), com o telefone do cadastro. Exige ao menos um critério. Paginado (pagina, tamanho até 200). Usado em campanhas.
GET /faturas/{id}/pagamento/	leitura	Linha digitável e PIX da fatura, emitidos na hora.
GET /faturas/{id}/link-cartao/	leitura	Link de pagamento por cartão. Se a fatura não aceita mais pagamento, vem disponivel: false, sem link.
GET /faturas/{id}/boleto.pdf	leitura	PDF do boleto.
GET /clientes/{id}/notas-fiscais/	leitura	Notas do cliente. Filtros desde, ate (AAAA-MM-DD) e limite (padrão 12, máximo 50).
GET /notas-fiscais/{uuid}/pdf/	leitura	PDF da nota (202 enquanto o emissor ainda gera).
GET /contratos/{id}/conexao/	leitura	Situação da conexão: online ou não, último visto, IP e sinal da ONU. Aceita ?login= para uma conexão específica.
GET /contratos/{id}/liberacao/	leitura	Diz se o contrato pode receber liberação (de confiança ou operacional) e, se não, por quê.

Liberar a internet (escopo desbloqueio)

Método e rota	Para quê
POST /contratos/{id}/desbloqueio-confianca/	Libera temporariamente um contrato bloqueado por atraso. Corpo opcional {"motivo": "..."}. Sucesso: 201 com liberado_ate. Recusa por regra: 409 com motivo: "recusado".
POST /contratos/{id}/liberacao-operacional/	Liberação antes de o técnico concluir, ou quando o bloqueio é do operador. Se o contrato não está bloqueado nem reduzido: 409 com motivo: "nao_esta_bloqueado".

Ambos exigem Idempotency-Key e respeitam a mesma regra de limite de usos do balcão.

Atendimento e O.S.

Método e rota	Escopo	Para quê
GET /atendimentos/catalogo/	leitura	Os seletores do formulário de abrir atendimento: assuntos (com modelos de O.S.), processos, setores, colaboradores e técnicos.
POST /atendimentos/	atendimento	Abre o atendimento. Campos principais: cliente_id, assunto_id (obrigatórios), contrato_id, descricao, omni_ref (a conversa de origem), abrir_os e, se quiser, template_os_id, setor_id, tecnico_id, agendada_para. Se já existe atendimento aberto da mesma conversa: 409 atendimento_ja_aberto.
POST /atendimentos/{id}/ordens-servico/	atendimento	Abre uma O.S. a partir de um atendimento (template_os_id, setor_id, tecnico_id, agendada_para).
GET /atendimentos/{id}/	leitura	Detalhe do atendimento com as O.S.
GET /clientes/{id}/atendimentos/	leitura	Atendimentos do cliente (status, omni_ref, limite).
GET /clientes/{id}/ordens-servico/	leitura	O.S. do cliente (status com várias opções separadas por vírgula).
GET /ordens-servico/{id}/	leitura	Detalhe de uma O.S.
GET /tecnicos/{id}/os-do-dia/	leitura	A agenda de hoje do técnico.
GET /clientes/{id}/regiao-manutencao/	leitura	Diz se o cliente está numa área em manutenção.
GET /regioes-manutencao/ativas/	leitura	Todas as regiões em atuação agora, com os clientes afetados.

Comercial

Método e rota	Escopo	Para quê
GET /planos/	leitura	Planos que a IA pode oferecer (só os marcados para isso, dentro da vigência e visíveis para as filiais da chave).
GET /planos/{id}/imagem/	leitura	Imagem do plano.
GET /viabilidade/?lat=&lng=	leitura	Viabilidade técnica no endereço, pela planta de rede.
POST /negociacoes/	cadastro	A IA registra (cria ou atualiza) a negociação de uma conversa; o atendente humano abre no assistente e conclui. Exige omni_ref e Idempotency-Key.

Para o ACS (escopo acs)

Método e rota	Para quê
GET /acs/identificar/	De quem é este aparelho? Parâmetros login, serial, serial_gpon, ip, mac. Devolve a conexão do cliente.
GET /acs/pppoe/	Credenciais PPPoE que o ACS grava no roteador (login, serial, serial_gpon). Inclui a senha PPPoE.
GET /acs/serial/	Resolve por serial da ONU.

Para o ASSINA (escopo assinatura)

Método e rota	Para quê
GET /assinaturas/ordens-servico/	Lista as O.S. de assinatura de contrato abertas (limite até 500; ou ids=1,2,3 para conferir O.S. em qualquer status).
POST /ordens-servico/{id}/assinatura/preparar/	Abre (ou reaproveita) a solicitação e devolve o contrato preenchido (PDF em base64) e os signatários.
POST /ordens-servico/{id}/assinatura/regerar/	Devolve o contrato atualizado de uma O.S. que já tem documento no ASSINA.
POST /assinaturas/{id}/vincular/	O ASSINA avisa que criou o documento: {documento_id, links: [...]}.
POST /assinaturas/{id}/concluir/	O cliente assinou: {documento_id, hash, assinado_em}. Fecha o ciclo e conclui a O.S.

Também estão no escopo leitura: GET /contratos/{id}/assinatura/, GET /contratos/{id}/assinatura/pendente/ e GET /contratos/{id}/assinatura.pdf. O link de assinatura nunca expõe o token do signatário.

Rotas mais antigas (sem versão)

Continuam disponíveis, com a mesma chave e sem exigir escopo:

• GET /api/webservice/rede/onu-sinal/{serial}/ — sinal da ONU pelo serial.
• GET /api/webservice/regiao-manutencao/{cliente_id}/ — se o cliente está em área de manutenção.

Exemplos

Buscar um cliente pelo documento

curl -s "https://isp.exemplo.com.br/api/webservice/v1/clientes/?documento=11122233344" \
  -H "X-API-Key: chave-de-exemplo"

{"resultados": [{"id": 3749, "nome": "Cliente Teste", "documento": "11122233344",
  "tipo": "PF", "telefones": ["45999998888"], "emails": ["a@b.com"],
  "cidade": "Cidade Exemplo", "uf": "PR", "ativo": true,
  "contratos": [{"id": 812, "status": "ativo"}]}]}

Pedir um desbloqueio de confiança

curl -s -X POST https://isp.exemplo.com.br/api/webservice/v1/contratos/812/desbloqueio-confianca/ \
  -H "X-API-Key: chave-de-exemplo" \
  -H "Idempotency-Key: pedido-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{"motivo": "Cliente pediu pelo atendimento"}'

{"ok": true, "tipo": "confianca", "liberado_ate": "2026-09-15T23:59:59-03:00"}

Abrir um atendimento

curl -s -X POST https://isp.exemplo.com.br/api/webservice/v1/atendimentos/ \
  -H "X-API-Key: chave-de-exemplo" \
  -H "Idempotency-Key: conversa-123-abertura" \
  -H "Content-Type: application/json" \
  -d '{"cliente_id": 3749, "contrato_id": 812, "assunto_id": 12,
       "descricao": "Cliente relata lentidão", "omni_ref": "conversa-123"}'

Webhooks que o ISP recebe

O ISP expõe três endereços fixos e públicos para os "avisos de volta". Em todos, a credencial é a assinatura HMAC do corpo.

Endereço	Quem chama	Cabeçalho	O que avisa
POST /api/webhooks/omni/{segredo}	OMNI	X-Integrador-Omni-Signature	Estado das mensagens enviadas pelo OMNI: enviada, entregue, lida ou falhou. O segredo no caminho identifica a instalação.
POST /api/webhooks/assina	ASSINA	X-Assina-Signature	O cliente assinou o documento. Sem segredo configurado, o ISP recusa tudo com 401.
POST /api/webhooks/acs	ACS	X-Acs-Signature	Lote de eventos de aparelho: vínculo, PPPoE aplicado, Wi-Fi, reinício, firmware, falha de tarefa. Corpo {"eventos": [...]} (até 500). Lista vazia é só um teste de conexão.

Quem recebe responde 200 mesmo para eventos que não conhece, para não gerar reenvio infinito. Os registros alimentam a trilha do contrato.

Erros comuns

Código	Quando
400	Parâmetro faltando ou inválido; Idempotency-Key ausente numa escrita.
401	Sem chave, chave inválida ou desativada.
403	A chave não tem o escopo (escopo_insuficiente).
404	Não existe ou está fora do alcance da chave.
409	Recusa de regra de negócio, com motivo (por exemplo, recusado, atendimento_ja_aberto, nao_esta_bloqueado).
422	Idempotency-Key reutilizada em outra rota.

Leia também

• Integrações — visão geral
• Integrador OMNI
• Integrador ACS
• Integrador ASSINA