Respostas, paginação e erros — API WebSystem Provider

Formato das respostas

Toda resposta de sucesso tem "sucesso": true e os dados em dados:

{
  "sucesso": true,
  "dados": { "id": 5, "nome": "João Silva" }
}

Convenções:

Datas sem hora no formato AAAA-MM-DD; data e hora em ISO 8601, em UTC (2026-10-13T15:04:05.000Z).
Valores em reais como número decimal com 2 casas (99.9 = R$ 99,90).
Situações e tipos em minúsculas e sem acento (ativo, bloqueado, vencida).
Campo sem informação vem como null, nunca é omitido.
Campos novos podem aparecer com o tempo: ignore os que o seu sistema não conhece.

Listas aceitam pagina (começa em 1) e por_pagina (padrão 20, máximo 100), e devolvem o bloco paginacao:

{
  "sucesso": true,
  "dados": [ ... ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 134, "total_paginas": 7 }
}

Para ler tudo, avance pagina até chegar a total_paginas.

Em caso de erro, a resposta tem "sucesso": false e um código estável, que o seu sistema pode tratar:

{
  "sucesso": false,
  "erro": { "codigo": "permissao_insuficiente", "mensagem": "Esta chave não tem a permissão \"financeiro:leitura\"." }
}

A mensagem é em português e pode ser mostrada ao usuário final. Para decidir o que fazer, use o codigo.

HTTP	Código	Quando acontece
400	`parametro_invalido`	Parâmetro ou corpo fora do formato esperado. A mensagem diz qual campo.
400	`cpf_cnpj_invalido` · `telefone_invalido` · `id_invalido`	Valor de busca inválido.
401	`chave_ausente` · `chave_invalida`	Chave não enviada ou inexistente.
401	`chave_revogada` · `chave_expirada`	A chave foi revogada pelo provedor ou passou da validade.
403	`ip_nao_autorizado`	A chamada veio de um IP fora da lista autorizada da chave.
403	`permissao_insuficiente`	A chave não tem a permissão exigida pela rota.
404	`nao_encontrado` · `rota_inexistente`	Registro ou rota inexistente.
409	`desbloqueio_ativo`	O contrato já está com desbloqueio de confiança em vigor.
422	ver cada rota	A regra de negócio não permite a ação (ex.: `contrato_nao_bloqueado`, `requer_desfecho_equipamento`).
429	`limite_excedido`	Limite de requisições por minuto atingido. Veja limites.
500	`erro_interno`	Falha inesperada. Tente de novo; se persistir, fale com o suporte.

Repita em 429 (depois do Retry-After), em 500 e em falha de rede, com espera crescente.
Não repita em 400, 401, 403, 404 e 422: o resultado será o mesmo até a causa ser corrigida.
Em POST /chamados, antes de repetir uma tentativa que falhou por rede, consulte os chamados do cliente para não abrir dois iguais.