Indicações

POST /referrals cria a indicação de um cliente. A resposta traz o link seguro da jornada, que você entrega ao cliente para que ele conduza a simulação e a contratação.

curl --request POST "$WINCRED_API_URL/referrals" \
  --header "Authorization: Bearer <chave do parceiro>" \
  --header "Content-Type: application/json" \
  --data '{
    "hub_code": "padrao",
    "customer": {
      "cpf": "000.000.000-00",
      "name": "CLIENTE SINTETICO DO TESTE",
      "phone": { "country_code": "55", "area_code": "11", "number": "987654321" },
      "email": "cliente.sintetico@example.com",
      "birth_date": "1988-04-17",
      "address": {
        "street": "Rua Sintetica do Teste",
        "number": "77",
        "complement": "apto sintetico",
        "neighborhood": "Bairro Sintetico",
        "city": "Cidade Sintetica",
        "state": "SP",
        "zip_code": "01001-000"
      }
    },
    "loan_request": { "amount": "5000.00", "installments": 24 }
  }'

O CPF dos exemplos, 000.000.000-00, é um marcador: a API o recusa com INVALID_CHECK_DIGIT. Substitua pelo CPF do cliente.

Apenas customer.cpf e customer.name são obrigatórios. Dos campos opcionais, envie o que você já coletou; o cliente confirma e complementa os dados na jornada.

{ "customer": { "cpf": "000.000.000-00", "name": "Ana" } }

Resposta (201):

{
  "process_external_id": "55555555-5555-4555-8555-555555555555",
  "hub_code": "padrao",
  "created": true,
  "url": "https://origination.example/sessao/parceiro/signed-token",
  "expires_at": "2026-11-14T10:12:00-03:00"
}

Persista o process_external_id. Ele é a chave da consulta e de todo webhook daquela indicação.
Entregue o url ao cliente. Ele é válido até expires_at.
Sem hub_code, a indicação entra no seu hub padrão (o que tem "default": true em GET /ping).

Repetir o POST é seguro

Se a chamada sofreu timeout, reenvie com tranquilidade. O mesmo CPF sempre devolve o mesmo processo, e é por isso que a API dispensa um Idempotency-Key. Quando já existe um processo aberto para o CPF, em qualquer um dos seus hubs, a resposta é 200 com "created": false:

o process_external_id é o do processo existente;
o url é novo, e o anterior continua válido até o próprio expires_at;
o hub_code é o do processo existente, que pode ser outro hub seu;
do novo pedido, apenas o CPF é considerado: os demais dados e o valor são validados, mas não alteram o processo.

Valor e prazo são um pedido

O loan_request é o que você pede para o cliente. Ele precisa estar dentro da faixa do hub, que você consulta em GET /ping; fora dela, a resposta é 422 LOAN_REQUEST_INVALID. O cliente pode ajustar valor e prazo na jornada. O proposal que você vê depois, no GET e nos webhooks, é o da proposta escolhida pelo cliente, e não o seu pedido. Veja a regra 5 do ciclo de vida.

Limite diário por CPF

O padrão é 3 encerramentos sem contrato por CPF por dia (fuso de São Paulo), configurável por parceiro. Atingido o limite, novas indicações daquele CPF respondem 429 CPF_DAILY_LIMIT_REACHED, com retry_after apontando para a próxima meia-noite de São Paulo. Aguarde esse horário antes de tentar novamente.

{
  "error": {
    "code": "CPF_DAILY_LIMIT_REACHED",
    "message": "Limite diário de tentativas sem sucesso do CPF atingido.",
    "request_id": "req-rest",
    "retry_after": "2026-10-16T00:00:00-03:00"
  }
}

O reaproveitamento de um processo já aberto não é afetado pelo limite.

Hub inativo

Um hub com "active": false em GET /ping recusa novas indicações com 403 HUB_INACTIVE, mesmo que o CPF já tenha processo aberto. Os processos já criados nele continuam disponíveis para consulta e seguem gerando notificações. A lista completa de campos e erros da rota está em Criar indicação e em Erros.

Introdução

Guia de integração

Referência da API

Eventos

Repetir o POST é seguro

Valor e prazo são um pedido

Limite diário por CPF

Hub inativo