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. São — endpoints cobrindo cadastro, contratos, autenticações, títulos, promessa de pagamento, ocorrências, assinatura digital, estoque, ONU/ONT, FTTH, notas fiscais e SVA.
https://sua-empresa.webnett.top/api/v1
Header Authorization: Bearer <token>
120 requisições por minuto por token (padrão) — configurável, inclusive sem limite
Início rápido
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.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.
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
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:
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.
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
429e5xxcom nova tentativa e espera crescente.