> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wincred.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções

> Formato, headers, dinheiro, datas, limites e evolução da API.

As convenções abaixo valem para todas as rotas. Conhecê-las desde o início evita surpresas na serialização e no tratamento de respostas.

| Tema | Regra |
| - | - |
| **Base** | `<host>/partners/v1`. Veja os [ambientes](https://docs.wincred.digital/api-do-parceiro/como-integrar.md#ambientes) |
| **Formato** | Somente HTTPS e somente JSON em UTF-8. A integração é de servidor para servidor |
| **Dinheiro** | String decimal com ponto: `"5000.00"`. Nunca número JSON, para preservar a precisão |
| **Datas e horas** | RFC 3339 com o fuso de São Paulo: `2026-10-05T10:12:00-03:00`. Data de nascimento: `AAAA-MM-DD` |
| **Enums** | Minúsculas com sublinhado: `awaiting_client` |
| **Campo ausente na resposta** | Um campo que o processo ainda não tem é omitido da resposta, em vez de vir como `null` |
| **Campo desconhecido** | Na requisição, é recusado com `400`. Na resposta e no webhook, ignore o que você não conhece: um campo novo não é quebra de contrato |
| **Versão** | Uma quebra de contrato dá origem a `/partners/v2` |

## Headers da requisição

| Header | Obrigatório | Conteúdo |
| - | - | - |
| `Authorization` | Sim | `Bearer <chave do parceiro>` |
| `Content-Type` | Só no `POST /referrals` | `application/json` (aceita `charset=utf-8`; outro charset é recusado com 400) |
| `X-Request-Id` | Não | Até 64 caracteres `[A-Za-z0-9_-]`. Se faltar ou for inválido, a Wincred gera um. Volta no header `X-Request-Id` de toda resposta e no `request_id` de todo erro |

## Limites

| Limite | Valor |
| - | - |
| Corpo da requisição | 16 KB. Acima disso, `413 PAYLOAD_TOO_LARGE` |
| Tempo máximo de processamento | 10 s. Depois disso, `503 SERVICE_UNAVAILABLE` |
| Requisições por minuto | Por parceiro, contadas separadamente para cada uma das 4 rotas. Ao exceder, `429 RATE_LIMITED` com `Retry-After` |
| Encerramentos sem contrato por CPF | Padrão 3 por CPF por dia, configurável por parceiro. Veja [Indicações](https://docs.wincred.digital/api-do-parceiro/indicacoes.md#limite-diario-por-cpf) |

## Ordem em que a API avalia a requisição

Saber a ordem das verificações ajuda a interpretar o erro recebido. A API avalia a requisição nesta sequência:

1. API desligada: `503 SERVICE_UNAVAILABLE`, antes da autenticação.
2. Corpo acima de 16 KB: `413 PAYLOAD_TOO_LARGE`, antes da autenticação.
3. Chave de API: `401 UNAUTHENTICATED`.
4. Limite por minuto: `429 RATE_LIMITED`. Uma requisição inválida também consome o limite.
5. Formato do corpo: `400 INVALID_REQUEST` ou `422 VALIDATION_FAILED`, sem criar processo.
6. Regras do seu cadastro (hub, faixa de valor, limite diário): `403`, `422` ou `429`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.