> 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/guias/glossario.md).

# Glossário

Termos da API GTPayroll (originação de consignado privado), agrupados por domínio. Nomes em `monospace` são campos e valores da API.

***

## Identidade e originador

| Termo                       | Definição                                                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **employee / trabalhador**  | A pessoa para quem o consignado é originado. Primeira entidade do fluxo, cadastrada com CPF, nome, data de nascimento e contato.                                      |
| **`publicId`**              | Identificador público do recurso. O do `employee` está no caminho da maioria dos endpoints de originação (ex.: `POST /employees/{publicId}/authorization-trails`).    |
| **originator / originador** | O parceiro que conduz a originação pela API. Estratégia de assinatura, regras de elegibilidade e outras configurações são definidas **por originador** no onboarding. |

***

## Estratégias e provedores de assinatura

Detalhes em [Estratégias de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md).

| Termo                                                              | Definição                                                                                                                                                                                                                             |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **estratégia de assinatura**                                       | Define **quem coleta a assinatura** (autorização Dataprev e contrato). Configurada por originador. Valores: `GIRO` e `ORIGINATOR_MANAGED`.                                                                                            |
| **`GIRO`**                                                         | Estratégia do **contrato (CCB)** em que a Giro.Tech gera o PDF e coleta a assinatura. Na autorização Dataprev, quem coleta é sempre o originador.                                                                                     |
| **`ORIGINATOR_MANAGED`**                                           | O originador coleta a assinatura no próprio provedor e envia o documento assinado. Em `authorizationSignatureStrategy`, é pré-requisito da trilha opt-in e do envio de termo assinado (sem ela, `403 ORIGINATOR_OPT_IN_NOT_ENABLED`). |
| **`authorizationSignatureStrategy` / `contractSignatureStrategy`** | Estratégia de assinatura da **autorização Dataprev** e do **contrato (CCB)**, definidas de forma independente.                                                                                                                        |
| **`formalizationStrategy`**                                        | Como a CCB é processada **após a averbação**: `GTBANKER` (formalização e desembolso via GTBanker) ou `ORIGINATOR_MANAGED` (o originador formaliza). Independe da estratégia de assinatura.                                            |

***

## Autorização

Detalhes em [Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md) e [Ciclo de Vida da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ciclo-de-vida-da-autorizacao.md).

| Termo                                      | Definição                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **autorização Dataprev**                   | Consentimento do trabalhador para a consulta dos seus dados na Dataprev. Sem ela não há margem. Dois caminhos (termo em PDF ou trilha opt-in), ambos terminando em `AUTHORIZATION_COMPLETED`.                                                                                                                                                |
| **termo / manifestação de vontade**        | O documento ou registro da autorização. Vale **30 dias** a partir do aceite; vencido, exige re-autorização. Com termo vencido, a consulta de margem responde `200` com `status: TERM_EXPIRED` ([Ciclo de Vida da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ciclo-de-vida-da-autorizacao.md)).                  |
| **lastro**                                 | Evidência do aceite custodiada pela Giro: o PDF assinado ou a trilha opt-in (IP, timestamp, sessão, fingerprint).                                                                                                                                                                                                                            |
| **Termo em Trilha Opt-In**                 | Autorização **sem PDF**: o originador coleta o opt-in no próprio canal e envia a trilha de aceite pela API; a Giro autoriza na Dataprev pelo canal Web Correspondente. Ver [Criar Trilha de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md). |
| **trilha de aceite / trilha de auditoria** | Evidências do aceite (IP, timestamp, sessão, fingerprint, device e, opcionalmente, `events[]`). No termo em PDF, página anexa ao documento; na trilha opt-in, enviada pela API e amarrada ao NSU. Ver [Trilha de Auditoria](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/trilha-de-auditoria.md).                              |
| **NSU**                                    | Identificador do documento de autorização. Na re-autorização, um **novo NSU** passa a valer e o anterior fica como lastro (`SUPERSEDED`).                                                                                                                                                                                                    |

***

## Margem e vínculos

Detalhes em [Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem.md) e [Consultas Dataprev (sob demanda)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md).

