Convenções da API

Esta página documenta as convenções de design que se aplicam a todos os endpoints da API Dinie. Entender essas convenções ajuda você a prever o comportamento da API mesmo antes de consultar a referência de cada endpoint.

A versão principal está no path da URL: /v3/...

Todas as respostas incluem o header de versão:

X-API-Version: 2026-03-01

A versão usa o formato de data (YYYY-MM-DD). Mudanças não-quebra (novos campos, novos endpoints, novos eventos de webhook) são introduzidas sob uma nova data. Mudanças que quebram compatibilidade exigem uma nova versão principal.

Segmentos de URL usam kebab-case, em letras minúsculas:

/v3/credit-offers/{id}
/v3/credit-offers/{id}/simulations
/v3/webhooks/endpoints/{id}/secret/rotate

• Substantivos no plural para coleções: /customers, /credit-offers, /loans
• Recurso individual acessado via /{coleção}/{id}
• Sub-recursos aninhados sob o recurso pai: /v3/customers/{id}/kyc-attachments
• Aninhamento vai no máximo 2 níveis de profundidade

Ações que não são CRUD usam um sufixo de verbo no path:

POST /v3/webhooks/endpoints/{id}/secret/rotate

Todos os nomes de campos usam snake_case:

{
  "approved_amount": 50000.00,
  "interest_rate": 3.50,
  "created_at": 1709546400
}

Sem camelCase, PascalCase ou kebab-case em corpos JSON.

Parâmetros de query também usam snake_case:

GET /v3/customers?external_id=partner123&starting_after=cust_abc123

• Headers de webhook: minúsculas com hifens (webhook-id, webhook-timestamp, webhook-signature)
• Headers OAuth: padrão (Authorization: Bearer ...)
• Headers da API: prefixo X- com segmentos PascalCase (X-API-Version, X-RateLimit-Limit)

Todos os campos de data/hora usam Unix epoch (inteiro, segundos desde 1 de janeiro de 1970 UTC):

"created_at": 1709546400

No OpenAPI: type: integer, format: int64.

Nenhum fuso horário é incluído no valor -- timestamps Unix são inerentemente UTC.

Campos que representam uma data de calendário sem componente de hora usam ISO 8601 date (YYYY-MM-DD) como string:

"due_date": "2026-04-03"

No OpenAPI: type: string, format: date.

Todos os valores monetários são representados como números JSON (number) com precisão de duas casas decimais:

{
  "approved_amount": 50000.00,
  "monthly_payment": 2289.42,
  "iof": 450.00
}

• Moeda é sempre BRL (Real Brasileiro) — não incluída na resposta, pois a plataforma opera exclusivamente em BRL
• Precisão: sempre exatamente 2 casas decimais
• Formato no OpenAPI: type: number, format: double

Campos sem valor são incluídos na resposta como null em vez de omitidos. Isso torna o schema da resposta previsível independente do estado:

{
  "id": "cust_abc123",
  "trading_name": null,
  "expires_at": null,
  "approved_amount": null
}

No OpenAPI, campos nullable usam type: ["string", "null"] (sintaxe JSON Schema 2020-12, suportada no OpenAPI 3.1).

Campos desconhecidos em corpos de requisição são silenciosamente ignorados (não rejeitados). Isso permite compatibilidade futura quando novos campos são adicionados. A especificação OpenAPI não define additionalProperties: false.

Da mesma forma, ao receber respostas da API, seu código deve ignorar campos que não reconhece — novos campos podem ser adicionados sem aviso prévio em versões menores.

Estes campos aparecem na maioria dos recursos:

Todos os IDs expostos pela API são prefixo + UUID sem hifens. O prefixo indica o tipo de recurso:

IDs são sempre strings, nunca inteiros. São imutáveis durante toda a vida do recurso.