Introdução

A API v1 da Régua de Cobrança expõe programaticamente tudo que o dashboard faz na operação de cobrança: clientes, cobranças, réguas, acordos, disputas, tarefas, importações e webhooks.

Para agentes de IA

Esta documentação é otimizada para LLMs: o índice completo em Markdown está em /llms.txt e o contrato da API em /openapi/openapi-v1-pt.yaml (variantes -en e -es no mesmo diretório). Prefira essas fontes a raspar o HTML.

Formato

A API aceita e devolve apenas JSON (UTF-8). Envie Content-Type: application/json em toda requisição com body.

Tipo de campo	Formato
Campos	camelCase nas respostas e nos bodies de requisição (dueDate, documentNumber)
Datas	ISO 8601 em UTC. Ex.: 2026-07-23T12:00:00.000Z
Valores monetários	Retornados como string decimal ("1500.00") para não perder precisão; aceitos como number nas requisições
Filtros de listagem	Query string em snake_case (due_date_from, person_id) — ver Paginação e filtros

Convenções

Convenção	Descrição
:id	Variável de caminho que precisa ser substituída na URL.
...	Conteúdo da resposta truncado para facilitar a leitura.
$DUNNING_TOKEN	Sua chave de API. Para testar em linha de comando, exporte-a: export DUNNING_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx e cole os comandos da documentação no terminal.

Envelope de erro

Todo erro responde com um envelope estável — message legível para humanos, code estável para máquinas (e, quando útil, details):

{
  "message": "Permissão insuficiente",
  "code": "FORBIDDEN"
}

Trate sempre pelo code (VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, IDEMPOTENCY_KEY_REUSED, RATE_LIMITED, INTERNAL_ERROR...) — o texto de message pode mudar sem aviso.

Códigos de retorno

A API usa os códigos HTTP padrão:

	Código	Descrição
✅	200 OK	Requisição bem-sucedida com corpo de resposta.
✅	201 Created	Recurso criado com sucesso.
✅	204 No Content	Requisição bem-sucedida, sem corpo de resposta.
❌	400 Bad Request	Requisição malformada — JSON inválido, header de idempotência inválido.
❌	401 Unauthorized	Chave de API ausente, inválida, revogada ou expirada.
❌	403 Forbidden	Chave sem o escopo necessário, ou recurso administrativo inacessível via API.
❌	404 Not Found	Recurso ou rota inexistente (ou pertencente a outra organização).
❌	409 Conflict	Conflito de estado — reuso de X-Idempotency-Key, transição inválida.
❌	422 Unprocessable Entity	Requisição bem formada, mas os dados não passam na validação de negócio.
❌	429 Too Many Requests	Limite de requisições excedido — aguarde o Retry-After.
❌	5xx	Erro no servidor — veja abaixo como re-tentar.

Erros 5xx e retry

500, 502, 503 e 504 indicam falha no nosso lado, quase sempre transitória. Sua integração deve:

1. Re-tentar com backoff exponencial (ex.: 1s, 2s, 4s, 8s...) e um teto de tentativas — nunca em loop imediato.
2. Usar X-Idempotency-Key nas mutações — o retry devolve a resposta original em vez de duplicar a operação.
3. Tratar timeout de rede como 5xx: não receber resposta não significa que a operação não executou; a idempotência resolve a ambiguidade.

Em 429, aguarde o número de segundos do header Retry-After antes da próxima tentativa.

Próximos passos

• Autenticação — chaves de API e escopos.
• Endpoints — ambientes e URLs base.
• Especificações OpenAPI — o contrato completo em OpenAPI 3.1.
• Rate limiting — limites e headers de resposta.
• Paginação e filtros — listagens e iteração.
• Idempotência — retries seguros em mutações.
• Webhooks — eventos em tempo real, sem polling.