| Termo                                              | Definição                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **margem consignável**                             | Valor máximo que pode ser descontado por mês da folha do trabalhador para pagar parcelas. Determinada pela Dataprev a partir do vínculo.                                                                                                                                                                                                                                                                                                                                           |
| **vínculo / bond**                                 | Relação de trabalho autorizada na Dataprev (matrícula + empregador). O trabalhador pode ter vários; no fluxo automático, a plataforma escolhe o melhor vínculo elegível.                                                                                                                                                                                                                                                                                                           |
| **`bondPublicId`**                                 | Identificador estável de um vínculo autorizado, obtido na [listagem de vínculos autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) e usado para consultar a margem de um vínculo específico.                                                                                                                                                                                             |
| **`forceIneligible`**                              | Em `POST .../authorized-bonds/{bondPublicId}/margin-queries`, `true` consulta a margem de vínculo **inelegível**. Não dispensa a autorização. Sem ele, vínculo inelegível retorna `422 BOND_NOT_ELIGIBLE`.                                                                                                                                                                                                                                                                         |
| **alerta (`alerts`)**                              | Aviso de **afastamento** ou **desligamento** vindo da Dataprev, no array opcional `alerts` de cada vínculo da [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#alertas-do-trabalhador-alerts) e do `MARGIN_QUERY_COMPLETED`. `null` quando não há.                                                                                                                                                               |
| **afastamento (`SUSPENSION`)**                     | `alertType=SUSPENSION` ("Afastamento"): suspensão temporária do vínculo (ex.: acidente/doença do trabalho). Campos `suspensionReasonCode`/`suspensionReasonDescription`, `suspensionStartDate` e `suspensionEndDate`.                                                                                                                                                                                                                                                              |
| **desligamento (`TERMINATION`)**                   | `alertType=TERMINATION` ("Desligamento"): encerramento do vínculo. Campos `terminationReasonCode`/`terminationReasonDescription`, `terminationDate`, `priorNoticeDate` e `priorNoticeEndDate`.                                                                                                                                                                                                                                                                                     |
| **empréstimo legado (`legacyLoans`)**              | Empréstimo que o trabalhador já tem, informado pela Dataprev no array opcional `legacyLoans` de cada vínculo da [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#emprestimos-legados-legacyloans) e do `MARGIN_QUERY_COMPLETED`: `financialInstitutionCode`, `contractNumber`, `contractType`/`contractTypeDescription`, datas e valores (parcelas, taxa mensal, CET, saldo devedor etc.). `null` quando não há. |
| **`workerCategory` / `workerCategoryDescription`** | Categoria do trabalhador no eSocial. Tabela em [Categoria do Trabalhador](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/categoria-trabalhador.md).                                                                                                                                                                                                                                                                                                              |
| **`terminationReason`**                            | Motivo de desligamento do vínculo. Tabela em [Motivo de Desligamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-desligamento.md).                                                                                                                                                                                                                                                                                                                    |
| **`ineligibilityReason` / `ineligibilityReasons`** | Motivo de inelegibilidade Dataprev. Tabela em [Motivo de Inelegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-inelegibilidade.md).                                                                                                                                                                                                                                                                                                             |
| **`politicallyExposedPerson`**                     | Indicador PEP. Tabela em [Pessoa Exposta Politicamente](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/pessoa-exposta-politicamente.md).                                                                                                                                                                                                                                                                                                                         |
| **tipo de contrato (`contractType`)**              | Tipo do empréstimo legado: `NON_PAYROLL_UNSECURED` (não consignado sem garantia) ou `PAYROLL_DEDUCTED` (com desconto em folha). Descrição em pt-BR em `contractTypeDescription`.                                                                                                                                                                                                                                                                                                   |

***

## Elegibilidade

Detalhes em [Elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md).

| Termo             | Definição                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **elegibilidade** | Regras que definem se o trabalhador pode contratar (idade, tempo de vínculo, margem, PEP, contratos ativos etc.). Configuráveis **por originador**; por padrão, todas habilitadas. Por configuração comercial, o originador pode ter todas as regras dispensadas, ou só as de limites do empréstimo (valor, parcela, prazo e taxa). |

***

## Crédito (simulação, proposta e contrato)

| Termo              | Definição                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **simulação**      | Cálculo de parcelas, juros, IOF e CET para valor e prazo desejados, antes da proposta. Verifica as regras de elegibilidade. `POST /employees/{publicId}/simulations`.    |
| **CET**            | Custo Efetivo Total: taxa que consolida juros e encargos, calculada na simulação.                                                                                        |
| **IOF**            | Imposto sobre Operações Financeiras, calculado na simulação.                                                                                                             |
| **proposta**       | Gerada a partir da simulação escolhida. `POST /employees/{publicId}/proposals`.                                                                                          |
| **contrato / CCB** | Cédula de Crédito Bancário, o instrumento do empréstimo, criado a partir da proposta com dados de desembolso e endereço. `POST /proposals/{proposalPublicId}/contracts`. |
| **formalização**   | Processamento da CCB após a averbação, conforme a `formalizationStrategy`: desembolso (`GTBANKER`) ou conclusão pelo originador (`ORIGINATOR_MANAGED`).                  |

***

## Pós-contrato

| Termo                                         | Definição                                                                                                                                                                                                         |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **averbação (endorsement)**                   | Registro da consignação na Dataprev, que reserva a parcela na margem. Vem depois da assinatura e antes do desembolso (`ENDORSED`).                                                                                |
| **desaverbação (exclusion / de-endorsement)** | Desfaz a averbação de contrato **não** pago: exclui a consignação, **cancela o contrato** e **devolve a margem**. Ver [Desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md). |
| **desembolso**                                | Pagamento do empréstimo ao trabalhador, última etapa com formalização `GTBANKER`.                                                                                                                                 |

***

## Dataprev — desambiguando as três áreas

A Dataprev aparece em três áreas da API, em momentos diferentes:

| Área                                                 | O que é                                                                                                                                     | Quando                           | Página                                                                                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **1. Autorização**                                   | **Consentimento** do trabalhador. Pré-requisito de tudo                                                                                     | **Antes** da originação          | [Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md)                                    |
| **2. Consultas Dataprev (sob demanda)**              | Listar **todos** os vínculos autorizados (inclusive inelegíveis) e consultar a **margem de um vínculo** (`bondPublicId`, `forceIneligible`) | **Depois** da autorização        | [Consultas Dataprev (sob demanda)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md) |
| **3. Escriturações e Transferências (pós-contrato)** | **Transferências de pagamento** e **lançamentos contábeis** (débito/crédito) processados pela Dataprev para os seus contratos               | **Depois** que o contrato existe | [Escriturações e Transferências](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes.md)   |

***

## Integração

| Termo                                | Definição                                                                                                                                                                                                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Idempotency-Key`**                | Header opcional (máx. 255) que faz o reenvio da mesma requisição devolver a resposta original em vez de processar de novo. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md).                                                          |
| **`requestId`**                      | Identificador de requisição assíncrona (ex.: consultas Dataprev sob demanda), retornado no `202` do `POST` e usado no `GET` do resultado.                                                                                                                                           |
| **webhook**                          | Notificação HTTP ao originador quando um evento acontece (ex.: `AUTHORIZATION_COMPLETED`, `MARGIN_QUERY_COMPLETED`). Payloads em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).                                         |
| **término de vínculo (situação 15)** | Com o fim do vínculo, a Dataprev encerra o empréstimo na situação 15: a dívida continua, o desconto em folha deixa de existir. Ver [Migração Automática por Término de Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/migracao-automatica-termino-vinculo.md). |
| **migração automática**              | A Dataprev move sozinha o contrato da situação 15 para o vínculo novo ativo do trabalhador. Mesmo contrato e mesmo `dataprevContractNumber`. Webhook `CONTRACT_MIGRATED_AUTOMATICALLY`.                                                                                             |
| **ajuste de parcelas**               | Alteração opcional do número e do valor das parcelas vincendas de contrato na situação 15, antes da migração (`POST /api/v1/originator/terminated-loan-alterations`). A parcela não pode subir.                                                                                     |

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