Testando em dev

O ambiente de dev é o ambiente de testes do parceiro. Valide a integração nele, com a chave de dev e dados sintéticos, antes de solicitar a ativação em produção.

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:

export WINCRED_API_URL="https://orchestrator-partner.dev.wincred.digital/partners/v1"

A validação segue três passos, nesta ordem. Os dois primeiros não criam processo, então você pode repeti-los à vontade.

1. Valide a chave: GET /ping

curl "$WINCRED_API_URL/ping" \
  --header "Authorization: Bearer <chave do parceiro>" \
  --header "X-Request-Id: meu-teste-001"

Resposta esperada (200):

{
  "partner": "parceiro-x",
  "hubs": [
    {
      "code": "padrao",
      "default": true,
      "active": true,
      "loan_limits": {
        "min_amount": "750.00",
        "max_amount": "25000.50",
        "installment_options": [6, 12, 24]
      }
    },
    {
      "code": "sem-faixa",
      "default": false,
      "active": false,
      "loan_limits": null
    }
  ]
}

401 UNAUTHENTICATED: chave errada, revogada ou mal formatada no header.
403 sem corpo JSON: o seu IP não está na allowlist de entrada e foi bloqueado na camada de gateway/WAF. Fale com o time de integrações.
Anote o code dos hubs e a faixa de valor e prazo. Use a faixa retornada aqui, em vez de uma cópia manual, para acompanhar mudanças de configuração.
loan_limits: null: o hub não tem faixa configurada e recusa toda indicação com loan_request.

2. Teste o webhook: POST /webhooks/test

curl --request POST "$WINCRED_API_URL/webhooks/test" \
  --header "Authorization: Bearer <chave do parceiro>"

A Wincred envia imediatamente um evento ping para a sua URL, com a mesma autenticação e a mesma assinatura das notificações reais, e devolve o resultado:

{
  "event_id": "7d0f3a6e-2b1c-4d5e-8f90-1a2b3c4d5e6f",
  "delivered": true,
  "http_status": 200,
  "error": null,
  "duration_ms": 120
}

`error`	O que significa	O que fazer
`null`	Entregue: o seu endpoint respondeu 2xx	Siga para o passo 3
`timeout`	O seu endpoint não respondeu dentro do prazo	Retorne 2xx imediatamente e processe o evento de forma assíncrona
`connection_error`	Não foi possível conectar (inclui host que não resolve)	Confira URL, DNS e firewall
`tls_error`	Falha de certificado ou de handshake	Use um certificado válido com a cadeia completa
`http_status`	Respondeu fora de 2xx (veja `http_status`)	Corrija a rota ou a autenticação do seu endpoint

Uma falha na entrega não é erro da rota: a resposta é 200 com "delivered": false.
422 WEBHOOK_NOT_CONFIGURED: você ainda não tem URL cadastrada. Fale com o time de integrações.
O teste é síncrono e sem retentativa. Corrija o que for preciso e chame de novo.
Confira que o seu endpoint verificou a assinatura do ping.

3. A primeira indicação: POST /referrals

Envie uma indicação com dados sintéticos, usando um CPF de teste combinado com o time de integrações:

curl --request POST "$WINCRED_API_URL/referrals" \
  --header "Authorization: Bearer <chave do parceiro>" \
  --header "Content-Type: application/json" \
  --data '{ "customer": { "cpf": "<CPF de teste>", "name": "Cliente Sintético" } }'

O esperado é 201 com o process_external_id e o url da jornada. A partir daí, consulte o processo com GET /referrals/{process_external_id} e acompanhe os webhooks.

Use apenas dados sintéticos em dev. Nunca envie CPF, nome ou contato de cliente real fora de produção.

Ver um erro de validação sem criar processo

A validação do corpo acontece antes de qualquer processo ser criado. O CPF marcador dos exemplos, 000.000.000-00, é recusado:

curl --request POST "$WINCRED_API_URL/referrals" \
  --header "Authorization: Bearer <chave do parceiro>" \
  --header "Content-Type: application/json" \
  --data '{ "customer": { "cpf": "000.000.000-00", "name": "Ana" } }'

O esperado é 422 VALIDATION_FAILED, com { "field": "customer.cpf", "reason": "INVALID_CHECK_DIGIT" } em details. Lembre-se de que a requisição conta no limite por minuto. Quando os três passos estiverem verdes, siga o checklist para ir a produção.

Introdução

Guia de integração

Referência da API

Eventos

Ver um erro de validação sem criar processo