Convenções - Wincred docs

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

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:

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