Pular para o conteúdo principal

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 campoFormato
CamposcamelCase nas respostas e nos bodies de requisição (dueDate, documentNumber)
DatasISO 8601 em UTC. Ex.: 2026-07-23T12:00:00.000Z
Valores monetáriosRetornados como string decimal ("1500.00") para não perder precisão; aceitos como number nas requisições
Filtros de listagemQuery string em snake_case (due_date_from, person_id) — ver Paginação e filtros

Campos personalizados (customData)​

Os recursos principais (clientes, cobranças, acordos, tarefas, interações) aceitam um objeto JSON livre no campo customData, para você guardar seus próprios dados junto do recurso (IDs do seu ERP, flags internas...). Em disputas, o campo equivalente chama-se customMetadata. Limites, iguais em todos:

  • 64 KB de payload serializado, no máximo;
  • 16 níveis de aninhamento, no máximo;
  • as chaves __proto__, constructor e prototype são rejeitadas.

Violações respondem 400 com code: "VALIDATION_ERROR" e o motivo em details. No update, o comportamento padrão é replace: o objeto enviado substitui o armazenado por inteiro (e null limpa o campo). Para mesclar em vez de substituir, envie customDataMode: "merge" no body do update — objetos aninhados são mesclados em profundidade; escalares, arrays e null sobrescrevem a chave.

Convenções​

ConvençãoDescrição
:idVariável de caminho que precisa ser substituída na URL.
...Conteúdo da resposta truncado para facilitar a leitura.
$DUNNING_TOKENSua 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ódigoDescrição
✅200 OKRequisição bem-sucedida com corpo de resposta.
✅201 CreatedRecurso criado com sucesso.
✅204 No ContentRequisição bem-sucedida, sem corpo de resposta.
❌400 Bad RequestRequisição malformada — JSON inválido, header de idempotência inválido.
❌401 UnauthorizedChave de API ausente, inválida, revogada ou expirada.
❌403 ForbiddenChave sem o escopo necessário, ou recurso administrativo inacessível via API.
❌404 Not FoundRecurso ou rota inexistente (ou pertencente a outra organização).
❌409 ConflictConflito de estado — reuso de X-Idempotency-Key, transição inválida.
❌422 Unprocessable EntityRequisição bem formada, mas os dados não passam na validação de negócio.
❌429 Too Many RequestsLimite de requisições excedido — aguarde o Retry-After.
❌5xxErro 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​