API do Sistema WebNett

Conecte apps externos, SVAs, sites e automações aos dados da sua empresa. Toda chamada usa HTTPS, JSON e um token de app criado por você no painel.

URL base

https://sua-empresa.webnett.top/api/v1

Autenticação

Header Authorization: Bearer <token>

Limite

120 requisições por minuto por token (padrão) — configurável, inclusive sem limite

Início rápido

Sua URL base é o subdomínio da sua empresa: https://sua-empresa.webnett.top/api/v1. Nos exemplos desta página, troque SUA-EMPRESA pelo subdomínio da empresa. O endereço exato aparece em Integrações › API do Sistema.

Crie um app. No painel, abra Integrações › API do Sistema e clique em + Novo app. O app identifica quem está conectando (ex.: “Meu SVA”, “Site”, “Automação n8n”). Todo token pertence a um app.

Gere um token. Dentro do app, clique em + Novo token, escolha as permissões e a validade. Você pode criar quantos tokens quiser, um para cada ambiente ou integração.

Copie na hora. O token só é mostrado uma vez. O sistema guarda apenas uma impressão digital (hash) dele: se perder, gere outro.

Faça a primeira chamada.

Autenticação

Envie o token em todas as requisições, em um destes headers:

Authorization: Bearer wn_1a2b3c4d5e6f...
# ou
X-API-Key: wn_1a2b3c4d5e6f...

Cada token enxerga somente os dados da própria empresa e só executa o que as permissões escolhidas na criação permitirem.

Permissão	Libera
`clients:read`	Listar e consultar clientes
`clients:write`	Criar e editar clientes
`contracts:read`	Listar e consultar contratos
`contracts:write`	Suspender e reativar contratos
`invoices:read`	Listar e consultar títulos (faturas)
`invoices:write`	Criar, dar baixa e cancelar títulos
`plans:read`	Listar planos
`sva:validate`	Validar login e senha de assinantes de SVA

Segurança. Use o token apenas em servidor (backend, automação). Nunca coloque em app de celular, site ou qualquer código que o cliente final consiga ver. Dê a cada integração só as permissões de que ela precisa e revogue tokens que não usa mais.

Convenções

Formato das respostas

Toda resposta é JSON, com o campo ok indicando sucesso ou falha.

// sucesso
{ "ok": true, "data": { ... }, "meta": { ... } }

// erro
{ "ok": false, "error": { "code": "not_found", "message": "Cliente não encontrado." } }

Paginação

Listagens aceitam page (padrão 1) e limit (padrão 50, máximo 200) e devolvem em meta: page, limit, total e pages.

Identificadores

IDs podem vir como número (3) ou texto ("001", "INV-535856"). Trate sempre como texto e compare como texto.

Datas e valores

Datas de vencimento usam AAAA-MM-DD. Datas com hora (createdAt, paidAt) estão em UTC, formato ISO 8601. Valores em reais, com ponto decimal (59.90). document, phone e zip são gravados só com números.

Limite de requisições

Cada token tem o seu limite por minuto, escolhido na criação em Integrações › API do Sistema: 120 (padrão), 600, 3.000 ou sem limite. Ao passar do limite a API responde 429 com o header Retry-After (segundos até poder tentar de novo). O limite do seu token aparece em GET /me (rateLimitPerMinute; null quando é sem limite). Em 429 e 5xx, tente novamente com espera crescente.

Erros

HTTP	`error.code`	Quando acontece
400	`missing_parameter` · `invalid_parameter`	Campo obrigatório ausente ou com valor inválido.
401	`unauthorized` · `token_expired`	Token ausente, inválido, revogado ou expirado.
403	`forbidden`	O token não tem a permissão exigida pelo endpoint.
403	`company_blocked`	Empresa bloqueada por pendência de mensalidade.
404	`not_found` · `client_not_found` · `contract_not_found`	Registro inexistente (ou de outra empresa).
409	`duplicate_document`	Já existe cliente com esse CPF/CNPJ.
409	`invoice_paid` · `invoice_canceled`	Título já pago não cancela; título cancelado não recebe baixa.
409	`contract_protected` · `contract_canceled` · `invalid_state`	Contrato marcado “Não suspende”/isento, cancelado, ou fora do estado esperado.
422	`router_not_configured`	Contrato sem dados de MikroTik para aplicar a mudança.
429	`rate_limited`	Passou do limite de requisições por minuto do token. Veja `Retry-After`.
502	`router_error`	O MikroTik não aceitou a mudança de status. O contrato não é alterado.

Guia: integrando um SVA

Um SVA (serviço de valor adicionado) normalmente precisa saber se o assinante pode entrar. Há dois caminhos, que você pode combinar:

1. Login e senha do SVA

Quando o assinante digita usuário e senha no seu SVA, chame POST /sva/validate. A resposta diz se o login é válido e ativo. Nunca revela se um usuário existe.

2. Situação financeira

Busque o cliente por CPF em GET /clients?document=…, veja os contratos e os títulos em aberto, e decida o acesso conforme sua regra.

Boas práticas

Crie um app por integração e um token por ambiente (produção, homologação).
Use a permissão mínima: um SVA que só valida login precisa apenas de sva:validate.
Guarde o token em variável de ambiente ou cofre de segredos, nunca no código.
Ao dar baixa em um título, o WebNett já reativa sozinho os contratos suspensos do cliente que ficaram sem pendência (veja meta.reactivatedContracts).
Trate 429 e 5xx com nova tentativa e espera crescente.

Histórico

v1 — Lançamento: apps e tokens, clientes, contratos (consulta, suspensão e reativação), títulos (consulta, criação, baixa e cancelamento), planos e validação de SVA.