> 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/webhooks/eventos-e-payloads.md).

# Eventos e Payloads

## Formato do body

Toda notificação chega no mesmo envelope:

```json
{
  "source": "CONTRACT",
  "eventType": "ENDORSEMENT_ENDORSED",
  "data": { ... }
}
```

* **source** — origem do evento (`EMPLOYEE`, `CONTRACT`, `GTBANKER`, `AUTHORIZATION_DOCUMENT`, `DATAPREV_SUSPENSION_WINDOW`, `AUCTION`, `TERMINATED_LOAN_NEW_BOND`)
* **eventType** — tipo do evento
* **data** — payload do evento. As tabelas abaixo descrevem só o `data`.

{% hint style="info" %}
Alguns eventos trazem também **`sourceId`** no envelope, com o identificador da entidade de origem — útil para correlação e idempotência. Trate como opcional: só conte com ele nos eventos cuja seção diz o que ele contém.
{% endhint %}

***

## Eventos disponíveis

### Margem

| Evento                   | Source     | Descrição                                                       |
| ------------------------ | ---------- | --------------------------------------------------------------- |
| `MARGIN_QUERY_COMPLETED` | `EMPLOYEE` | Consulta de margem concluída, com a margem completa no payload. |
| `MARGIN_QUERY_FAILED`    | `EMPLOYEE` | Consulta de margem encerrada sem sucesso e sem nova tentativa.  |

### Vínculos autorizados (Dataprev)

| Evento                            | Source     | Descrição                                                           |
| --------------------------------- | ---------- | ------------------------------------------------------------------- |
| `AUTHORIZED_BONDS_LISTED`         | `EMPLOYEE` | Listagem de vínculos autorizados concluída, com a lista no payload. |
| `AUTHORIZED_BONDS_LISTING_FAILED` | `EMPLOYEE` | Listagem de vínculos autorizados encerrada sem sucesso.             |

### FGTS disponível (Dataprev)

| Evento                              | Source     | Descrição                                                               |
| ----------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `FGTS_AVAILABILITY_QUERY_COMPLETED` | `EMPLOYEE` | Consulta de FGTS disponível concluída.                                  |
| `FGTS_AVAILABILITY_QUERY_FAILED`    | `EMPLOYEE` | Consulta de FGTS disponível encerrada sem sucesso e sem nova tentativa. |

### Leilão de Propostas

| Evento                            | Source    | Descrição                                                   |
| --------------------------------- | --------- | ----------------------------------------------------------- |
| `AUCTION_OFFER_ACCEPTED`          | `AUCTION` | Trabalhador aceitou uma das suas ofertas de leilão.         |
| `AUCTION_SOLICITATIONS_REFRESHED` | `AUCTION` | Solicitações de proposta recém-recebidas mudaram de estado. |

### Autorização Dataprev

| Evento                         | Source                   | Descrição                                                                  |
| ------------------------------ | ------------------------ | -------------------------------------------------------------------------- |
| `AUTHORIZATION_COMPLETED`      | `EMPLOYEE`               | Autorização Dataprev concluída.                                            |
| `AUTHORIZATION_EXPIRED`        | `EMPLOYEE`               | Autorização Dataprev perdeu a validade; o colaborador precisa reautorizar. |
| `AUTHORIZATION_FAILED`         | `EMPLOYEE`               | Autorização Dataprev encerrada sem sucesso e sem nova tentativa.           |
| `AUTHORIZATION_DOCUMENT_READY` | `AUTHORIZATION_DOCUMENT` | PDF do termo de autorização gerado pela plataforma.                        |
| `AUTHORIZATION_SIGN_URL_READY` | `AUTHORIZATION_DOCUMENT` | **Descontinuado.** Link de assinatura do termo de autorização pronto.      |
| `AUTHORIZATION_SIGNED`         | `AUTHORIZATION_DOCUMENT` | Termo de autorização assinado.                                             |

### Averbação

| Evento                   | Source     | Descrição                       |
| ------------------------ | ---------- | ------------------------------- |
| `ENDORSEMENT_ENDORSED`   | `CONTRACT` | Contrato averbado com sucesso   |
| `ENDORSEMENT_FAILED`     | `CONTRACT` | Averbação encerrada sem sucesso |
| `ENDORSEMENT_RETRYING`   | `CONTRACT` | Averbação em nova tentativa     |
| `ENDORSEMENT_PROCESSING` | `CONTRACT` | Averbação em processamento      |
| `ENDORSEMENT_PENDING`    | `CONTRACT` | Averbação pendente              |

### Desaverbação (de-endorsement)

| Evento                         | Source     | Descrição                                                 |
| ------------------------------ | ---------- | --------------------------------------------------------- |
| `ENDORSEMENT_EXCLUDING`        | `CONTRACT` | Desaverbação aceita e em processamento                    |
| `ENDORSEMENT_EXCLUDED`         | `CONTRACT` | Desaverbação confirmada — contrato cancelado              |
| `ENDORSEMENT_EXCLUSION_FAILED` | `CONTRACT` | Desaverbação não concluída — o contrato continua averbado |

Fluxo completo no guia [Desaverbação (de-endorsement)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md).

### Pagamento (GTBanker)

| Evento             | Source     | Descrição                                                     |
| ------------------ | ---------- | ------------------------------------------------------------- |
| `PAYMENT_SUCCESS`  | `GTBANKER` | Desembolso realizado com sucesso                              |
| `PAYMENT_REVISION` | `GTBANKER` | Desembolso aguardando nova conta ou retentativa do originador |
| `PAYMENT_FAILURE`  | `GTBANKER` | Falha no desembolso que depende da Giro                       |
| `CCB_RECEIVED`     | `GTBANKER` | CCB (Cédula de Crédito Bancário) recebida                     |

{% hint style="success" %}
**Correlacione pelo `contract_public_id`.** Todo evento de source `GTBANKER` traz, na raiz do `data`, o `contract_public_id`: o `publicId` do contrato na Giro, acrescentado por nós. O `numero_ccb` dentro de `dados` vem do GTBanker como ele mandou e pode chegar **sem os zeros à esquerda** (`"2"` para o contrato `00000002`).
{% endhint %}

### Assinatura

| Evento                  | Source     | Descrição                                 |
| ----------------------- | ---------- | ----------------------------------------- |
| `SIGNATURE_LINK_RESEND` | `CONTRACT` | Link de assinatura do contrato reenviado. |

### Contrato (documento)

| Evento                               | Source                   | Descrição                                                            |
| ------------------------------------ | ------------------------ | -------------------------------------------------------------------- |
| `CONTRACT_DOCUMENT_READY`            | `CONTRACT`               | PDF do contrato pronto.                                              |
| `CONTRACT_SIGNED`                    | `CONTRACT`               | Contrato assinado.                                                   |
| `CONTRACT_DOCUMENT_FAILED`           | `CONTRACT`               | Geração do PDF do contrato encerrada sem sucesso.                    |
| `CONTRACT_REGISTRATION_FAILED`       | `CONTRACT`               | Registro do contrato encerrado sem sucesso; não haverá averbação.    |
| `CONTRACT_SIGNING_FAILED`            | `CONTRACT`               | Assinatura do contrato encerrada sem sucesso.                        |
| `CONTRACT_FORMALIZATION_FAILED`      | `CONTRACT`               | Formalização do contrato encerrada sem sucesso.                      |
| `CONTRACT_PAYMENT_APPROVAL_REQUIRED` | `CONTRACT`               | Contrato averbado aguardando a sua aprovação de pagamento.           |
| `AUTHORIZATION_DOCUMENT_FAILED`      | `AUTHORIZATION_DOCUMENT` | Geração ou assinatura do termo de autorização encerrada sem sucesso. |

### Janela de suspensão Dataprev (virada de competência)

| Evento                   | Source                       | Descrição                                  |
| ------------------------ | ---------------------------- | ------------------------------------------ |
| `DATAPREV_WINDOW_OPENED` | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev aberta.    |
| `DATAPREV_WINDOW_CLOSED` | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev encerrada. |

### Novos vínculos (empréstimo encerrado)

| Evento                              | Source                     | Descrição                                                                    |
| ----------------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
| `CONTRACT_TERMINATED_BOND`          | `CONTRACT`                 | A Dataprev encerrou um empréstimo por término do vínculo empregatício.       |
| `TERMINATED_LOAN_NEW_BOND`          | `TERMINATED_LOAN_NEW_BOND` | Novo vínculo encontrado para um empréstimo encerrado por término de vínculo. |
| `GUARANTEE_EXECUTED`                | `CONTRACT`                 | A Dataprev aceitou a execução da garantia FGTS.                              |
| `CONTRACT_MIGRATED_AUTOMATICALLY`   | `CONTRACT`                 | A Dataprev migrou um contrato encerrado para um vínculo novo.                |
| `TERMINATED_LOAN_ALTERED`           | `CONTRACT`                 | A Dataprev aceitou a alteração de parcelas de um empréstimo encerrado.       |
| `TERMINATED_LOAN_ALTERATION_FAILED` | `CONTRACT`                 | A Dataprev recusou a alteração.                                              |

***

## Payloads por evento

### MARGIN\_QUERY\_COMPLETED

