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

# 01 - Consultar Vínculos

> Endpoint para consulta de vínculos empregatícios

## Visão Geral

O primeiro passo para oferecer crédito na modalidade de consignado privado é coletar os dados essenciais do trabalhador e obter sua autorização para consulta dos vínculos empregatícios.

A Wincred disponibiliza um endpoint assíncrono que abstrai toda a complexidade do processo de consulta, realizando automaticamente:

* Envio dos dados da autorização de consulta para a DATAPREV
* Validação e recuperação dos vínculos empregatícios ativos.

<Info>
  Este é um endpoint **assíncrono**. A resposta retorna imediatamente com um identificador, e você deve consultar o status posteriormente para obter o resultado.
</Info>

### Termo de aceite

O termo de aceite é **obrigatório** para consulta dos dados do trabalhador.
Imediatamente após o fornecimento dos dados do trabalhador, será enviado um termo de aceite para o cliente e o fluxo só poderá ser concluído após a assinatura do termo.

<Tip>
  A Wincred disponibiliza um modelo de termo de aceite pronto para uso, garantindo conformidade com a LGPD e requisitos regulatórios.
</Tip>

<Note>
  O HUB será [notificado](/e-consignado/casos-de-uso/contratação-ativa/webhooks-e-eventos/01-evento-de-listagem-de-vínculos#evento-assinatura-termo) após a assinatura ou rejeição do termo de aceite.

  Caso o trabalhador já possua um **termo de autorização válido** assinado com a wincred, esse fluxo será ignorado.
</Note>

<Warning>
  É importante enviar os dados do trabalhador corretos via API.

  **O termo será preenchido com essas informações**
</Warning>

***

## Pré-requisitos

<Warning>
  Antes de realizar a consulta, é obrigatória a captação dos seguintes dados e autorizações pelo originador:
</Warning>

### Dados do trabalhador

* **CPF**
* **Telefone**
* **Data de nascimento**
* **Nome**
* **Cidade**

***

## Endpoint

<ParamField path="POST" type="endpoint">
  `/api/v1/e-consignado/vinculos`
</ParamField>

### URL Base

HML: `https://integracao.apidev.wincred.digital`

### Headers

| Header          | Tipo   | Obrigatório | Descrição                      |
| --------------- | ------ | ----------- | ------------------------------ |
| `Content-Type`  | string | Sim         | `application/json`             |
| `Authorization` | string | Sim         | `Bearer {seu_token_de_acesso}` |

***

## Requisição

### Exemplo de Requisição

```bash theme={null}
curl -X POST "https://integracao.apidev.wincred.digital/api/v1/e-consignado/vinculos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {seu_token_de_acesso}" \
  -d '{
    "chaveIdentificadora": "2345678901",
    "cpf": "12345678900",
    "dataNascimento": "1980-01-01",
    "telefone": "11987654321",
    "nome": "João da silva",
    "cidade": "São Paulo"
  }'
```

### Parâmetros da Requisição

<ParamField path="chaveIdentificadora" type="string" required>
  Identificador único da requisição para rastreabilidade e idempotência.
  Esperamos que este valor seja uma string gerada pelo sistema do originador.

  <Tip>
    **Tamanho máximo**: 15 caracteres
  </Tip>
</ParamField>

<ParamField path="cpf" type="string" required>
  CPF do trabalhador

  **Exemplo:** `"12345678900"`

  <Tip>
    Enviar apenas números e sem formatação.
  </Tip>
</ParamField>

<ParamField path="dataNascimento" type="string" required>
  Data de nascimento

  **Exemplo:** `"1980-12-01"`

  <Tip>
    Formato esperado: `YYYY-MM-DD`
  </Tip>
</ParamField>

<ParamField path="telefone" type="string" required>
  Telefone do trabalhador com

  **Exemplo:** `"11987654321"`

  <Tip>
    Enviar com DDD e apenas números.

    **Tamanho:** 11 caracteres
  </Tip>
</ParamField>

<ParamField path="nome" type="string" required>
  Nome do trabalhador

  **Exemplo:** `"João da Silva"`

  <Tip>
    Enviar nome completo
  </Tip>
</ParamField>

<ParamField path="cidade" type="string" required>
  Cidade de residência do trabalhador

  **Exemplo:** `"São Paulo"`

  <Tip>
    Enviar nome da cidade
  </Tip>
</ParamField>

***

## Resposta

### Resposta de Sucesso (202 Accepted)

A requisição foi aceita e está sendo processada de forma assíncrona.

```json theme={null}
{
  "idRequisicao": "09874f03-55f4-404c-be58-951326d28336",
  "chaveIdentificadora": "2345678901",
  "idCotacao": "123e4567-e89b-12d3-a456-426614174000",
  "status": "AGUARDANDO_AUTORIZACAO_TERMO",
  "dataSolicitacao": "2024-01-01T10:00:00Z"
}
```

<Info>Caso algum erro aconteça na requisição, uma lista de erros será retornada.[**documentação de erros**](/e-consignado/casos-de-uso/contratação-ativa/erros/1-introducao)                     </Info>

## Respostas de erro comuns no sistema

### Resposta de Erro (4xx Bad Request)

```json theme={null}
{
    "erros": [
        {
            "codigo": "WIN_xxxx",
            "msg": "MENSGEM DE ERRO DESCRITIVA"
        }
    ]
}
```

### Resposta de Erro (422 Unprocessable Entity)

```json theme={null}
{
  "erros": [
    {
      "codigo": "WIN_XXXX",
      "msg": "Proposta não encontrada"
    }
  ]
}
```

### Resposta de Erro (401 Unauthorized)

```json theme={null}
{
  "code": 401,
  "message": ""
}
```

<Warning>
  **Esse payload é um retorno da API de autenticação e não da API do sistema.**

  Esta resposta pode indicar que o token de autenticação fornecido é inválido ou expirou. Verifique se o token está correto e se ainda é válido.
</Warning>

### Resposta de Erro (500 Unauthorized)

```json theme={null}
{
  "code": 500,
  "message": ""
}
```

## Códigos de Status

| Código | Descrição                            |
| ------ | ------------------------------------ |
| `202`  | Requisição aceita e em processamento |
| `401`  | Não autorizado - token inválido      |
| `422`  | Erro de validação dos dados          |
| `429`  | Muitas requisições, limite atingido  |
| `500`  | Erro interno do servidor             |

***

## Próximos Passos

<Steps>
  <Step title="Aguardar assinatura do termo">
    O sistema irá notificar o HUB caso o termo seja aceito ou rejeitado.

    Após a **assinatura** do termo, o disparo da consulta será realizado automaticamente.

    <Note>
      Esse passo será ignorado caso o trabalhador já possua um termo de autorização válido assinado com a wincred.
    </Note>
  </Step>

  <Step title="Aguardar processamento">
    A consulta é processada de forma assíncrona assim que o trabalhador aceita o termo.
  </Step>

  <Step title="Consultar resultado">
    Utilize o endpoint de consulta de status ou webhook para obter o resultado da consulta de vínculos.
  </Step>

  <Step title="Escolher vínculo">
    Com os vínculos retornados, você pode prosseguir para a próxima etapa de simular propostas de crédito consignado.
  </Step>
</Steps>

<Card title="Próximo: Consultar Status" icon="arrow-right" href="/e-consignado/casos-de-uso/contratação-ativa/webhooks-e-eventos/01-evento-de-listagem-de-vínculos">
  Consultar o status e resultado da consulta de vínculos
</Card>