> 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.md).

# Margem

A **margem consignável** é o valor máximo que pode ser descontado por mês da folha do trabalhador para pagar parcelas de empréstimo. Ela é informada pela Dataprev, por vínculo, junto com elegibilidade, dados do vínculo (categoria, CBO, CNAE do empregador, nacionalidade, tipo de bloqueio, quantidade de consignados ativos etc.) e, quando houver, [alertas de afastamento e desligamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#alertas-do-trabalhador-alerts) e [empréstimos legados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#emprestimos-legados-legacyloans).

## Métodos de consulta de margem

|                    | **Melhor vínculo** (automático)                                                | **Manual** (por vínculo)                                                     |
| ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Seleção do vínculo | A plataforma escolhe o melhor vínculo elegível                                 | O originador escolhe um vínculo (`bondPublicId`)                             |
| Disparo            | Automático após a autorização; depois, sob demanda no `POST /margin`           | Sob demanda                                                                  |
| Vínculos múltiplos | Retorna só o melhor                                                            | Lista todos os vínculos autorizados e consulta um a um                       |
| Vínculo inelegível | Não é retornado                                                                | Pode ser consultado com `forceIneligible=true`                               |
| Modelo             | `GET` síncrono (`200`/`202`) + atualização assíncrona (`POST` `202` → webhook) | Assíncrono (`202` + `requestId` → webhook → `GET`)                           |
| Endpoint           | `GET` / `POST /employees/{publicId}/margin`                                    | `POST .../authorized-bonds/{bondPublicId}/margin-queries`                    |
| Quando usar        | Caso padrão de originação                                                      | Múltiplos vínculos, vínculo específico ou inelegível, correlação por vínculo |

* **Melhor vínculo**: [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) para ler e [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) para pedir margem nova.
* **Por vínculo**: [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) e [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md).

## 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) concluída: webhook `AUTHORIZATION_COMPLETED` ou [Consultar Status da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md).

## Comportamento do `GET /margin`

| Status HTTP | Significado                                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200`       | Margem disponível                                                                                                                                                                                                  |
| `202`       | Consulta em processamento. Consulte de novo a cada **10 a 30 segundos**                                                                                                                                            |
| `422`       | Sem margem vigente e sem consulta em andamento (`MARGIN_REFRESH_REQUIRED`). Chame [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) |

O `GET` só lê; ver [O `GET` read-only](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#o-get-read-only). Com a margem, siga para [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md).

## Operações disponíveis

| Operação                                                                                                                         | Método | Endpoint                                         |
| -------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------ |
| [Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md)                | `GET`  | `/api/v1/originator/employees/{publicId}/margin` |
| [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) | `POST` | `/api/v1/originator/employees/{publicId}/margin` |

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