Disparado quando a consulta de margem termina. O payload já traz a margem completa, com a mesma estrutura do [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) — inclusive os [alertas (`alerts`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#alertas-do-trabalhador-alerts) e os [empréstimos legados (`legacyLoans`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#emprestimos-legados-legacyloans) —, então não é preciso chamar o `GET` depois.

| Campo                     | Tipo                       | Descrição                                                                                                                                                                                                                                         |
| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpf`                     | `string`                   | CPF do colaborador.                                                                                                                                                                                                                               |
| `publicId`                | `string`                   | `publicId` do empregado (16 caracteres).                                                                                                                                                                                                          |
| `status`                  | `string`                   | Status da consulta (`MARGIN_UPDATED` quando concluída).                                                                                                                                                                                           |
| `requestId`               | `string` (nullable)        | Identificador da requisição — preenchido apenas na [consulta de margem por vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md); `null` na consulta automática. |
| `bondPublicId`            | `string (uuid)` (nullable) | Vínculo consultado — preenchido apenas na consulta por vínculo; `null` na consulta automática.                                                                                                                                                    |
| `employmentRelationships` | `array` (nullable)         | Um ou mais vínculos ativos com margem vigente, na estrutura do `GET /margin`.                                                                                                                                                                     |

```json
{
  "source": "EMPLOYEE",
  "eventType": "MARGIN_QUERY_COMPLETED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "MARGIN_UPDATED",
    "requestId": null,
    "employmentRelationships": [
      {
        "registrationNumber": "12345678901",
        "employerTaxId": "12345678000199",
        "employerName": "Empresa Exemplo Ltda",
        "status": "ACTIVE",
        "availableMargin": 1697.76,
        "usableMargin": 1697.76,
        "isEligible": true,
        "alerts": [
          {
            "alertType": "SUSPENSION",
            "alertTypeDescription": "Afastamento",
            "referenceDate": "2024-03-01",
            "eventId": 7,
            "suspensionReasonCode": 1,
            "suspensionReasonDescription": "Acidente/doença do trabalho",
            "suspensionStartDate": "2024-03-01",
            "suspensionEndDate": "2024-04-01",
            "terminationReasonCode": null,
            "terminationReasonDescription": null,
            "terminationDate": null,
            "priorNoticeDate": null,
            "priorNoticeEndDate": null
          }
        ],
        "legacyLoans": [
          {
            "financialInstitutionCode": 341,
            "contractNumber": "CONTRATO-123",
            "contractType": "PAYROLL_DEDUCTED",
            "contractTypeDescription": "Empréstimo com descontos em folha de pagamento",
            "contractStartDate": "2024-03-01",
            "contractEndDate": "2026-03-01",
            "totalInstallments": 24,
            "paidInstallments": 6,
            "installmentAmount": 150.00,
            "loanAmount": 3000.00,
            "disbursedAmount": 2800.00,
            "outstandingBalance": 2400.00,
            "monthlyInterestRate": 1.99,
            "monthlyCet": 2.15,
            "sourceUpdatedAt": "2024-03-01T10:15:30"
          }
        ]
      }
    ]
  }
}
```

***

### MARGIN\_QUERY\_FAILED

Disparado quando a consulta de margem termina sem sucesso e não haverá nova tentativa. Revise o cadastro do colaborador antes de consultar de novo.

| Campo          | Tipo                       | Descrição                                                          |
| -------------- | -------------------------- | ------------------------------------------------------------------ |
| `cpf`          | `string`                   | CPF do colaborador.                                                |
| `publicId`     | `string`                   | `publicId` do empregado (16 caracteres).                           |
| `status`       | `string`                   | Sempre `FAILED`.                                                   |
| `errorCode`    | `string`                   | Mesmos valores de [`AUTHORIZATION_FAILED`](#authorization_failed). |
| `reason`       | `string` (nullable)        | Descrição legível do erro.                                         |
| `requestId`    | `string` (nullable)        | Preenchido apenas na consulta por vínculo.                         |
| `bondPublicId` | `string (uuid)` (nullable) | Preenchido apenas na consulta por vínculo.                         |

```json
{
  "source": "EMPLOYEE",
  "eventType": "MARGIN_QUERY_FAILED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "FAILED",
    "errorCode": "CPF_NOT_FOUND_OR_INELIGIBLE",
    "reason": "CPF não encontrado na base ou CPF do trabalhador inelegível",
    "requestId": null
  }
}
```

***

### AUTHORIZED\_BONDS\_LISTED / AUTHORIZED\_BONDS\_LISTING\_FAILED

Resultado de [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md).

* **`AUTHORIZED_BONDS_LISTED`** — listagem concluída. A lista vem no payload; o mesmo resultado está em `GET /api/v1/originator/authorized-bonds-queries/{requestId}`.
* **`AUTHORIZED_BONDS_LISTING_FAILED`** — listagem encerrada sem sucesso. Revise o cadastro do colaborador antes de tentar de novo.

| Campo       | Tipo      | Descrição                                                                                                                                                                                                  |
| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpf`       | `string`  | CPF do empregado.                                                                                                                                                                                          |
| `publicId`  | `string`  | `publicId` do empregado (16 caracteres).                                                                                                                                                                   |
| `requestId` | `string`  | Identificador da requisição. UUID de 36 caracteres; requisições antigas usam um id de 16 caracteres — não valide tamanho fixo.                                                                             |
| `status`    | `string`  | `COMPLETED` ou `FAILED`.                                                                                                                                                                                   |
| `bondCount` | `integer` | Quantidade de lastros autorizados. Só no sucesso.                                                                                                                                                          |
| `bonds`     | `array`   | Lastros, na estrutura do `GET` de listagem: `bondPublicId`, `registrationNumber`, `employerTaxId`, `employerTaxIdType`, `eligible`, `ineligibilityReason` e `fgtsAvailability` (ou `null`). Só no sucesso. |
| `errorCode` | `string`  | Código do erro. Só na falha; `null` no sucesso.                                                                                                                                                            |
| `reason`    | `string`  | Descrição legível do erro. Só na falha; `null` no sucesso.                                                                                                                                                 |

```json
{
  "source": "EMPLOYEE",
  "eventType": "AUTHORIZED_BONDS_LISTED",
  "data": {
    "cpf": "12345678901",
    "publicId": "abcd1234efgh5678",
    "requestId": "0198f2f7-ad35-7048-be6b-9d2f4a7c5b3a",
    "status": "COMPLETED",
    "bondCount": 1,
    "bonds": [
      {
        "bondPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b04",
        "registrationNumber": "00012345",
        "employerTaxId": "33060350000100",
        "employerTaxIdType": "CNPJ",
        "eligible": true,
        "ineligibilityReason": null,
        "fgtsAvailability": {
          "availableBalance": 1234.56,
          "severanceFine": 789.00,
          "referenceAt": "2026-06-12T09:30:15"
        }
      }
    ],
    "errorCode": null,
    "reason": null
  }
}
```

***

### FGTS\_AVAILABILITY\_QUERY\_COMPLETED / FGTS\_AVAILABILITY\_QUERY\_FAILED

Resultado de [Consultar FGTS Disponível](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md).

* **`FGTS_AVAILABILITY_QUERY_COMPLETED`** — consulta concluída. O mesmo resultado está em `GET /api/v1/originator/fgts-availability-queries/{requestId}`.
* **`FGTS_AVAILABILITY_QUERY_FAILED`** — consulta encerrada sem sucesso e sem nova tentativa.

| Campo                            | Tipo                 | Descrição                                                                                                                                   |
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpf`                            | `string`             | CPF do empregado.                                                                                                                           |
| `publicId`                       | `string`             | `publicId` do empregado (16 caracteres).                                                                                                    |
| `status`                         | `string`             | `COMPLETED` ou `FAILED`.                                                                                                                    |
| `requestId`                      | `string`             | Identificador da requisição. UUID de 36 caracteres; requisições antigas usam um id de 16 caracteres — não valide tamanho fixo.              |
| `bondPublicId`                   | `string (uuid)`      | Lastro de origem, quando a consulta foi feita por lastro; `null` caso contrário.                                                            |
| `employmentRelationshipPublicId` | `string (uuid)`      | Vínculo de origem, quando a consulta foi feita por vínculo; `null` caso contrário.                                                          |
| `availableBalance`               | `number`             | Saldo de FGTS disponível como garantia. Só no sucesso.                                                                                      |
| `severanceFine`                  | `number`             | Multa rescisória disponível. Só no sucesso.                                                                                                 |
| `referenceAt`                    | `string` (date-time) | Data/hora da consulta na Dataprev. Só no sucesso.                                                                                           |
| `errorCode`                      | `string`             | Sigla do erro Dataprev (ex. `CB`), `RETRY_EXHAUSTED` ou `PROVIDER_ERROR` (a Dataprev rejeitou a consulta sem informar código). Só na falha. |
| `reason`                         | `string`             | Descrição legível do erro. Só na falha.                                                                                                     |

```json
{
  "source": "EMPLOYEE",
  "eventType": "FGTS_AVAILABILITY_QUERY_COMPLETED",
  "data": {
    "cpf": "12345678901",
    "publicId": "abcd1234efgh5678",
    "status": "COMPLETED",
    "requestId": "0198f308-be46-7159-cf7c-ae3f5b8d6c4b",
    "bondPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b04",
    "employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
    "availableBalance": 1234.56,
    "severanceFine": 789.00,
    "referenceAt": "2026-06-12T09:30:15"
  }
}
```

***

### AUTHORIZATION\_COMPLETED

Disparado quando a autorização Dataprev é concluída. Status também em [Consultar Status de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md).

| Campo            | Tipo                           | Descrição                                |
| ---------------- | ------------------------------ | ---------------------------------------- |
| `cpf`            | `string`                       | CPF do colaborador.                      |
| `publicId`       | `string`                       | `publicId` do empregado (16 caracteres). |
| `status`         | `string`                       | `AUTHORIZED`.                            |
| `termExpiresAt`  | `string` (date-time, nullable) | Expiração do termo de autorização.       |
| `tokenExpiresAt` | `string` (date-time, nullable) | Expiração do token Dataprev.             |

```json
{
  "source": "EMPLOYEE",
  "eventType": "AUTHORIZATION_COMPLETED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "AUTHORIZED",
    "termExpiresAt": "2027-06-18T10:30:00Z",
    "tokenExpiresAt": "2026-12-18T10:30:00Z"
  }
}
```

***

### AUTHORIZATION\_EXPIRED

Disparado quando a Dataprev deixa de aceitar a autorização do colaborador. Reinicie o fluxo de autorização para ele. Mesmos campos de [`AUTHORIZATION_COMPLETED`](#authorization_completed), com `status` = `EXPIRED` e `tokenExpiresAt` = `null`.

```json
{
  "source": "EMPLOYEE",
  "eventType": "AUTHORIZATION_EXPIRED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "EXPIRED",
    "termExpiresAt": "2027-06-18T10:30:00Z",
    "tokenExpiresAt": null
  }
}
```

***

### AUTHORIZATION\_FAILED

Disparado quando a autorização termina sem sucesso e não haverá nova tentativa. Erros transitórios não disparam o evento. Revise o cadastro do colaborador (CPF, vínculo, matrícula) antes de iniciar novo fluxo.

| Campo       | Tipo                | Descrição                                |
| ----------- | ------------------- | ---------------------------------------- |
| `cpf`       | `string`            | CPF do colaborador.                      |
| `publicId`  | `string`            | `publicId` do empregado (16 caracteres). |
| `status`    | `string`            | Sempre `INELIGIBLE`.                     |
| `errorCode` | `string`            | Código estável do erro (tabela abaixo).  |
| `reason`    | `string` (nullable) | Descrição legível do erro.               |

| `errorCode`                          | Origem Dataprev | Significado                                                                                                                                                    |
| ------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CPF_NOT_FOUND_OR_INELIGIBLE`        | `CB`            | CPF não encontrado na base ou trabalhador inelegível                                                                                                           |
| `EMPLOYMENT_RELATIONSHIP_INELIGIBLE` | `HU`            | Vínculo inelegível para empréstimo                                                                                                                             |
| `WORKER_NOT_FOUND`                   | `TA`            | Trabalhador inexistente                                                                                                                                        |
| `RETRY_EXHAUSTED`                    | —               | Retentativas esgotadas em falhas transitórias                                                                                                                  |
| `NEEDS_VERIFICATION_TIMEOUT`         | —               | A Dataprev não confirmou nem descartou a operação e a verificação não fechou no prazo. O efeito é desconhecido: a plataforma não reenvia sozinha               |
| `ADMIN_FAIL`                         | —               | Um operador da plataforma encerrou a operação como falha após verificação manual. O efeito na Dataprev pode ser desconhecido; a plataforma não reenvia sozinha |
| `UNKNOWN_DATAPREV_ERROR`             | (outros)        | Erro permanente da Dataprev fora dos códigos acima                                                                                                             |

