# Convenções

Valores em centavos, datas, paginação, idempotência e limites de uso.

Regras que valem para toda a API. Ler esta página uma vez evita a maioria dos erros de integração.

## Dinheiro é sempre em centavos

Todo valor monetário é um **número inteiro em centavos**, na moeda BRL. Nunca use decimais.

| Você quer cobrar | Envie | Não envie |
| --- | --- | --- |
| R$ 5,00 | `500` | `5.00` · `"5,00"` |
| R$ 19,90 | `1990` | `19.9` |
| R$ 129,90 | `12990` | `129.90` |
| R$ 1.500,00 | `150000` | `1500` |

> ⚠️ A API **recusa** valores com ponto ou vírgula, com `validation_error`. É proposital: `19.90` não tem representação exata em ponto flutuante, e um centavo perdido em arredondamento vira divergência de conciliação no fim do mês.

Valor mínimo por cobrança: `500` (R$ 5,00). Se a sua conta tiver limite por transação ou limite diário configurado, valores acima dele respondem `403` com `amount_limit_exceeded` ou `daily_limit_exceeded`.

## Datas

Todas as datas saem em **ISO-8601 com fuso de Brasília** (UTC−03:00):

_Formato_

```json
{
  "created_at": "2026-08-07T14:32:10-03:00",
  "paid_at": "2026-08-07T14:35:02-03:00",
  "available_at": "2026-09-06T14:35:02-03:00"
}
```

Campos de data ainda não preenchidos vêm como `null` — uma cobrança pendente tem `paid_at: null`.

## Idempotência

Timeout de rede não diz se a cobrança foi criada. Sem proteção, sua retentativa cria uma **segunda cobrança real** e o cliente é cobrado duas vezes.

Envie o header `Idempotency-Key` em todo `POST` que movimenta dinheiro. Se a mesma chave chegar de novo, devolvemos a resposta original — sem criar nada:

_Requisição_

```bash
curl -X POST https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Idempotency-Key: pedido-48219" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```

A resposta repetida vem com o header `Idempotent-Replay: true`, para você saber que não foi uma criação nova.

| Situação | Resposta |
| --- | --- |
| Chave nova | Processa normalmente. |
| Mesma chave, mesmo corpo, já concluída | Devolve a resposta original, idêntica. |
| Mesma chave, mesmo corpo, ainda processando | `409 idempotency_key_in_progress`. Aguarde e consulte antes de repetir. |
| Mesma chave, corpo diferente | `422 idempotency_key_reused`. Use uma chave nova. |

**Como escolher a chave:** use algo que identifique a *operação*, não a tentativa. O número do pedido é ideal — `pedido-48219`. Um UUID gerado a cada retentativa não protege nada, porque cada tentativa teria uma chave diferente.

As chaves valem por **24 horas**. Respostas `5xx` e `429` não são gravadas: são falhas transitórias e a retentativa precisa poder tentar de verdade.

## Paginação

Listagens aceitam `limit` (1 a 100, padrão 25) e `offset`:

_Requisição_

```bash
curl "https://novexfinance.com.br/api/v1/charges?limit=50&offset=100" \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

_Resposta_

```json
{
  "object": "list",
  "data": [
    // … até 50 cobranças
  ],
  "has_more": true,
  "limit": 50,
  "offset": 100
}
```

Use `has_more` para saber quando parar — é mais confiável do que comparar o tamanho de `data` com o `limit`. Os resultados vêm sempre do mais recente para o mais antigo.

## Limites de uso

| Escopo | Limite |
| --- | --- |
| Requisições por chave | 300 por minuto |
| Escritas (POST/DELETE) por chave | 60 por minuto |
| Requisições sem autenticação, por IP | 20 por minuto |

Ao estourar, a resposta é `429` com `rate_limit_exceeded` e o header `Retry-After` em segundos. Respeite esse valor — retentar antes só consome a cota da janela seguinte.

> ℹ️ Se você está batendo no limite consultando cobranças em laço, o problema não é o limite: é a estratégia. Troque a consulta repetida por [webhooks](https://novexfinance.com.br/docs/webhooks) e o volume cai para quase zero.

## Identificadores

Cada objeto tem um ID com prefixo que diz o que ele é. Guarde-os como **texto** — nunca como número:

| Prefixo | Objeto | Exemplo |
| --- | --- | --- |
| `ch_` | Cobrança | `ch_9f2a71c4e8b35d06a147` |
| `chk_` | Checkout hospedado | `chk_4b81de07a2f6c395e0d8` |
| `wd_` | Saque | `wd_1c7fa03e95b846d2f0ba` |
| `whe_` | Endpoint de webhook | `whe_12` |
| `evt_` | Evento de webhook | `evt_ac41f9b26d80375e1c4a` |
| `acct_` | Conta | `acct_42` |

## Sua própria referência

O campo `reference` guarda o identificador que faz sentido *no seu sistema* — número do pedido, ID da fatura. Ele volta em toda consulta e em todo webhook, e serve de filtro:

_Buscar pela sua referência_

```bash
curl "https://novexfinance.com.br/api/v1/charges?reference=48219" \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

Para dados extras, use `metadata`: um objeto livre de até 30 chaves, com valores de texto, número ou booleano. Ele é devolvido intacto em consultas e webhooks — nós não interpretamos nada dele.

_Exemplo_

```json
{
  "reference": "48219",
  "metadata": {
    "canal": "app-ios",
    "vendedor_id": 77,
    "primeira_compra": true
  }
}
```

## Rastrear uma requisição

Toda resposta traz o header `X-Request-Id`, e todo erro repete esse valor em `error.request_id`. Registre-o no seu log: com ele, o suporte encontra exatamente a requisição que falhou.


---

Documentação completa: https://novexfinance.com.br/docs/convencoes
Base da API: https://novexfinance.com.br/api/v1