> ## 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. # Consultar indicação > Devolve a **visão atual** do processo, montada no momento da consulta. Tem a mesma estrutura do `data` do webhook, mas **o GET é a fonte da verdade**: o `data` do webhook é congelado quando a notificação é gravada, enquanto o GET reflete o estado atual. Consulte-o antes de tomar uma decisão no seu sistema. Campos que o processo ainda não tem **são omitidos da resposta** (não vêm como `null`). Processo inexistente ou pertencente a outro parceiro: 404 `REFERRAL_NOT_FOUND`. ## OpenAPI ````yaml /api-do-parceiro/openapi.yaml get /referrals/{process_external_id} openapi: 3.1.0 info: title: API do Parceiro Wincred version: 1.0.0 summary: Indique clientes, acompanhe a contratação e receba notificações por webhook. description: > API REST para parceiros comerciais indicarem clientes para o crédito consignado CLT da Wincred e acompanharem a contratação. A integração é de servidor para servidor e tem baixo acoplamento: o seu sistema indica o cliente e, a partir daí, atua como um ouvinte do que acontece na Wincred, por webhooks e por consulta, enquanto o cliente conduz a simulação e a contratação no link seguro da Wincred. O servidor publicado aqui é o **ambiente de dev**, o ambiente de testes do parceiro. O host de produção é enviado por e-mail na ativação. Antes da primeira indicação, siga o passo a passo de teste: `GET /ping`, `POST /webhooks/test` e uma indicação com dados sintéticos. O onboarding é assistido de ponta a ponta pelo time de integrações da Wincred. ## Convenções - **Base:** `/partners/v1`. Só HTTPS. Corpo sempre JSON em UTF-8. - **Autenticação:** `Authorization: Bearer `, com a chave entregue pela Wincred. - **Identificador de requisição:** envie `X-Request-Id` (até 64 caracteres, `[A-Za-z0-9_-]`); se faltar ou for inválido, geramos um. Ele volta no header `X-Request-Id` de toda resposta e no campo `request_id` de todo erro. Informe-o ao suporte: ele nos permite localizar a requisição rapidamente. - **Dinheiro:** string decimal com ponto, por exemplo `"5000.00"`. Nunca número JSON, para preservar a precisão. - **Datas e horas:** RFC 3339 com o fuso de São Paulo, por exemplo `2026-10-05T10:12:00-03:00`. Data de nascimento: `AAAA-MM-DD`. - **Enums:** minúsculas com sublinhado (`awaiting_client`). - **Evolução:** campo novo em resposta ou webhook não é quebra de contrato: ignore o que não conhece. Uma quebra de contrato dá origem a `/partners/v2`. - **Campo desconhecido na requisição é recusado** (400). Os nomes dos campos diferenciam maiúsculas de minúsculas. ## Ordem em que a API avalia a requisição Saber a ordem das verificações ajuda a interpretar o erro recebido. 1. API desligada: 503 `SERVICE_UNAVAILABLE`, antes mesmo da autenticação. 2. Corpo com `Content-Length` acima de 16 KB: 413 `PAYLOAD_TOO_LARGE`, antes da autenticação. 3. Chave de API: 401 `UNAUTHENTICATED`. 4. Limite de requisições por minuto: 429 `RATE_LIMITED`. Uma requisição inválida também consome o limite. 5. Formato do corpo: 400 `INVALID_REQUEST` ou 422 `VALIDATION_FAILED`, sem criar processo. 6. Regras que dependem do cadastro do parceiro (hub, faixa de valor, limite diário): 403, 422 ou 429. ## Limites | Limite | Valor | |--------|-------| | Corpo da requisição | 16 KB (16384 bytes) | | Tempo máximo de processamento | 10 s; depois disso, 503 `SERVICE_UNAVAILABLE` | | Requisições por minuto | Por parceiro, contado separadamente para `POST /referrals`, `GET /referrals/{process_external_id}`, `GET /ping` e `POST /webhooks/test`. Ao exceder: 429 com `Retry-After` | | Encerramentos sem contrato por CPF | Padrão 3 por CPF por dia, configurável por parceiro. Ao exceder: 429 `CPF_DAILY_LIMIT_REACHED` | ## Respostas fora do envelope Por segurança, a API aceita chamadas apenas dos IPs que o parceiro informou à Wincred (allowlist de entrada). 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. Fale com o time de integrações para liberar o IP. contact: name: Integrações Wincred servers: - url: https://orchestrator-partner.dev.wincred.digital/partners/v1 description: >- Dev, o ambiente de testes do parceiro. O host de produção é enviado por e-mail na ativação. security: - bearerAuth: [] tags: - name: Webhooks description: >- Notificações que a Wincred envia para a webhook_url do parceiro a cada etapa da indicação. - name: Indicações description: Criar a indicação de um cliente e consultar o andamento do processo. - name: Teste de integração description: Rotas para validar a chave e o webhook antes da primeira indicação real. paths: /referrals/{process_external_id}: get: tags: - Indicações summary: Consultar indicação description: > Devolve a **visão atual** do processo, montada no momento da consulta. Tem a mesma estrutura do `data` do webhook, mas **o GET é a fonte da verdade**: o `data` do webhook é congelado quando a notificação é gravada, enquanto o GET reflete o estado atual. Consulte-o antes de tomar uma decisão no seu sistema. Campos que o processo ainda não tem **são omitidos da resposta** (não vêm como `null`). Processo inexistente ou pertencente a outro parceiro: 404 `REFERRAL_NOT_FOUND`. operationId: getReferral parameters: - name: process_external_id in: path required: true description: >- Identificador do processo, devolvido em `POST /referrals` e em todo webhook. schema: type: string format: uuid example: 55555555-5555-4555-8555-555555555555 - $ref: '#/components/parameters/XRequestId' responses: '200': description: Visão atual do processo. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Referral' examples: desembolsado: summary: Valor desembolsado value: process_external_id: 55555555-5555-4555-8555-555555555555 hub_code: padrao status: loan_disbursed proposal: gross_amount: '5000.00' installments: 24 ccb_number: '1234' disbursed_at: '2026-09-24T10:12:00-03:00' aguardando-cliente: summary: Link enviado, termo ainda não assinado value: process_external_id: 55555555-5555-4555-8555-555555555555 hub_code: padrao status: awaiting_client termo-assinado: summary: Termo assinado value: process_external_id: 55555555-5555-4555-8555-555555555555 hub_code: padrao status: term_signed '400': description: O `process_external_id` não é um UUID. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: id-invalido: value: error: code: INVALID_REQUEST message: Requisição inválida. request_id: req-rest '401': $ref: '#/components/responses/Unauthenticated' '404': description: Processo inexistente ou pertencente a outro parceiro. Confira o id. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: nao-encontrada: value: error: code: REFERRAL_NOT_FOUND message: Indicação não encontrada. request_id: req-rest '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: XRequestId: name: X-Request-Id in: header required: false description: > Identificador da requisição, até 64 caracteres `[A-Za-z0-9_-]`. Se faltar ou for inválido, a Wincred gera um. Volta no header `X-Request-Id` da resposta e no `request_id` de todo erro. schema: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ example: meu-teste-001 headers: XRequestId: description: >- O `X-Request-Id` que você enviou (se válido) ou o que a Wincred gerou. Informe-o ao suporte. schema: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ RetryAfter: description: Segundos de espera antes de tentar novamente. schema: type: integer minimum: 1 schemas: Referral: type: object description: >- Visão do processo. Mesma estrutura no `GET` e no `data` do webhook. Campos que o processo ainda não tem são omitidos da resposta. required: - process_external_id - hub_code - status properties: process_external_id: type: string format: uuid hub_code: type: string status: $ref: '#/components/schemas/ReferralStatus' proposal: $ref: '#/components/schemas/Proposal' ccb_number: type: string description: Número da CCB. Presente a partir da criação do contrato. example: '1234' disbursed_at: type: string format: date-time description: Data e hora do desembolso. Presente a partir do desembolso. ErrorEnvelope: type: object required: - error properties: error: $ref: '#/components/schemas/Error' ReferralStatus: type: string description: > Último marco alcançado. **Pode voltar**: depois de um reset, o processo retorna a `term_signed`, porque o contrato anterior foi encerrado antes do desembolso e o cliente escolhe uma nova proposta. Prepare a sua máquina de estados para esse retorno. | Valor | Significado | |-------|-------------| | `awaiting_client` | Link enviado, termo não assinado | | `term_signed` | Termo assinado, antes da criação do contrato | | `contract_created` | Do contrato até antes do desembolso (CCB, KYC, averbação) | | `loan_disbursed` | Valor desembolsado na conta do cliente (conclusão com sucesso) | | `closed` | Encerrado sem contratação. **Termo vencido sem contrato aparece como `closed` no GET, mas não gera webhook** | enum: - awaiting_client - term_signed - contract_created - loan_disbursed - closed Proposal: type: object description: > Proposta selecionada pelo cliente; ausente enquanto não há seleção. O valor é o da **proposta**, e não o pedido do parceiro: o cliente pode tê-lo ajustado na jornada. required: - gross_amount - installments properties: gross_amount: type: string pattern: ^[0-9]+\.[0-9]{2}$ description: Valor bruto da proposta, string decimal com 2 casas. example: '5000.00' installments: type: integer format: int32 example: 24 Error: type: object required: - code - message - request_id description: >- Envelope de erro. Programe contra `code`; a `message` é um texto fixo por código e pode mudar de redação. properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Texto fixo em português para cada `code`. request_id: type: string description: O mesmo valor do header `X-Request-Id`. Informe-o ao suporte. details: type: array description: > Presente só quando o erro aponta campos: 422 `VALIDATION_FAILED` gerado na borda e 400 `INVALID_REQUEST` quando o campo é localizável (tipo errado, campo desconhecido, campo duplicado). items: $ref: '#/components/schemas/ErrorDetail' retry_after: type: string format: date-time description: >- Só em `CPF_DAILY_LIMIT_REACHED`: a próxima meia-noite de São Paulo, RFC 3339. O `Retry-After` (segundos) vem no header. ErrorCode: type: string description: > | HTTP | `code` | Quando | O que fazer | |------|--------|--------|-------------| | 400 | `INVALID_REQUEST` | JSON malformado, tipo errado, campo desconhecido, `Content-Type` errado, id que não é UUID | Corrija; não repita igual | | 401 | `UNAUTHENTICATED` | Chave ausente, malformada, inválida ou revogada | Confira a chave | | 403 | `HUB_INACTIVE` | Hub desligado | Não repita | | 404 | `REFERRAL_NOT_FOUND` | Processo inexistente ou de outro parceiro | Confira o id | | 413 | `PAYLOAD_TOO_LARGE` | Corpo acima de 16 KB | Corrija | | 422 | `VALIDATION_FAILED` | Formato de dado do cliente, valor ou prazo, ou campo obrigatório ausente | Corrija pelos `details` | | 422 | `LOAN_REQUEST_INVALID` | Valor ou prazo fora da faixa do hub | Ajuste pela faixa de `GET /ping` | | 422 | `HUB_NOT_FOUND` | `hub_code` inexistente ou de outro parceiro | Corrija | | 422 | `WEBHOOK_NOT_CONFIGURED` | `POST /webhooks/test` sem `webhook_url` cadastrada | Fale com a Wincred | | 429 | `RATE_LIMITED` | Limite por minuto do parceiro | Espere o `Retry-After` | | 429 | `CPF_DAILY_LIMIT_REACHED` | Limite diário de indicações sem sucesso do CPF | Não repita antes de `retry_after` | | 500 | `INTERNAL_ERROR` | Erro nosso | Repita com espera | | 503 | `SERVICE_UNAVAILABLE` | API desligada, serviço fora do ar ou tempo máximo de 10 s | Repita com espera | enum: - INVALID_REQUEST - UNAUTHENTICATED - HUB_INACTIVE - REFERRAL_NOT_FOUND - PAYLOAD_TOO_LARGE - VALIDATION_FAILED - LOAN_REQUEST_INVALID - HUB_NOT_FOUND - WEBHOOK_NOT_CONFIGURED - RATE_LIMITED - CPF_DAILY_LIMIT_REACHED - INTERNAL_ERROR - SERVICE_UNAVAILABLE ErrorDetail: type: object required: - field - reason properties: field: type: string description: >- Caminho do campo com pontos, por exemplo `customer.address.zip_code`. example: customer.cpf reason: type: string description: > | `reason` | Significado | |----------|-------------| | `REQUIRED` | Campo obrigatório ausente ou vazio | | `INVALID_FORMAT` | Formato ou tipo inválido | | `INVALID_CHECK_DIGIT` | CPF com dígito verificador inválido ou dígitos repetidos | | `OUT_OF_RANGE` | Fora do tamanho ou da faixa permitida | | `NOT_ALLOWED` | Valor bem formado, mas não aceito (por exemplo, código de país diferente de 55) | | `UNKNOWN_FIELD` | Campo que a API não conhece | enum: - REQUIRED - INVALID_FORMAT - INVALID_CHECK_DIGIT - OUT_OF_RANGE - NOT_ALLOWED - UNKNOWN_FIELD responses: Unauthenticated: description: Chave de API ausente, malformada, inválida ou revogada. Confira a chave. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: sem-chave: value: error: code: UNAUTHENTICATED message: Chave de API ausente, inválida ou revogada. request_id: 0b9f3c2e-6d1a-4e8b-9c7d-2a4f6e8b0c1d RateLimited: description: >- Excedeu o limite por minuto. Aguarde o `Retry-After` (segundos). O corpo não traz `retry_after`. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: limite-por-minuto: value: error: code: RATE_LIMITED message: Limite de requisições excedido. request_id: req-rate InternalError: description: >- Erro interno da Wincred. Repita com espera; `POST /referrals` é seguro de repetir. Se persistir, informe o `request_id` ao time de integrações. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: erro-interno: value: error: code: INTERNAL_ERROR message: Erro interno. request_id: req-rest ServiceUnavailable: description: > API desligada, serviço da Wincred fora do ar ou tempo máximo de 10 s excedido. Repita com espera. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: indisponivel: value: error: code: SERVICE_UNAVAILABLE message: Serviço indisponível. request_id: 0b9f3c2e-6d1a-4e8b-9c7d-2a4f6e8b0c1d securitySchemes: bearerAuth: type: http scheme: bearer description: > Chave de API do parceiro, entregue pelo time de integrações da Wincred. Header: `Authorization: Bearer ` (o esquema `Bearer` não diferencia maiúsculas). Por segurança, chave ausente, malformada, inválida ou revogada recebem a mesma resposta: 401 `UNAUTHENTICATED`. Guarde a chave apenas no servidor e solicite a rotação ao time de integrações quando precisar trocá-la. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.