```json
{
  "source": "EMPLOYEE",
  "eventType": "AUTHORIZATION_FAILED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "status": "INELIGIBLE",
    "errorCode": "CPF_NOT_FOUND_OR_INELIGIBLE",
    "reason": "CPF não encontrado na base ou CPF do trabalhador inelegível"
  }
}
```

***

### AUTHORIZATION\_DOCUMENT\_READY

Disparado quando o PDF do termo de autorização gerado pela plataforma fica disponível. Colete a assinatura e envie o termo por [Upload do Documento Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/upload-documento-assinado.md). Nova URL de download em [Obter Documento de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/baixar-documento-autorizacao.md).

| Campo         | Tipo     | Descrição                                                    |
| ------------- | -------- | ------------------------------------------------------------ |
| `cpf`         | `string` | CPF do colaborador.                                          |
| `publicId`    | `string` | `publicId` do empregado (16 caracteres).                     |
| `nsu`         | `string` | NSU do documento de autorização.                             |
| `documentUrl` | `string` | URL temporária para download do PDF.                         |
| `status`      | `string` | Status do documento (ex.: `PENDING_SIGNATURE`, `GENERATED`). |

```json
{
  "source": "AUTHORIZATION_DOCUMENT",
  "eventType": "AUTHORIZATION_DOCUMENT_READY",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "nsu": "777481165341001801",
    "documentUrl": "https://files.example.com/authorizations/777481165341001801.pdf",
    "status": "PENDING_SIGNATURE"
  }
}
```

***

### AUTHORIZATION\_SIGN\_URL\_READY

{% hint style="warning" %}
**Descontinuado.** Não é emitido nos fluxos atuais, em que a assinatura do termo é sempre coletada pelo originador — ver [Termo em PDF](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf.md) e [Termo em Trilha Opt-In](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in.md). Mantido como referência para integrações legadas.
{% endhint %}

Disparado quando o link de assinatura do termo de autorização ficava pronto.

| Campo               | Tipo                 | Descrição                                |
| ------------------- | -------------------- | ---------------------------------------- |
| `cpf`               | `string`             | CPF do empregado.                        |
| `publicId`          | `string`             | `publicId` do empregado (16 caracteres). |
| `nsu`               | `string`             | NSU do documento de autorização.         |
| `signUrl`           | `string`             | Link de assinatura, de uso único.        |
| `signatureProvider` | `string`             | Provedor de assinatura (`INTERNAL`).     |
| `signatureMode`     | `string`             | Modo de assinatura (`LINK` ou `JWT`).    |
| `expiresAt`         | `string` (date-time) | Expiração do link.                       |

```json
{
  "source": "AUTHORIZATION_DOCUMENT",
  "eventType": "AUTHORIZATION_SIGN_URL_READY",
  "data": {
    "cpf": "12345678901",
    "publicId": "abcd1234efgh5678",
    "nsu": "777481165341001801",
    "signUrl": "https://employee.giro.tech/sign/eyJhbGciOiJIUzUxMi...",
    "signatureProvider": "INTERNAL",
    "signatureMode": "LINK",
    "expiresAt": "2026-04-30T13:00:00Z"
  }
}
```

***

### ENDORSEMENT\_\* (Averbação)

Disparados a cada mudança de estado da averbação na Dataprev. Contrato consultável em [Buscar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md).

| Campo            | Tipo                | Descrição                                                                                                                                                                                                                                           |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber` | `string`            | Número do contrato (CCB).                                                                                                                                                                                                                           |
| `status`         | `string`            | `ENDORSED`, `FAILED`, `RETRYING`, `PROCESSING` ou `PENDING`.                                                                                                                                                                                        |
| `protocol`       | `string` (nullable) | Protocolo da averbação na Dataprev.                                                                                                                                                                                                                 |
| `failureReason`  | `string` (nullable) | Motivo da falha em `ENDORSEMENT_FAILED`; `null` nos demais.                                                                                                                                                                                         |
| `errorCode`      | `string` (nullable) | Código de erro da Dataprev em `ENDORSEMENT_FAILED`; `null` nos demais. `NEEDS_VERIFICATION_TIMEOUT` ou `ADMIN_FAIL` indicam que o efeito da averbação na Dataprev é desconhecido (não confirmado nem descartado); a plataforma não reenvia sozinha. |

```json
{
  "source": "CONTRACT",
  "eventType": "ENDORSEMENT_ENDORSED",
  "data": {
    "contractNumber": "00345678",
    "status": "ENDORSED",
    "protocol": "20260226143000",
    "failureReason": null,
    "errorCode": null
  }
}
```

```json
{
  "source": "CONTRACT",
  "eventType": "ENDORSEMENT_FAILED",
  "data": {
    "contractNumber": "00345678",
    "status": "FAILED",
    "protocol": "20260226143000",
    "failureReason": "Averbação recusada pela Dataprev",
    "errorCode": "HU"
  }
}
```

***

### ENDORSEMENT\_EXCLUDING / ENDORSEMENT\_EXCLUDED / ENDORSEMENT\_EXCLUSION\_FAILED (Desaverbação)

Eventos da [Desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md). Mesmos campos dos eventos de averbação acima:

* **`ENDORSEMENT_EXCLUDING`** — `status` = `EXCLUDING`: desaverbação aceita e em processamento.
* **`ENDORSEMENT_EXCLUDED`** — `status` = `EXCLUDED`: contrato cancelado (`CANCELLED`) e margem restaurada.
* **`ENDORSEMENT_EXCLUSION_FAILED`** — `status` = `ENDORSED`: a desaverbação não foi concluída e o contrato continua averbado. Você pode pedir de novo.

`failureReason` traz a origem da desaverbação ou o motivo da falha; `errorCode` vem `null`.

```json
{
  "source": "CONTRACT",
  "eventType": "ENDORSEMENT_EXCLUDED",
  "data": {
    "contractNumber": "00345678",
    "status": "EXCLUDED",
    "protocol": "20260226143000",
    "failureReason": "Desaverbação solicitada pelo originador",
    "errorCode": null
  }
}
```

```json
{
  "source": "CONTRACT",
  "eventType": "ENDORSEMENT_EXCLUSION_FAILED",
  "data": {
    "contractNumber": "00345678",
    "status": "ENDORSED",
    "protocol": "20260226143000",
    "failureReason": "Desaverbação falhou após múltiplas tentativas",
    "errorCode": null
  }
}
```

***

### CONTRACT\_PAYMENT\_APPROVAL\_REQUIRED

Disparado quando um contrato averbado entra em `PENDING_PAYMENT_APPROVAL`. Só para originadores com aprovação de pagamento habilitada e formalização pelo GTBanker. Aprove com `POST /api/v1/originator/contracts/{contractNumber}/payment-approval`: o contrato volta a `ENDORSED` e segue para a formalização. O `ENDORSEMENT_ENDORSED` continua sendo enviado. Ver [Aprovação de Pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/aprovacao-de-pagamento.md).

| Campo            | Tipo     | Descrição                          |
| ---------------- | -------- | ---------------------------------- |
| `requestNumber`  | `string` | Número da requisição do contrato.  |
| `contractNumber` | `string` | Número do contrato (CCB).          |
| `status`         | `string` | Sempre `PENDING_PAYMENT_APPROVAL`. |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_PAYMENT_APPROVAL_REQUIRED",
  "data": {
    "requestNumber": "GTAB12CD34EF",
    "contractNumber": "00345678",
    "status": "PENDING_PAYMENT_APPROVAL"
  }
}
```

***

### PAYMENT\_SUCCESS

Disparado quando o desembolso é realizado. O contrato passa a `COMPLETED`.

Nos eventos de source `GTBANKER`, o `data` é o payload do GTBanker:

| Campo                        | Tipo                  | Obrigatório   | Descrição                                              |
| ---------------------------- | --------------------- | ------------- | ------------------------------------------------------ |
| `versao`                     | string                | Sim           | Versão do payload, ex: `"1.0"`                         |
| `evento`                     | string                | Sim           | Sempre `SUCESSO_DESEMBOLSO`                            |
| `id_evento`                  | string (UUID)         | Sim           | Identificador único do evento                          |
| `data_evento`                | string (datetime UTC) | Sim           | Timestamp do evento                                    |
| `contract_public_id`         | string (UUID)         | Sim           | `publicId` do contrato na Giro. Acrescentado pela Giro |
| `dados.valor_desembolso`     | number                | Sim           | Valor total desembolsado (0–999999999.99)              |
| `dados.id_transacao`         | integer (int64)       | Sim           | ID único da transferência                              |
| `dados.data_pagamento`       | string (date)         | Sim           | Data em que o pagamento foi executado                  |
| `dados.status`               | string                | Sim           | Sempre `CONFIRMADO`                                    |
| `dados.favorecido.documento` | string                | Sim           | CPF (11 dígitos) ou CNPJ (14 dígitos) do favorecido    |
| `dados.conta_bancaria`       | objeto                | Condicional\* | Conta bancária de destino                              |
| `dados.pix`                  | objeto                | Condicional\* | Chave PIX de destino                                   |
| `dados.ccbs[]`               | array                 | Sim           | CCBs do desembolso                                     |

