> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md).

# Consultas Dataprev (sob demanda)

Permitem escolher **qual vínculo** do trabalhador consultar, inclusive vínculos inelegíveis. Complementam, sem substituir, a [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) automática.

{% hint style="info" %}
Esta é a área de consultas após a autorização. O consentimento do trabalhador está em [Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md); a parte contábil pós-contrato (transferências e lançamentos), em [Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev.md).
{% endhint %}

## Quando usar

| Cenário                                                                                      | Use                                                                                                                                                              |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Margem do melhor vínculo elegível, disparada automaticamente após a autorização              | [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) (automática)                                   |
| Ver **todos** os vínculos autorizados (inclusive inelegíveis) para escolher qual detalhar    | [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) |
| Margem de **um vínculo específico**, inclusive forçando um inelegível                        | [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md)     |
| **Saldo de FGTS disponível** (+ multa rescisória) de um vínculo, como garantia de consignado | [Consultar FGTS Disponível](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md)           |

O fluxo automático não muda: após a autorização, a plataforma escolhe o melhor vínculo elegível (menor matrícula) e dispara `MARGIN_QUERY_COMPLETED`. As consultas desta seção não interferem nele.

## O conceito de `bondPublicId`

Um **vínculo** (bond) é uma relação de trabalho autorizada na Dataprev: matrícula + empregador. Cada vínculo tem um identificador estável, o **`bondPublicId`**, obtido na [listagem de vínculos autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) junto com matrícula, empregador e elegibilidade.

```
Listar vínculos → escolher o bondPublicId → Consultar margem por vínculo
```

## O padrão assíncrono

Todas as consultas desta seção vão à Dataprev (segundos, sujeitas a rate limit) e seguem o mesmo padrão:

1. **`POST`** inicia a consulta e responde **`202 Accepted`** com `{ requestId, status: PROCESSING }`.
2. Ao concluir, a plataforma dispara um **webhook** (`AUTHORIZED_BONDS_LISTED`, `MARGIN_QUERY_COMPLETED` ou `FGTS_AVAILABILITY_QUERY_COMPLETED`).
3. **`GET`** por `requestId` retorna o resultado quando `COMPLETED`. Enquanto `PENDING`/`PROCESSING`, retorna `202`.

```mermaid
sequenceDiagram
    autonumber
    actor O as Originador
    participant API as GTPayroll API
    participant DP as Dataprev

    O->>API: POST .../queries
    API-->>O: 202 Accepted { requestId, status: PROCESSING }

    API->>DP: consulta vínculos / margem
    Note over API,DP: processamento assíncrono<br/>(segundos, sujeito a rate limit)
    DP-->>API: resultado

    API-)O: webhook AUTHORIZED_BONDS_LISTED / MARGIN_QUERY_COMPLETED

    O->>API: GET .../queries/{requestId}
    alt requisição COMPLETED
        API-->>O: 200 OK + resultado (vínculos ou margem)
    else ainda PENDING / PROCESSING
        API-->>O: 202 Accepted (tente novamente)
    end
```

### Estados da requisição

| Status       | Significado                                                          |
| ------------ | -------------------------------------------------------------------- |
| `PENDING`    | Requisição criada, processamento não iniciado                        |
| `PROCESSING` | Consulta em andamento na Dataprev                                    |
| `COMPLETED`  | Concluída; resultado disponível no `GET`                             |
| `FAILED`     | Falha permanente; `errorCode`/`reason` no `GET` e webhook `*_FAILED` |

Sem webhooks, consulte o `GET` a cada **10 a 30 segundos** até receber `200`.

## Pré-requisitos

1. Employee [cadastrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md).
2. [Autorização Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md) em `AUTHORIZED`. Sem ela, os `POST` respondem `422`. A flag `forceIneligible` só contorna a elegibilidade do vínculo, não a autorização.

## Operações disponíveis

| Operação                                                                                                                                                             | Método | Endpoint                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| [Solicitar Listagem de Vínculos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md)     | `POST` | `/api/v1/originator/employees/{publicId}/authorized-bonds-queries`                                                  |
| [Consultar Resultado da Listagem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md)    | `GET`  | `/api/v1/originator/authorized-bonds-queries/{requestId}`                                                           |
| [Solicitar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md)         | `POST` | `/api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/margin-queries`                            |
| [Consultar Resultado da Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md)        | `GET`  | `/api/v1/originator/margin-queries/{requestId}`                                                                     |
| [Solicitar FGTS Disponível (por lastro)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md)  | `POST` | `/api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/fgts-availability-queries`                 |
| [Solicitar FGTS Disponível (por vínculo)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md) | `POST` | `/api/v1/originator/employees/{publicId}/employment-relationships/{relationshipPublicId}/fgts-availability-queries` |
| [Consultar Resultado do FGTS](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md)             | `GET`  | `/api/v1/originator/fgts-availability-queries/{requestId}`                                                          |

Webhooks de conclusão: [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
