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

# Indicações

> Como criar uma indicação, por que repetir a chamada é seguro e o que o valor pedido significa.

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

```bash theme={null}
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 }
  }'
```

> [!WARNING]
>
> 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.

```json theme={null}
{ "customer": { "cpf": "000.000.000-00", "name": "Ana" } }
```

**Resposta (201):**

```json theme={null}
{
  "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](https://docs.wincred.digital/api-do-parceiro/consultar.md) 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](https://docs.wincred.digital/api-do-parceiro/ciclo-de-vida.md#as-5-regras).

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

```json theme={null}
{
  "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](https://docs.wincred.digital/api-do-parceiro/referencia/criar-indicacao.md) e em [Erros](https://docs.wincred.digital/api-do-parceiro/erros.md).


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