\*Vem `conta_bancaria` ou `pix`, nunca os dois.

**`dados.conta_bancaria`:**

| Campo                  | Tipo            | Obrigatório | Descrição                    |
| ---------------------- | --------------- | ----------- | ---------------------------- |
| `codigo_banco`         | string (max 14) | Sim         | Código do banco              |
| `numero_conta`         | string (max 20) | Sim         | Número da conta              |
| `digito_conta`         | string (max 2)  | Não         | Dígito verificador da conta  |
| `numero_agencia`       | string (max 4)  | Sim         | Número da agência            |
| `tipo`                 | string          | Sim         | `CORRENTE` ou `POUPANCA`     |
| `documento_favorecido` | string (max 14) | Não         | CPF/CNPJ do titular da conta |

**`dados.pix`:**

| Campo            | Tipo             | Obrigatório | Descrição                                |
| ---------------- | ---------------- | ----------- | ---------------------------------------- |
| `chave_pix`      | string (max 255) | Sim         | Valor da chave PIX                       |
| `tipo_chave_pix` | string           | Sim         | `EMAIL`, `CPF`, `CNPJ`, `PHONE` ou `EVP` |

**`dados.ccbs[]` (cada item):**

| Campo               | Tipo   | Descrição                        |
| ------------------- | ------ | -------------------------------- |
| `origem`            | string | Identificador do originador      |
| `numero_ccb`        | string | Número da CCB                    |
| `documento_tomador` | string | CPF/CNPJ do tomador              |
| `valor_desembolso`  | number | Valor desembolsado para esta CCB |

```json
{
  "source": "GTBANKER",
  "eventType": "PAYMENT_SUCCESS",
  "data": {
    "versao": "1.0",
    "evento": "SUCESSO_DESEMBOLSO",
    "id_evento": "a9fabe92-4b07-43c4-ba1c-d5d4873d6a28",
    "data_evento": "2024-04-25T10:30:00Z",
    "dados": {
      "valor_desembolso": 15000,
      "id_transacao": 987654321,
      "data_pagamento": "2024-04-25",
      "status": "CONFIRMADO",
      "favorecido": { "documento": "12345678901" },
      "pix": {
        "chave_pix": "usuario@exemplo.com",
        "tipo_chave_pix": "EMAIL"
      },
      "ccbs": [
        {
          "origem": "PARCEIRO_XYZ",
          "numero_ccb": "12345678",
          "documento_tomador": "12345678901",
          "valor_desembolso": 15000
        }
      ]
    },
    "contract_public_id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
  }
}
```

***

### PAYMENT\_REVISION

Disparado quando o desembolso falha por dado bancário inconsistente ou instabilidade com o banco. O GTBanker emite um ticket com prazo para você enviar a conta de novo por [Atualizar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md).

O contrato **continua em `FORMALIZED`**. Até o desembolso sair, o `rejectionReason` do contrato traz `Revisão de conta de desembolso necessária - Ticket: <ticket>`. Contrato em `COMPLETED` ou `CANCELLED` ignora o evento.

{% hint style="success" %}
**Integre pelo bloco `disbursementReview`.** Ele é acrescentado pela Giro e é estável. O bloco `dados` é repassado do GTBanker como veio e pode mudar sem aviso.
{% endhint %}

| Campo                                              | Tipo                  | Obrigatório   | Descrição                                                                  |
| -------------------------------------------------- | --------------------- | ------------- | -------------------------------------------------------------------------- |
| `disbursementReview.ticket`                        | string                | Sim           | Ticket para reenviar a conta                                               |
| `disbursementReview.createdAt`                     | string (datetime UTC) | Sim           | Criação do ticket                                                          |
| `disbursementReview.expiresAt`                     | string (datetime UTC) | Sim           | Expiração do ticket                                                        |
| `disbursementReview.availableActions`              | array de string       | Sim           | `NEW_ACCOUNT` e/ou `RETRY` (ver abaixo)                                    |
| `versao`                                           | string                | Sim           | Versão do payload                                                          |
| `evento`                                           | string                | Sim           | Sempre `REVISAO_DESEMBOLSO`                                                |
| `id_evento`                                        | string (UUID)         | Sim           | Identificador único do evento                                              |
| `data_evento`                                      | string (datetime UTC) | Sim           | Timestamp do evento                                                        |
| `contract_public_id`                               | string (UUID)         | Sim           | `publicId` do contrato na Giro. Acrescentado pela Giro                     |
| `dados.valor_desembolso`                           | number                | Sim           | Valor do desembolso                                                        |
| `dados.id_transacao`                               | integer (int64)       | Sim           | ID da transferência                                                        |
| `dados.data_pagamento`                             | string (date)         | Sim           | Data de pagamento                                                          |
| `dados.status`                                     | string                | Sim           | Sempre `AGUARDANDO_REVISAO`                                                |
| `dados.favorecido.documento`                       | string                | Sim           | CPF/CNPJ do favorecido                                                     |
| `dados.conta_bancaria`                             | objeto                | Condicional\* | Conta bancária que falhou                                                  |
| `dados.pix`                                        | objeto                | Condicional\* | Chave PIX que falhou                                                       |
| `dados.erro.codigo`                                | string                | Sim           | Código do erro, ex: `paymentError.bankAccount.bankingInconsistent`         |
| `dados.erro.mensagem`                              | string                | Sim           | Descrição do erro                                                          |
| `dados.revisao_conta_desembolso.ticket`            | string                | Sim           | Mesmo valor de `disbursementReview.ticket`                                 |
| `dados.revisao_conta_desembolso.data_criacao`      | string (datetime UTC) | Sim           | Criação do ticket                                                          |
| `dados.revisao_conta_desembolso.data_vencimento`   | string (datetime UTC) | Sim           | Expiração do ticket                                                        |
| `dados.revisao_conta_desembolso.acoes_disponiveis` | array de string       | Não           | `NOVA_CONTA`, `RETENTATIVA`. Prefira `disbursementReview.availableActions` |
| `dados.ccbs[]`                                     | array                 | Sim           | CCBs vinculadas                                                            |
| `dados.numero_ccb`                                 | string                | Sim           | Número da CCB afetada                                                      |
| `dados.origem`                                     | string                | Sim           | Identificador do portfólio                                                 |

