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

# Como integrar

> O que a Wincred entrega, o que você informa e o caminho até a ativação em produção.

O onboarding é assistido de ponta a ponta pelo **time de integrações** da Wincred. O time cuida, junto com você, do cadastro do parceiro, da configuração dos hubs, das credenciais e do webhook, para que a sua equipe possa se concentrar na integração em si.

## O que a Wincred entrega

| Item | Descrição |
| - | - |
| **Chave de API** | Uma para dev e outra para produção. Veja [Autenticação](https://docs.wincred.digital/api-do-parceiro/autenticacao.md) |
| **Hubs** | Um parceiro pode ter mais de um hub (por exemplo, por condição comercial, produto ou marca). Cada hub tem um `code`, uma faixa de valor e prazo e pode estar ativo ou inativo. Você os consulta em `GET /ping` |
| **Segredo do webhook** | Usado para verificar a assinatura de cada notificação. Veja [Assinatura do webhook](https://docs.wincred.digital/api-do-parceiro/assinatura.md) |

## O que você informa à Wincred

**1. Os IPs de onde você chama a API**

Por segurança, a API aceita chamadas apenas de IPs previamente liberados (allowlist de entrada). Informe os IPs de saída dos seus servidores e a Wincred os libera. Uma chamada de um IP fora da lista é bloqueada na camada de gateway/WAF, antes de chegar à API, e por isso recebe `403` sem o envelope de erro em JSON.

**2. A URL do webhook**

O endpoint HTTPS do seu sistema que vai receber as notificações. A Wincred entrega diretamente nessa URL e não segue redirecionamentos.

**3. A autenticação do webhook**

Você escolhe entre a assinatura `X-Wincred-Signature`, presente em toda notificação, ou a assinatura combinada com um header próprio (você define o nome, por exemplo `x-api-key`, e o valor).

**4. Os eventos que você quer receber**

Você recebe apenas os eventos que assinar: `term_signed`, `contract_created`, `loan_disbursed` e `closed`. Veja [Webhooks](https://docs.wincred.digital/api-do-parceiro/webhooks.md).

> [!NOTE]
>
> A Wincred não garante IP fixo de saída para os webhooks. Por isso, valide cada notificação pela assinatura, e não pelo IP de origem.

## Ambientes

| Ambiente | Base da API | Para que serve |
| - | - | - |
| **Dev** | `https://orchestrator-partner.dev.wincred.digital/partners/v1` | Ambiente de testes do parceiro. Use a chave de dev e dados sintéticos |
| **Produção** | Enviada por e-mail na ativação | Indicações de clientes reais. O host não é publicado neste site |

Nos exemplos deste site, a base da API está na variável `WINCRED_API_URL`:

```bash theme={null}
export WINCRED_API_URL="https://orchestrator-partner.dev.wincred.digital/partners/v1"
```

## Do dev à produção

1. Receba a chave de dev e cadastre a URL do webhook de dev.
2. Siga o passo a passo de [Testando em dev](https://docs.wincred.digital/api-do-parceiro/testando-em-dev.md).
3. Confira o checklist abaixo e avise o time de integrações.
4. Na ativação, a Wincred envia por e-mail o host de produção e a chave de produção.

### Checklist para ir a produção

* [ ] `GET /ping` responde 200 e você guardou o `code` dos seus hubs.
* [ ] `POST /webhooks/test` responde `"delivered": true`.
* [ ] Seu endpoint verifica `X-Wincred-Signature` e recusa `t` fora da tolerância de 5 minutos.
* [ ] Seu endpoint deduplica pelo `event_id` e retorna 2xx imediatamente, processando o evento de forma assíncrona.
* [ ] Você persiste o `process_external_id` de cada indicação.
* [ ] Sua máquina de estados trata o `status` como um estado que pode retornar e usa o `GET` como fonte da verdade.
* [ ] Você registra o `request_id` das respostas com erro.
* [ ] Você repete com espera em `500`, `503` e timeout, e respeita o `Retry-After` no `429`.

## Suporte

Fale com o time de integrações da Wincred pelo canal combinado no onboarding. Para qualquer dúvida sobre uma chamada específica, informe o `X-Request-Id` da resposta: ele nos permite localizar a requisição rapidamente.


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