# 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.

## Versionamento

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.

## URLs e Recursos

### Formato dos Paths

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
```

### Nomes de Recursos

- 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

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


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

## Nomes de Campos

### Corpos de Requisição e Resposta

Todos os nomes de campos usam **snake_case**:


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

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

### Parâmetros de Query

Parâmetros de query também usam **snake_case**:


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

### Headers

- 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`)


## Data e Hora

### Timestamps

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


```json
"created_at": 1709546400
```

No OpenAPI: `type: integer, format: int64`.

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

### Campos Somente Data

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


```json
"due_date": "2026-04-03"
```

No OpenAPI: `type: string, format: date`.

## Valores Monetários

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


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

### Regras

- 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 Nulos

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:


```json
{
  "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

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.

## Campos Comuns de Resposta

Estes campos aparecem na maioria dos recursos:

| Campo | Tipo | Formato | Descrição |
|  --- | --- | --- | --- |
| `id` | string | ID prefixado | Identificador único do recurso (ex.: `cust_`, `ln_`, `co_`) |
| `status` | string | enum | Estado atual do ciclo de vida (quando aplicável) |
| `created_at` | integer | int64 | Unix epoch (segundos) de criação |
| `updated_at` | integer | int64 | Unix epoch (segundos) da última modificação (quando aplicável) |


### Identificadores

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

| Recurso | Prefixo | Exemplo |
|  --- | --- | --- |
| Cliente | `cust_` | `cust_550e8400e29b41d4a716446655440000` |
| Oferta de Crédito | `co_` | `co_550e8400e29b41d4a716446655440000` |
| Empréstimo | `ln_` | `ln_550e8400e29b41d4a716446655440000` |
| Simulação | `sim_` | `sim_550e8400e29b41d4a716446655440000` |
| Transação | `tx_` | `tx_550e8400e29b41d4a716446655440000` |
| Endpoint de Webhook | `we_` | `we_550e8400e29b41d4a716446655440000` |


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