\*Estruturas de `conta_bancaria` e `pix` iguais às de [`PAYMENT_SUCCESS`](#payment_success).

#### Ações disponíveis

| Valor         | O que enviar                                                                           |
| ------------- | -------------------------------------------------------------------------------------- |
| `NEW_ACCOUNT` | Uma conta ou chave PIX **ainda não usada** nessa operação                              |
| `RETRY`       | A **mesma** conta ou chave PIX que falhou (a de `dados.pix` ou `dados.conta_bancaria`) |

| Tipo de erro              | Ações no webhook           | O que fazer                                    |
| ------------------------- | -------------------------- | ---------------------------------------------- |
| Dados bancários inválidos | `["NEW_ACCOUNT"]`          | Enviar uma conta ou PIX **novos**              |
| Instabilidade bancária    | `["NEW_ACCOUNT", "RETRY"]` | Reenviar a **mesma** conta, ou enviar uma nova |

São **rejeitados**: reenviar a mesma conta quando só há `NEW_ACCOUNT`; reaproveitar conta de tentativa anterior que não seja a da falha; usar ticket já usado (uso único) ou vencido. Ticket antigo, sem `acoes_disponiveis`, chega com `availableActions` = `["NEW_ACCOUNT"]`.

{% hint style="warning" %}
Há um limite de tentativas por pagamento. Em instabilidade, espace as retentativas.
{% endhint %}

Aceita a nova conta, a transferência é refeita e o resultado chega em `PAYMENT_SUCCESS` ou em novo `PAYMENT_REVISION`. Para simular em homologação, use as [chaves PIX de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md).

**Exemplo — instabilidade bancária (`NEW_ACCOUNT` e `RETRY`):**

```json
{
  "source": "GTBANKER",
  "eventType": "PAYMENT_REVISION",
  "data": {
    "versao": "2",
    "evento": "REVISAO_DESEMBOLSO",
    "id_evento": "a9fabe92-4b07-43c4-ba1c-d5d4873d6a28",
    "data_evento": "2024-04-25T10:30:00Z",
    "disbursementReview": {
      "ticket": "ticket-abc123",
      "createdAt": "2024-04-25T10:30:00Z",
      "expiresAt": "2024-04-27T10:30:00Z",
      "availableActions": ["NEW_ACCOUNT", "RETRY"]
    },
    "dados": {
      "valor_desembolso": 15000,
      "id_transacao": 987654321,
      "data_pagamento": "2024-04-25",
      "status": "AGUARDANDO_REVISAO",
      "favorecido": { "documento": "12345678901" },
      "pix": {
        "chave_pix": "usuario@exemplo.com",
        "tipo_chave_pix": "EMAIL"
      },
      "erro": {
        "codigo": "paymentError.general",
        "mensagem": "Houve uma instabilidade na comunicação com o banco"
      },
      "revisao_conta_desembolso": {
        "ticket": "ticket-abc123",
        "data_criacao": "2024-04-25T10:30:00Z",
        "data_vencimento": "2024-04-27T10:30:00Z",
        "acoes_disponiveis": ["NOVA_CONTA", "RETENTATIVA"]
      },
      "ccbs": [
        {
          "origem": "PARCEIRO_XYZ",
          "numero_ccb": "12345678",
          "documento_tomador": "12345678901",
          "valor_desembolso": 15000
        }
      ],
      "numero_ccb": "12345678",
      "origem": "PARCEIRO_XYZ"
    },
    "contract_public_id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
  }
}
```

**Exemplo — dados bancários inválidos (só `NEW_ACCOUNT`, trecho):**

```json
{
  "source": "GTBANKER",
  "eventType": "PAYMENT_REVISION",
  "data": {
    "versao": "2",
    "evento": "REVISAO_DESEMBOLSO",
    "id_evento": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "data_evento": "2024-04-25T14:10:22Z",
    "disbursementReview": {
      "ticket": "ticket-def456",
      "createdAt": "2024-04-25T14:10:05Z",
      "expiresAt": "2024-04-27T14:10:05Z",
      "availableActions": ["NEW_ACCOUNT"]
    },
    "dados": {
      "status": "AGUARDANDO_REVISAO",
      "erro": {
        "codigo": "paymentError.bankAccount.bankingInconsistent",
        "mensagem": "Chave Pix inexistente ou inválida. Verifique o tipo e o formato da chave conforme padrão do Bacen. Envie novos dados bancários"
      },
      "revisao_conta_desembolso": {
        "ticket": "ticket-def456",
        "data_criacao": "2024-04-25T14:10:05Z",
        "data_vencimento": "2024-04-27T14:10:05Z",
        "acoes_disponiveis": ["NOVA_CONTA"]
      }
    },
    "contract_public_id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
  }
}
```

***

### PAYMENT\_FAILURE

Disparado quando o desembolso falha por motivo que a Giro resolve (ex.: sistema bancário indisponível, limite excedido). Não há ticket nem ação do originador.

O contrato **continua em `FORMALIZED`**. Até o desembolso sair, o `rejectionReason` do contrato traz `Falha no pagamento - Código: <codigo> - <mensagem>`. Contrato em `COMPLETED` ou `CANCELLED` ignora o evento.

| Campo                        | Tipo                  | Obrigatório   | Descrição                                              |
| ---------------------------- | --------------------- | ------------- | ------------------------------------------------------ |
| `versao`                     | string                | Sim           | Versão do payload                                      |
| `evento`                     | string                | Sim           | Sempre `FALHA_DESEMBOLSO`                              |
| `id_evento`                  | string (UUID)         | Sim           | Identificador único do evento                          |
| `data_evento`                | string (datetime UTC) | Sim           | Timestamp do evento                                    |
| `contract_public_id`         | string (UUID)         | Sim           | `publicId` do contrato na Giro. Acrescentado pela Giro |
| `dados.valor_desembolso`     | number                | Sim           | Valor do desembolso                                    |
| `dados.id_transacao`         | integer (int64)       | Sim           | ID da transferência                                    |
| `dados.data_pagamento`       | string (date)         | Sim           | Data de pagamento                                      |
| `dados.status`               | string                | Sim           | Sempre `AGUARDANDO_SOLUCAO_GIRO`                       |
| `dados.favorecido.documento` | string                | Sim           | CPF/CNPJ do favorecido                                 |
| `dados.conta_bancaria`       | objeto                | Condicional\* | Conta bancária usada na tentativa                      |
| `dados.pix`                  | objeto                | Condicional\* | Chave PIX usada na tentativa                           |
| `dados.erro.codigo`          | string                | Sim           | Código do erro                                         |
| `dados.erro.mensagem`        | string                | Sim           | Descrição do erro                                      |
| `dados.ccbs[]`               | array                 | Sim           | CCBs vinculadas                                        |
| `dados.numero_ccb`           | string                | Sim           | Número da CCB afetada                                  |
| `dados.origem`               | string                | Sim           | Identificador do portfólio                             |

\*Estruturas de `conta_bancaria` e `pix` iguais às de [`PAYMENT_SUCCESS`](#payment_success).

```json
{
  "source": "GTBANKER",
  "eventType": "PAYMENT_FAILURE",
  "data": {
    "versao": "1.0",
    "evento": "FALHA_DESEMBOLSO",
    "id_evento": "a9fabe92-4b07-43c4-ba1c-d5d4873d6a28",
    "data_evento": "2024-04-25T10:30:00Z",
    "dados": {
      "valor_desembolso": 15000,
      "id_transacao": 987654321,
      "data_pagamento": "2024-04-25",
      "status": "AGUARDANDO_SOLUCAO_GIRO",
      "favorecido": { "documento": "12345678901" },
      "conta_bancaria": {
        "codigo_banco": "001",
        "numero_conta": "567890",
        "digito_conta": "1",
        "numero_agencia": "1234",
        "tipo": "CORRENTE",
        "documento_favorecido": "12345678901"
      },
      "erro": {
        "codigo": "ERR_SISTEMA_INDISPONIVEL",
        "mensagem": "Sistema bancário temporariamente indisponível"
      },
      "ccbs": [
        {
          "origem": "PARCEIRO_XYZ",
          "numero_ccb": "12345678",
          "documento_tomador": "12345678901",
          "valor_desembolso": 15000
        }
      ],
      "numero_ccb": "12345678",
      "origem": "PARCEIRO_XYZ"
    },
    "contract_public_id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
  }
}
```

***

### CCB\_RECEIVED

Disparado quando o GTBanker recebe a CCB. O contrato passa a `FORMALIZED`.

| Campo                          | Tipo                  | Obrigatório | Descrição                                                                                                                                                                                        |
| ------------------------------ | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `versao`                       | string                | Sim         | Versão do payload                                                                                                                                                                                |
| `evento`                       | string                | Sim         | Sempre `CCB_RECEBIDA`                                                                                                                                                                            |
| `id_evento`                    | string (UUID)         | Sim         | Identificador único do evento                                                                                                                                                                    |
| `data_evento`                  | string (datetime UTC) | Sim         | Timestamp do evento                                                                                                                                                                              |
| `contract_public_id`           | string (UUID)         | Sim         | `publicId` do contrato na Giro. Acrescentado pela Giro                                                                                                                                           |
| `dados.origem`                 | string (max 255)      | Sim         | Identificador único do originador                                                                                                                                                                |
| `dados.numero_ccb`             | string (max 20)       | Sim         | Número da CCB                                                                                                                                                                                    |
| `dados.identificador_programa` | string (max 255)      | Sim         | Identificador do programa em que a operação foi formalizada: o da originação ativa ou, para proposta criada com `proposalNumber` de leilão, o do leilão. Não assuma um valor fixo por originador |
| `dados.data_recebimento`       | string (date)         | Sim         | Data em que a CCB foi recebida pela Giro                                                                                                                                                         |

```json
{
  "source": "GTBANKER",
  "eventType": "CCB_RECEIVED",
  "data": {
    "versao": "1.0",
    "evento": "CCB_RECEBIDA",
    "id_evento": "a9fabe92-4b07-43c4-ba1c-d5d4873d6a28",
    "data_evento": "2024-04-25T10:30:00Z",
    "dados": {
      "origem": "PARCEIRO_XYZ",
      "numero_ccb": "12345678",
      "identificador_programa": "PROGRAMA_CREDITO_PESSOAL",
      "data_recebimento": "2024-04-25"
    },
    "contract_public_id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
  }
}
```

***

### SIGNATURE\_LINK\_RESEND

Disparado quando o link de assinatura do contrato é reenviado por [Reenviar Link de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-giro/reenviar-link-assinatura.md). A variante com `source` = `AUTHORIZATION_DOCUMENT` está **descontinuada**; ela vem sem `contractPublicId` e sem `requestNumber`.

| Campo              | Tipo     | Descrição                                                        |
| ------------------ | -------- | ---------------------------------------------------------------- |
| `cpf`              | `string` | CPF do colaborador.                                              |
| `publicId`         | `string` | `publicId` do empregado (16 caracteres).                         |
| `contractPublicId` | `string` | Identificador público do contrato. Ausente em contratos antigos. |
| `requestNumber`    | `string` | Número da requisição do contrato.                                |
| `nsu`              | `string` | NSU do documento.                                                |
| `signUrl`          | `string` | Novo link de assinatura.                                         |

```json
{
  "source": "AUTHORIZATION_DOCUMENT",
  "eventType": "SIGNATURE_LINK_RESEND",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "nsu": "777481165341001801",
    "signUrl": "https://employee.giro.tech/sign/eyJhbGciOiJIUzUxMi..."
  }
}
```

***

### CONTRACT\_DOCUMENT\_READY

Disparado quando o PDF do contrato fica pronto. Na estratégia **GIRO**, chega com o link de assinatura (`signUrl`). Na **ORIGINATOR\_MANAGED**, colete a assinatura e envie por [Upload de Contrato Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador/upload-contrato-assinado.md). Nova URL de download em [Obter Documento do Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador/baixar-documento-contrato.md).

| Campo            | Tipo                | Descrição                                                             |
| ---------------- | ------------------- | --------------------------------------------------------------------- |
| `publicId`       | `string`            | Identificador público do contrato. Ausente em contratos antigos.      |
| `requestNumber`  | `string`            | Número da requisição do contrato.                                     |
| `contractNumber` | `string`            | Número do contrato (CCB).                                             |
| `nsu`            | `string`            | NSU do documento.                                                     |
| `presignedUrl`   | `string`            | URL temporária do PDF do contrato.                                    |
| `signUrl`        | `string` (nullable) | Link de assinatura na estratégia GIRO; `null` na ORIGINATOR\_MANAGED. |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_DOCUMENT_READY",
  "data": {
    "requestNumber": "GTAB12CD34EF",
    "contractNumber": "00345678",
    "nsu": "777481165341001801",
    "presignedUrl": "https://files.example.com/contracts/00345678.pdf",
    "signUrl": "https://employee.giro.tech/sign/eyJhbGciOiJIUzUxMi..."
  }
}
```

***

### CONTRACT\_SIGNED

Disparado quando a assinatura digital do contrato é concluída (em homologação, também na assinatura simulada). Mesmos campos de [`CONTRACT_DOCUMENT_READY`](#contract_document_ready): `presignedUrl` aponta para o **PDF assinado** e `signUrl` vem `null`. Se a URL expirar, use [Obter Documento do Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador/baixar-documento-contrato.md).

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_SIGNED",
  "data": {
    "requestNumber": "GTAB12CD34EF",
    "contractNumber": "00345678",
    "nsu": "777481165341001801",
    "presignedUrl": "https://files.example.com/contracts/signed/00345678.pdf",
    "signUrl": null
  }
}
```

***

### AUTHORIZATION\_SIGNED

Disparado quando a assinatura digital do termo de autorização é concluída. Mesmos campos de [`AUTHORIZATION_DOCUMENT_READY`](#authorization_document_ready), com `status` = `SIGNED` e `documentUrl` apontando para o PDF assinado. Nova URL em [Obter Documento de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/baixar-documento-autorizacao.md).

```json
{
  "source": "AUTHORIZATION_DOCUMENT",
  "eventType": "AUTHORIZATION_SIGNED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "nsu": "777481165341001801",
    "documentUrl": "https://files.example.com/authorizations/signed/777481165341001801.pdf",
    "status": "SIGNED"
  }
}
```

***

### CONTRACT\_DOCUMENT\_FAILED / CONTRACT\_REGISTRATION\_FAILED / CONTRACT\_SIGNING\_FAILED

Disparados quando uma etapa do contrato termina sem sucesso e não haverá nova tentativa. Depois do evento, reinicie o fluxo do contrato.

| Evento                         | Etapa                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `CONTRACT_DOCUMENT_FAILED`     | Geração do PDF do contrato.                                                                              |
| `CONTRACT_REGISTRATION_FAILED` | Registro do contrato, antes da averbação. A averbação não será feita.                                    |
| `CONTRACT_SIGNING_FAILED`      | Assinatura: retentativas esgotadas, ou assinatura recusada, expirada, cancelada ou com fraude detectada. |

| Campo                      | Tipo                | Descrição                                                                                                                                               |
| -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`                 | `string`            | Identificador público do contrato. Ausente em contratos antigos.                                                                                        |
| `requestNumber`            | `string`            | Número da requisição do contrato.                                                                                                                       |
| `contractNumber`           | `string`            | Número do contrato (CCB).                                                                                                                               |
| `status`                   | `string`            | Sempre `FAILED`.                                                                                                                                        |
| `errorCode`                | `string`            | Motivo (tabela abaixo).                                                                                                                                 |
| `reason`                   | `string` (nullable) | Descrição legível do erro.                                                                                                                              |
| `signatureDocumentStatus`  | `string` (opcional) | Só em `SIGNATURE_CANCELLED` por reprovação na validação do documento: `APPROVED`, `REJECTED`, `IN_PROGRESS`, `NOT_APPLICABLE`. `null` nos demais casos. |
| `signatureFaceMatchStatus` | `string` (opcional) | Só em `SIGNATURE_CANCELLED` por reprovação na comparação facial: `APPROVED`, `REJECTED`, `IN_PROGRESS`, `NOT_APPLICABLE`. `null` nos demais casos.      |

| `errorCode`           | Aplica a                  | Significado                                   |
| --------------------- | ------------------------- | --------------------------------------------- |
| `RETRY_EXHAUSTED`     | os três eventos           | Retentativas esgotadas em falhas transitórias |
| `SIGNATURE_REJECTED`  | `CONTRACT_SIGNING_FAILED` | Assinatura recusada pelo signatário           |
| `SIGNATURE_EXPIRED`   | `CONTRACT_SIGNING_FAILED` | Prazo de assinatura venceu                    |
| `SIGNATURE_CANCELLED` | `CONTRACT_SIGNING_FAILED` | Solicitação de assinatura cancelada           |
| `FRAUD_DETECTED`      | `CONTRACT_SIGNING_FAILED` | Fraude detectada na assinatura                |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_SIGNING_FAILED",
  "data": {
    "requestNumber": "GTAB12CD34EF",
    "contractNumber": "00345678",
    "status": "FAILED",
    "errorCode": "RETRY_EXHAUSTED",
    "reason": "Esgotamento de retentativas em falhas transitórias"
  }
}
```

***

### AUTHORIZATION\_DOCUMENT\_FAILED

Disparado quando a geração do termo de autorização termina sem sucesso e não haverá nova tentativa, ou quando a assinatura do termo é recusada, expira, é cancelada ou tem fraude detectada.

| Campo                      | Tipo                | Descrição                                                                                                                                                                                                                            |
| -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cpf`                      | `string`            | CPF do colaborador.                                                                                                                                                                                                                  |
| `publicId`                 | `string`            | `publicId` do empregado (16 caracteres).                                                                                                                                                                                             |
| `nsu`                      | `string`            | NSU do documento de autorização.                                                                                                                                                                                                     |
| `status`                   | `string`            | Sempre `FAILED`.                                                                                                                                                                                                                     |
| `errorCode`                | `string`            | `RETRY_EXHAUSTED`, `SIGNATURE_REJECTED`, `SIGNATURE_EXPIRED`, `SIGNATURE_CANCELLED` ou `FRAUD_DETECTED` — mesmo significado da [tabela de contrato](#contract_document_failed-contract_registration_failed-contract_signing_failed). |
| `reason`                   | `string` (nullable) | Descrição legível do erro.                                                                                                                                                                                                           |
| `signatureDocumentStatus`  | `string` (opcional) | Como no contrato: só em `SIGNATURE_CANCELLED` por reprovação na validação do documento.                                                                                                                                              |
| `signatureFaceMatchStatus` | `string` (opcional) | Como no contrato: só em `SIGNATURE_CANCELLED` por reprovação na comparação facial.                                                                                                                                                   |

```json
{
  "source": "AUTHORIZATION_DOCUMENT",
  "eventType": "AUTHORIZATION_DOCUMENT_FAILED",
  "data": {
    "cpf": "12345678901",
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "nsu": "777481165341001801",
    "status": "FAILED",
    "errorCode": "RETRY_EXHAUSTED",
    "reason": "Esgotamento de retentativas na geração do documento de autorização"
  }
}
```

***

### CONTRACT\_FORMALIZATION\_FAILED

Disparado uma vez, quando a formalização do contrato é abandonada antes de o GTBanker confirmar a operação. Diferente de [`PAYMENT_FAILURE`](#payment_failure), que é falha do desembolso depois de formalizado.

**O que fazer:** se `reason` aponta dado errado (ex.: chave Pix), corrija com [`PUT /disbursement-accounts` sem `ticket`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md) — a formalização é reenviada automaticamente. Se não for dado, acione o suporte Giro.

| Campo            | Tipo                | Descrição                                                                                                                  |
| ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber` | `string`            | Número do contrato (CCB).                                                                                                  |
| `requestNumber`  | `string`            | Número da requisição do contrato.                                                                                          |
| `status`         | `string`            | Sempre `FAILED`.                                                                                                           |
| `errorCode`      | `string`            | Sempre `RETRY_EXHAUSTED`. A causa vem em `reason`.                                                                         |
| `reason`         | `string` (nullable) | Mensagem do erro que causou a última falha (ex.: motivo de recusa do GTBanker), ou texto genérico de tentativas esgotadas. |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_FORMALIZATION_FAILED",
  "data": {
    "contractNumber": "00345678",
    "requestNumber": "GTAB12CD34EF",
    "status": "FAILED",
    "errorCode": "RETRY_EXHAUSTED",
    "reason": "Chave Pix informada não corresponde ao tipo de chave informado"
  }
}
```

***

### DATAPREV\_WINDOW\_OPENED / DATAPREV\_WINDOW\_CLOSED (Janela de suspensão Dataprev)

Disparados quando a janela de suspensão da Dataprev (virada de competência, tipicamente dias 21 a 23) abre e fecha. Com a janela aberta, consultas de margem e autorizações são rejeitadas e averbações ficam adiadas. Espere o `DATAPREV_WINDOW_CLOSED` para reenviar o que foi rejeitado — nada é reenviado automaticamente.

Os eventos vão uma vez para cada originador inscrito, não por colaborador ou contrato. O `sourceId` é o `windowId`.

| Campo            | Tipo                 | Descrição                                                                    |
| ---------------- | -------------------- | ---------------------------------------------------------------------------- |
| `windowId`       | `integer` (int64)    | Identificador da janela; o mesmo na abertura e no fechamento.                |
| `status`         | `string`             | `SCHEDULED`, `OPEN` ou `CLOSED`. `OPEN` na abertura, `CLOSED` no fechamento. |
| `scheduledStart` | `string` (date-time) | Início planejado.                                                            |
| `scheduledEnd`   | `string` (date-time) | Fim planejado.                                                               |
| `effectiveEnd`   | `string` (date-time) | Fim efetivo. `null` na abertura.                                             |

As datas desta payload vêm **sem fuso** (`2026-05-21T00:00:00`).

```json
{
  "source": "DATAPREV_SUSPENSION_WINDOW",
  "eventType": "DATAPREV_WINDOW_OPENED",
  "data": {
    "windowId": 42,
    "status": "OPEN",
    "scheduledStart": "2026-05-21T00:00:00",
    "scheduledEnd": "2026-05-23T06:00:00",
    "effectiveEnd": null
  }
}
```

```json
{
  "source": "DATAPREV_SUSPENSION_WINDOW",
  "eventType": "DATAPREV_WINDOW_CLOSED",
  "data": {
    "windowId": 42,
    "status": "CLOSED",
    "scheduledStart": "2026-05-21T00:00:00",
    "scheduledEnd": "2026-05-23T06:00:00",
    "effectiveEnd": "2026-05-23T05:12:00"
  }
}
```

### AUCTION\_OFFER\_ACCEPTED

Disparado quando o trabalhador aceita uma das suas ofertas de [leilão](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao.md) pelo [link público de aceite](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/aceite-da-oferta.md). O envelope vem sem `sourceId`: correlacione por `data.proposalNumber`. Em [Listar deliveries](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/configuracao-via-api.md#listar-deliveries), o `sourceId` da entrega é esse mesmo `proposalNumber`.

| Campo            | Tipo                 | Descrição                                                                                                                                                                                                          |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `proposalNumber` | `string`             | Número da proposta da oferta aceita (`GT-{prefixo}-{único}`, 20 caracteres; o prefixo é o código Dataprev do seu originador, ex. `GT-XX-7K3F9Q2M1ZX4AB`).                                                          |
| `solicitationId` | `integer`            | Identificador Dataprev da solicitação. Use-o ao [materializar a proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/aceite-da-oferta.md#depois-do-aceite-materializar-a-proposta). |
| `withWarranty`   | `boolean`            | Se a oferta aceita era a com garantia FGTS.                                                                                                                                                                        |
| `acceptedAt`     | `string` (date-time) | Momento do aceite.                                                                                                                                                                                                 |

```json
{
  "source": "AUCTION",
  "eventType": "AUCTION_OFFER_ACCEPTED",
  "data": {
    "proposalNumber": "GT-XX-7K3F9Q2M1ZX4AB",
    "solicitationId": 987654321,
    "withWarranty": false,
    "acceptedAt": "2026-06-13T12:30:00"
  }
}
```

### AUCTION\_SOLICITATIONS\_REFRESHED

Disparado quando solicitações de proposta recém-recebidas mudam de estado — passam a aceitar oferta ou são descartadas por inelegibilidade. Só chega se ao menos uma mudou. O `sourceId` é o `originatorId`. Como o total inclui as descartadas, `refreshedCount > 0` não garante novidade: veja o que está disponível em [Listar Solicitações](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md).

{% hint style="warning" %}
Desde 2026-07-19 o payload tem só `refreshedCount`; `discovered`, `persistedNew`, `skipped`, `windowStart` e `windowEnd` não são mais enviados. Migração no [changelog](https://docs.giro.tech/desenvolvedores/api-gtpayroll/changelog.md).
{% endhint %}

| Campo            | Tipo      | Descrição                               |
| ---------------- | --------- | --------------------------------------- |
| `refreshedCount` | `integer` | Quantas solicitações mudaram de estado. |

```json
{
  "source": "AUCTION",
  "eventType": "AUCTION_SOLICITATIONS_REFRESHED",
  "sourceId": "1",
  "data": {
    "refreshedCount": 3
  }
}
```

### CONTRACT\_TERMINATED\_BOND

Disparado quando a Dataprev encerra um empréstimo por término do vínculo empregatício (`situacaoEmprestimo.codigo = 15`). O `sourceId` é o `publicId` do contrato quando o empréstimo é da plataforma; para empréstimo de terceiro, o `dataprevContractNumber`. Listagem equivalente em [Empréstimos encerrados (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-global.md).

`installmentAmount` é o **teto da parcela** no [ajuste de parcelas antes da migração automática](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md). Para empréstimo de terceiro, só este evento e a listagem de encerrados mostram esse teto.

| Campo                          | Tipo                 | Descrição                                                                                                                                                             |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`                     | `string` (uuid)      | Identificador público do registro de encerramento.                                                                                                                    |
| `dataprevContractNumber`       | `string`             | Número do contrato na Dataprev. Sempre preenchido.                                                                                                                    |
| `contractPublicId`             | `string` (uuid)      | Identificador público do contrato na plataforma. Nulo para empréstimo de terceiro.                                                                                    |
| `contractNumber`               | `string`             | Preenchido apenas quando o empréstimo encerrado é um contrato nosso.                                                                                                  |
| `requestNumber`                | `string`             | Preenchido apenas quando o empréstimo encerrado é um contrato nosso.                                                                                                  |
| `cpf`                          | `string`             | CPF do trabalhador (11 dígitos).                                                                                                                                      |
| `registrationNumber`           | `string`             | Matrícula do trabalhador no vínculo encerrado.                                                                                                                        |
| `terminationDate`              | `string` (date)      | Data do término do vínculo. Pode ser nula.                                                                                                                            |
| `terminationReasonCode`        | `integer`            | Código Dataprev do motivo do desligamento. Tabela: [Motivo de Desligamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-desligamento.md). |
| `terminationReasonDescription` | `string`             | Descrição do motivo do desligamento retornada pela Dataprev.                                                                                                          |
| `totalInstallments`            | `integer`            | Total de parcelas do empréstimo encerrado.                                                                                                                            |
| `paymentsCount`                | `integer`            | Quantidade de pagamentos registrados.                                                                                                                                 |
| `installmentAmount`            | `number`             | Valor da parcela em reais (2 casas decimais).                                                                                                                         |
| `hasGuarantees`                | `boolean`            | `true` quando o contrato encerrado tem garantias.                                                                                                                     |
| `updatedAtDataprev`            | `string` (date-time) | Última atualização na Dataprev.                                                                                                                                       |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_TERMINATED_BOND",
  "sourceId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "data": {
    "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b03",
    "dataprevContractNumber": "2GT00000028",
    "contractPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
    "contractNumber": "00345678",
    "requestNumber": "GTAB12CD34EF",
    "cpf": "12345678901",
    "registrationNumber": "000108",
    "terminationDate": "2026-06-30",
    "terminationReasonCode": 7,
    "terminationReasonDescription": "Rescisão do contrato de trabalho por iniciativa do empregado",
    "totalInstallments": 12,
    "paymentsCount": 0,
    "installmentAmount": 231.29,
    "hasGuarantees": true,
    "updatedAtDataprev": "2026-07-21T12:10:38Z"
  }
}
```

### GUARANTEE\_EXECUTED

Disparado quando a Dataprev aceita a execução da garantia FGTS (saldo e/ou multa rescisória) de um contrato encerrado por término do vínculo. A execução é irreversível e só ocorre uma vez por contrato: não há evento de reversão nem segunda entrega. Recusas não geram evento; consulte-as em [Consultar execução de garantia](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/consultar-execucao-de-garantia.md). O `sourceId` é o `publicId` do contrato.

{% hint style="warning" %}
O evento **não altera o status do contrato** nem dá baixa na dívida. `transferForecastDate` é previsão da Dataprev: a conciliação do valor recebido é sua.
{% endhint %}

| Campo                    | Tipo                 | Descrição                                                                                                  |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| `contractPublicId`       | `string` (uuid)      | Identificador público do contrato.                                                                         |
| `contractNumber`         | `string`             | Número do contrato na plataforma.                                                                          |
| `requestNumber`          | `string`             | Número da requisição do contrato.                                                                          |
| `dataprevContractNumber` | `string`             | Número do contrato na Dataprev (máx. 15 caracteres).                                                       |
| `cpf`                    | `string`             | CPF do trabalhador (11 dígitos).                                                                           |
| `protocol`               | `string`             | Protocolo da execução na Dataprev. **String, não número**: até 32 dígitos, não cabe em inteiro de 64 bits. |
| `transferForecastDate`   | `string` (date)      | Data prevista de repasse informada pela Dataprev.                                                          |
| `fgtsBalanceAmount`      | `number`             | Saldo de FGTS executado. Nulo quando a execução foi só de multa.                                           |
| `severancePenaltyAmount` | `number`             | Multa rescisória executada. Nulo quando a execução foi só de saldo.                                        |
| `executedAt`             | `string` (date-time) | Momento da execução.                                                                                       |

```json
{
  "source": "CONTRACT",
  "eventType": "GUARANTEE_EXECUTED",
  "sourceId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "data": {
    "contractPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
    "contractNumber": "00345678",
    "requestNumber": "GTAB12CD34EF",
    "dataprevContractNumber": "2GT00000028",
    "cpf": "12345678901",
    "protocol": "12345678901234567890123456789012",
    "transferForecastDate": "2026-09-20",
    "fgtsBalanceAmount": 1200.55,
    "severancePenaltyAmount": 480.00,
    "executedAt": "2026-09-03T10:30:00"
  }
}
```

### TERMINATED\_LOAN\_NEW\_BOND

Disparado quando aparece um novo vínculo para um trabalhador com empréstimo encerrado por término de vínculo. O `sourceId` identifica a entrega, para deduplicação; o vínculo novo é o `data.employmentRelationshipPublicId`. Listagem equivalente em [Novos vínculos global](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-global.md) e [Novos vínculos por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-por-contrato.md), com o registro completo.

{% hint style="info" %}
**`eligible=false` com `ineligibilityReasonCode=8` é o normal neste evento**: a Dataprev marca o vínculo novo como inelegível justamente por haver empréstimo encerrado. Use `actionable` como critério, não `eligible`.
{% endhint %}

| Campo                            | Tipo                 | Descrição                                                                                                                                                                                                                                            |
| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `employmentRelationshipPublicId` | `string` (uuid)      | Identificador público do vínculo novo — é ele que vai em `quote.employmentRelationshipPublicId` na renegociação. `null` quando o empréstimo encerrado é de outra instituição: aí não há renegociação a fazer, e sim portabilidade.                   |
| `dataprevContractNumber`         | `string`             | Número Dataprev do empréstimo encerrado.                                                                                                                                                                                                             |
| `contractNumber`                 | `string`             | Preenchido apenas quando o empréstimo encerrado é um contrato nosso.                                                                                                                                                                                 |
| `requestNumber`                  | `string`             | Preenchido apenas quando o empréstimo encerrado é um contrato nosso.                                                                                                                                                                                 |
| `cpf`                            | `string`             | CPF do trabalhador (11 dígitos).                                                                                                                                                                                                                     |
| `registrationNumber`             | `string`             | Matrícula do trabalhador no novo vínculo.                                                                                                                                                                                                            |
| `employerRegistrationNumber`     | `string`             | Número de inscrição do empregador.                                                                                                                                                                                                                   |
| `admissionDate`                  | `string` (date)      | Data de admissão no novo vínculo.                                                                                                                                                                                                                    |
| `eligible`                       | `boolean`            | Valor bruto da Dataprev. Use `actionable`.                                                                                                                                                                                                           |
| `ineligibilityReasonCode`        | `integer`            | `8` = CPF com empréstimo encerrado por término de vínculo (renegociável); `4` = vínculo antigo, nunca renegociável. Tabela: [Motivo de Inelegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-inelegibilidade.md). |
| `ineligibilityReasonDescription` | `string`             | Descrição do motivo retornada pela Dataprev, quando informada.                                                                                                                                                                                       |
| `actionable`                     | `boolean`            | `eligible=true` **ou** `ineligibilityReasonCode=8`.                                                                                                                                                                                                  |
| `migrated`                       | `boolean`            | `true` quando a Dataprev já migrou o contrato encerrado para um vínculo novo. Contrato migrado não aceita renegociação nem alteração (`422`). Normalmente vem `false`, e a migração chega depois por `CONTRACT_MIGRATED_AUTOMATICALLY`.              |
| `availableMarginAmount`          | `number`             | Margem disponível em reais (2 casas decimais).                                                                                                                                                                                                       |
| `loansCount`                     | `integer`            | Quantidade de empréstimos do vínculo.                                                                                                                                                                                                                |
| `atLoanLimit`                    | `boolean`            | `loansCount >= 9`. Oportunidade neste limite não pode ser renegociada.                                                                                                                                                                               |
| `marginCapturedAt`               | `string` (date-time) | Quando a Dataprev capturou a margem — não é o instante do evento.                                                                                                                                                                                    |

```json
{
  "source": "TERMINATED_LOAN_NEW_BOND",
  "eventType": "TERMINATED_LOAN_NEW_BOND",
  "sourceId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "data": {
    "employmentRelationshipPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
    "dataprevContractNumber": "2GT00000028",
    "contractNumber": "00345678",
    "requestNumber": "GTAB12CD34EF",
    "cpf": "12345678901",
    "registrationNumber": "000108",
    "employerRegistrationNumber": "12345678000195",
    "admissionDate": "2026-07-14",
    "eligible": false,
    "ineligibilityReasonCode": 8,
    "ineligibilityReasonDescription": "Vínculo com empréstimo encerrado por término de vínculo",
    "actionable": true,
    "migrated": false,
    "availableMarginAmount": 843.39,
    "loansCount": 3,
    "atLoanLimit": false,
    "marginCapturedAt": "2026-08-12T06:00:14Z"
  }
}
```

### TERMINATED\_LOAN\_ALTERED

Disparado quando a Dataprev aceita a alteração do número e do valor das parcelas de um empréstimo encerrado por término de vínculo, feita por [Alterar contrato encerrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md). A alteração não migra o contrato: ajusta as parcelas para que a migração automática da Dataprev leve o contrato ao vínculo novo com esse plano. O `sourceId` é o `publicId` da alteração; consulta equivalente em [Consultar alteração](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/consultar-alteracao-emprestimo-encerrado.md).

| Campo                       | Tipo                 | Descrição                                                                             |
| --------------------------- | -------------------- | ------------------------------------------------------------------------------------- |
| `publicId`                  | `string` (uuid)      | Identificador público da alteração.                                                   |
| `closedContractNumber`      | `string`             | Número do contrato encerrado. **O mesmo de antes** — a operação não gera número novo. |
| `status`                    | `string`             | `COMPLETED`.                                                                          |
| `installmentCount`          | `integer`            | Número de parcelas depois da alteração.                                               |
| `installmentAmount`         | `number`             | Valor da parcela depois da alteração.                                                 |
| `previousInstallmentCount`  | `integer`            | Número de parcelas antes. Nulo quando desconhecido.                                   |
| `previousInstallmentAmount` | `number`             | Valor da parcela antes. Nulo quando desconhecido.                                     |
| `providerSuccessCode`       | `string`             | Código de sucesso da Dataprev, cru.                                                   |
| `providerMessage`           | `string`             | Mensagem da Dataprev, crua.                                                           |
| `completedAt`               | `string` (date-time) | Momento do desfecho.                                                                  |

```json
{
  "source": "CONTRACT",
  "eventType": "TERMINATED_LOAN_ALTERED",
  "sourceId": "3f6b1c9e-1d4a-4d2f-9a44-6a2b7f0d5c11",
  "data": {
    "publicId": "3f6b1c9e-1d4a-4d2f-9a44-6a2b7f0d5c11",
    "closedContractNumber": "00000028",
    "status": "COMPLETED",
    "installmentCount": 36,
    "installmentAmount": 120.00,
    "previousInstallmentCount": 24,
    "previousInstallmentAmount": 189.90,
    "providerSuccessCode": "AB",
    "providerMessage": "Alteração efetuada",
    "completedAt": "2026-09-08T13:22:41Z"
  }
}
```

### TERMINATED\_LOAN\_ALTERATION\_FAILED

Disparado quando a Dataprev recusa a alteração. Mesmos campos de [`TERMINATED_LOAN_ALTERED`](#terminated_loan_altered), com `status` = `FAILED`, `providerSuccessCode` nulo e a recusa em `providerErrorCode` / `providerMessage`. `providerErrorCode` pode trazer `HW` (margem consignável excedida) e `PL` (empréstimo em refinanciamento), que só a Dataprev avalia.

```json
{
  "source": "CONTRACT",
  "eventType": "TERMINATED_LOAN_ALTERATION_FAILED",
  "sourceId": "3f6b1c9e-1d4a-4d2f-9a44-6a2b7f0d5c11",
  "data": {
    "publicId": "3f6b1c9e-1d4a-4d2f-9a44-6a2b7f0d5c11",
    "closedContractNumber": "00000028",
    "status": "FAILED",
    "installmentCount": 36,
    "installmentAmount": 120.00,
    "previousInstallmentCount": 24,
    "previousInstallmentAmount": 189.90,
    "providerErrorCode": "HZ",
    "providerMessage": "Não é possível fazer a operação com o empréstimo nesta situação",
    "completedAt": "2026-09-08T13:22:41Z"
  }
}
```

### CONTRACT\_MIGRATED\_AUTOMATICALLY

Disparado quando a Dataprev move sozinha um contrato encerrado por término de vínculo para um vínculo novo ativo do mesmo trabalhador. Vale para contratos formalizados a partir de 24/07/2025 (Lei 15.179). É aviso, não pedido de ação: não há endpoint para provocar nem cancelar a migração. O contrato **não recebe número novo** — o `dataprevContractNumber` é o mesmo de antes.

Só o originador dono do contrato recebe o evento. O `sourceId` é o `publicId` do contrato; se o contrato não for seu, o número do contrato na Dataprev. Listagem equivalente em [Migrações automáticas (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-global.md).

{% hint style="danger" %}
Este evento e o [`TERMINATED_LOAN_NEW_BOND`](#terminated_loan_new_bond) falam do mesmo contrato em momentos diferentes: primeiro chega o aviso do vínculo novo; dias depois, a migração. O primeiro é informativo: não há ação a tomar sobre o vínculo novo. O que cabe a você, se for o caso, é [ajustar as parcelas](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md) do contrato encerrado antes da migração.
{% endhint %}

| Campo                                         | Tipo                      | Descrição                                                                                                                                                                                      |
| --------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`                                    | `string` (uuid)           | Identificador da migração, o mesmo de [Migrações automáticas (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-global.md). |
| `dataprevContractNumber`                      | `string`                  | Número do contrato na Dataprev. Não muda na migração.                                                                                                                                          |
| `contractPublicId`                            | `string` (uuid)           | Contrato na Giro. `null` quando o contrato não é de uma proposta sua.                                                                                                                          |
| `contractNumber`                              | `string`                  | Número do contrato na Giro. `null` no mesmo caso.                                                                                                                                              |
| `requestNumber`                               | `string`                  | Número da requisição do contrato. `null` no mesmo caso.                                                                                                                                        |
| `cpf`                                         | `string`                  | CPF do trabalhador (11 dígitos).                                                                                                                                                               |
| `previousBond`                                | `object`                  | Vínculo de onde o contrato saiu: o da averbação ou, numa migração encadeada (A→B e depois B→C), o destino da migração anterior.                                                                |
| `previousBond.registrationNumber`             | `string`                  | Matrícula do trabalhador no vínculo antigo.                                                                                                                                                    |
| `previousBond.employerRegistrationNumber`     | `string`                  | Inscrição do empregador como a Dataprev o identifica: raiz do CNPJ (8 caracteres) ou CPF. Pode ser `null`. Para comparar com `currentBond`, use `employerTaxId`.                               |
| `previousBond.employerName`                   | `string`                  | Nome do empregador antigo.                                                                                                                                                                     |
| `previousBond.employerTaxId`                  | `string`                  | Documento completo do empregador: CNPJ da **matriz** (raiz + `0001` + dígitos verificadores) quando só se tem a raiz, ou CPF. `null` quando não é possível afirmar um documento válido.        |
| `previousBond.employerTaxIdType`              | `string`                  | `CNPJ` ou `CPF`. `null` junto com `employerTaxId`.                                                                                                                                             |
| `previousBond.employmentRelationshipPublicId` | `string` (uuid)           | Vínculo na plataforma, quando já existe.                                                                                                                                                       |
| `currentBond`                                 | `object`                  | Vínculo de destino. Mesmos campos de `previousBond`.                                                                                                                                           |
| `guarantee`                                   | `object`                  | Garantia **depois** da migração, como a Dataprev devolve. `null` quando não informada — não significa "sem garantia".                                                                          |
| `guarantee.hasGuarantees`                     | `boolean`                 | Se o contrato migrado mantém garantia. Fora da transferência de grupo econômico a migração não leva a garantia; na transferência, leva. Decida só por este campo.                              |
| `guarantee.fgtsBalanceAmount`                 | `number`                  | Saldo de FGTS em garantia.                                                                                                                                                                     |
| `guarantee.fgtsPenaltyAmount`                 | `number`                  | Multa rescisória do FGTS em garantia.                                                                                                                                                          |
| `guarantee.severancePercentage`               | `number`                  | Percentual das verbas rescisórias em garantia.                                                                                                                                                 |
| `migratedAt`                                  | `string` (date-time, UTC) | Instante da migração na Dataprev — não é o instante do evento.                                                                                                                                 |

```json
{
  "source": "CONTRACT",
  "eventType": "CONTRACT_MIGRATED_AUTOMATICALLY",
  "sourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "publicId": "8f14e45f-ceea-467a-9f0b-2c1c0a2c0b31",
    "dataprevContractNumber": "2GT00000028",
    "contractPublicId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "contractNumber": "00345678",
    "requestNumber": "GTAB12CD34EF",
    "cpf": "12345678901",
    "previousBond": {
      "registrationNumber": "000108",
      "employerRegistrationNumber": "11222333",
      "employerName": "EMPREGADOR ANTIGO LTDA",
      "employerTaxId": "11222333000181",
      "employerTaxIdType": "CNPJ",
      "employmentRelationshipPublicId": "0198f0c0-0000-7000-8000-0000000000b1"
    },
    "currentBond": {
      "registrationNumber": "000221",
      "employerRegistrationNumber": "12345678",
      "employerName": "EMPREGADOR NOVO LTDA",
      "employerTaxId": "12345678000195",
      "employerTaxIdType": "CNPJ",
      "employmentRelationshipPublicId": null
    },
    "guarantee": {
      "hasGuarantees": false,
      "fgtsBalanceAmount": null,
      "fgtsPenaltyAmount": null,
      "severancePercentage": null
    },
    "migratedAt": "2026-09-08T06:12:44Z"
  }
}
```
