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

# Changelog da API

Registro das mudanças relevantes da **API GTPayroll (Originator)** — novos endpoints, webhooks e alterações de contrato.

Convenção de formato:

* **Data** — cada release é identificada por uma data no formato ISO `AAAA-MM-DD`. **A mais recente fica no topo.**
* **Categorias por entrada** — cada mudança é classificada em uma destas categorias:
  * **Adicionado** — novos endpoints, campos opcionais ou eventos.
  * **Alterado** — mudança de comportamento ou ampliação de contrato já existente (ex.: novo valor de enum).
  * **Corrigido** — correção de bug ou de comportamento divergente do documentado.
  * **Removido / Descontinuado** — remoção ou deprecação de endpoint, campo ou evento.

Convenção de compatibilidade:

* **Aditivo (não-breaking)** — novos endpoints, campos opcionais ou eventos. **Retrocompatível**: integrações existentes continuam funcionando sem mudança. Aplica-se tipicamente às categorias **Adicionado** e **Alterado** quando sinalizadas como *(aditivo, não-breaking)*.
* **Breaking** — remoção de campo, mudança de tipo ou de comportamento que exige ação do integrador. Sempre sinalizado explicitamente.

> Catálogo completo de eventos em [Webhooks — Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md). Códigos de erro em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

***

## 2026-11-18

### Leilão: consulta de oferta vigente por CPF

**Adicionado** · **Aditivo (não-breaking)**

* Novo [Consultar Oferta Vigente](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/consultar-oferta-vigente.md) (`POST /api/v1/originator/auction/offers/active-query`): dado o CPF do trabalhador, devolve as ofertas de leilão vigentes para ele — entre originadores, independente de quem enviou a oferta — agrupadas por instituição financeira ofertante (até uma com garantia e uma sem, por grupo). CPF sem oferta vigente devolve `200` com `offers: []`.
* Permite checar o teto de taxa descrito em [CPF com oferta vigente](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao.md#cpf-com-oferta-vigente) antes de criar a proposta, em vez de descobri-lo de forma reativa pelo `422` `AUCTION_ACTIVE_OFFER_RATE_EXCEEDED`.

***

## 2026-10-29

### Leilão: CCB de CPF com oferta vigente é amarrada à oferta

**Alterado** · **Aditivo (não-breaking)**

* A Dataprev recusa (`HW`) averbação de CPF com oferta de leilão vigente que não referencie a oferta. A plataforma passa a fazer o vínculo para toda CCB do CPF, de qualquer originador — regras em [CPF com oferta vigente](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao.md#cpf-com-oferta-vigente).
* [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md) pode responder `422` `AUCTION_ACTIVE_OFFER_RATE_EXCEEDED` (taxa acima do teto, devolvido em `properties.maxMonthlyInterestRate`) e `409` `AUCTION_OFFER_BUSY` (oferta em uso; repetir com nova `Idempotency-Key`). `AUCTION_OFFER_NOT_FOUND` passa a cobrir também oferta já reivindicada por outra proposta.
* `ENDORSEMENT_FAILED` pode trazer `errorCode` `AUCTION_OFFER_RATE_EXCEEDED_PRE_ENDORSEMENT`, `AUCTION_OFFER_WARRANTY_MISMATCH_PRE_ENDORSEMENT`, `AUCTION_OFFER_EXPIRED_PRE_ENDORSEMENT`, `AUCTION_OFFER_SOLICITATION_CONSUMED_PRE_ENDORSEMENT`, `AUCTION_PROGRAM_NOT_CONFIGURED_PRE_ENDORSEMENT` e `AUCTION_OFFER_CLAIM_CONTENTION_TIMEOUT`; `ENDORSEMENT_RETRYING` pode trazer `AUCTION_OFFER_CLAIM_CONTENTION`. Significado e ação em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md#async).
* Oferta sua pode ficar `CONVERTED` pela CCB de outro originador; recusa da plataforma antes de enviar à Dataprev não marca mais a oferta como `LOST`.
* Integrações que tratam `errorCode` desconhecido como falha genérica não precisam de mudança; quem usa `switch` fechado deve acrescentar os valores.

***

## 2026-10-27

### Webhooks do GTBanker: `contract_public_id` para correlacionar o contrato

**Adicionado** *(aditivo, não-breaking)*

* Os eventos de source `GTBANKER` — [`PAYMENT_SUCCESS`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_success), [`PAYMENT_REVISION`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_revision), [`PAYMENT_FAILURE`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_failure) e [`CCB_RECEIVED`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#ccb_received) — passam a trazer `contract_public_id` na raiz do `data`, com o `publicId` do contrato na Giro.
* Use esse campo para achar o contrato. O `dados.numero_ccb` vem do GTBanker como ele mandou e pode chegar sem os zeros à esquerda.
* Num desembolso com várias CCBs, cada webhook leva o `contract_public_id` do contrato a que se refere. Nenhum campo existente mudou.

### Consulta de margem por vínculo: datas de admissão e desligamento e demais dados do vínculo

**Adicionado** *(aditivo, não-breaking)*

* O `relationship` do resultado de [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md) (`GET /api/v1/originator/margin-queries/{requestId}`) passa a trazer `admissionDate`, `terminationDate` e `terminationReason`. Um vínculo inelegível por `BOND_WITH_TERMINATION_DATE` agora vem com a data e o motivo do desligamento que causaram a inelegibilidade.
* Também passam a vir os mesmos dados de trabalhador, empregador e bloqueio que o [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) já devolve: `workerName`, `workerCategory`, `workerCategoryDescription`, `workerCboCode`, `workerCboDescription`, `nationalityCode`, `nationalityDescription`, `politicallyExposedPerson`, `employerTaxIdType`, `employerCnae`, `employerCnaeDescription`, `employerActivityStartDate`, `blockingTypeCode`, `blockingTypeDescription` e `totalEarnings`.
* Todos os campos novos podem vir `null`. Nenhum campo existente mudou.

***

## 2026-10-15

### Desaverbação: liberada com o pagamento parado, recusada com o pagamento em curso

**Alterado** · **Breaking** para quem trata `FORMALIZATION_ALREADY_SENT` pelo nome

* A [desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desaverbar-contrato.md) passa a decidir pela situação do pagamento no GTBanker, e não mais apenas pelo envio da CCB:
  * **aceita** (`202`) antes do envio da CCB (sem mudança) e, agora, também com o pagamento parado aguardando nova conta (`PAYMENT_REVISION`), mesmo com o ticket vencido. Até aqui, todo contrato com CCB enviada era recusado;
  * **recusada** com o novo `409 DISBURSEMENT_IN_PROGRESS` enquanto o pagamento pode estar acontecendo: CCB enviada aguardando confirmação, desembolso em andamento, correção de conta em andamento ou falha de desembolso em análise. O `detail` diz o estado e orienta a tentar de novo após o desfecho.
* O desfecho continua chegando por `ENDORSEMENT_EXCLUDED` ou `ENDORSEMENT_EXCLUSION_FAILED`; não há evento novo. Regras e orientação em [Desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md#desaverbacao-e-pagamento).
* `409 CONTRACT_ALREADY_CANCELLED` (contrato já cancelado), que já podia ser retornado, passa a ser documentado.
* Integrações que tratam `409` de forma genérica não precisam de mudança. Quem trata `FORMALIZATION_ALREADY_SENT` pelo nome deve passar a tratar `DISBURSEMENT_IN_PROGRESS`, que **não** é definitivo: tente de novo após o desfecho do pagamento.

### Atualizar Conta de Desembolso: novos casos de `422`

**Alterado**

* [Atualizar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md) passa a recusar com `422 FORMALIZATION_NOT_CORRECTABLE`, com mensagem própria para cada caso: desaverbação em andamento ou concluída (ou contrato cancelado), desembolso já pago, correção de conta já em andamento (com `ticket`, janela de 5 minutos) e, sem `ticket`, envio da CCB suspenso por pedido de desaverbação. Não há código novo.
* Depois de um pedido de desaverbação, o envio da CCB ainda não enviada fica suspenso mesmo que a desaverbação falhe; a retomada é feita pelo suporte.

### Removido: desaverbação automática 5 dias após a formalização

**Removido / Descontinuado**

* O gatilho automático de desaverbação 5 dias após a formalização, descrito no guia como podendo estar desligado, foi removido.

### Removido: `FORMALIZATION_ALREADY_SENT`

**Removido / Descontinuado**

* O `409 FORMALIZATION_ALREADY_SENT` deixa de ser retornado pela desaverbação; os casos que ainda são recusados passam a `DISBURSEMENT_IN_PROGRESS`.

***

## 2026-10-05

### Leilão: `proposalNumber` define o programa da formalização

**Alterado** · **Aditivo (não-breaking)**

* A proposta criada com `proposalNumber` de uma [oferta de leilão](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/aceite-da-oferta.md) é formalizada no programa de leilão do originador; sem `proposalNumber`, no programa da originação ativa. O `identificador_programa` dos webhooks do GTBanker passa a refletir esse programa.
* Com `proposalNumber` e sem `solicitationId`, a Giro grava o `solicitationId` da oferta; sem `proposalNumber`, o `solicitationId` enviado é ignorado.
* Na proposta que materializa uma oferta aceita, informe sempre o `proposalNumber`: sem ele, a operação não é tratada como leilão.

### Leilão: proposta e contrato exigem originador habilitado

**Alterado**

* [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md) com `proposalNumber` e [Criar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md) de proposta de leilão retornam `403` `AUCTION_PARTICIPATION_DISABLED` quando o originador não tem a participação no leilão habilitada. Propostas e contratos sem `proposalNumber` não mudam.

***

## 2026-10-04

### Webhooks de falha: `NEEDS_VERIFICATION_TIMEOUT` e `ADMIN_FAIL`

**Alterado** · **Aditivo (não-breaking)**

* [`MARGIN_QUERY_FAILED` e `AUTHORIZATION_FAILED`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md) passam a poder trazer `errorCode` `NEEDS_VERIFICATION_TIMEOUT` (a Dataprev não confirmou nem descartou a operação e a verificação não fechou no prazo) e `ADMIN_FAIL` (operador da plataforma encerrou a operação como falha após verificação manual). Nos dois casos o efeito na Dataprev é desconhecido e a plataforma não reenvia sozinha.
* O `errorCode` de `ENDORSEMENT_FAILED` pode trazer os mesmos dois valores, com o mesmo significado.
* [`FGTS_AVAILABILITY_QUERY_FAILED`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md) passa a poder trazer `errorCode` `PROVIDER_ERROR`: a Dataprev rejeitou a consulta sem informar código.
* Integrações que tratam `errorCode` desconhecido como falha genérica não precisam de mudança; quem usa `switch` fechado sobre o enum deve acrescentar os dois valores.

### Simulação reversa: `maxEffectiveCostSpread` aceito, teto não aplicado

**Alterado** *(documentação do comportamento atual)*

* Na simulação por parcela ([com vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao-por-parcela.md) e [sem vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo-por-parcela.md)), `maxEffectiveCostSpread` é aceito, mas o teto **não é aplicado nem verificado**: não há isenção de dias de juros de carência por causa dele.
* `effectiveCostWithinLimit` vem `true` quando o campo não é enviado e `null` explícito no JSON quando é enviado. Na simulação direta o comportamento não muda.

***

## 2026-10-02

### Link do comprovante do desembolso no contrato

**Adicionado** · **Aditivo (não-breaking)**

* [Buscar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md) e a listagem de contratos do originador ganham o campo opcional **`paymentReceiptUrl`**: o link do comprovante do desembolso emitido pelo banco liquidante. Aparece depois do pagamento, inclusive quando o desembolso chega após um cancelamento.
* **É uma credencial.** Quem tem o link abre o comprovante sem autenticação: não o publique, não o grave em log nem o envie por canal aberto.
* Integrações que ignoram campos desconhecidos não precisam de nenhuma ação.

***

## 2026-10-01

### Erros: catálogo completo

**Corrigido** *(documentação; nenhuma mudança na API)*

* [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md) passa a listar todos os `errorCode` por status (400, 403, 404, 409, 413, 422, 503), as regras de negócio sem `errorCode` (identificadas pelo `detail`), os motivos de elegibilidade, a janela de suspensão da Dataprev (`423`), o `503` de indisponibilidade e as falhas que chegam só por webhook ou pelo status do recurso.
* O guia dizia que corpo ilegível e parâmetro de tipo errado vinham como `#invalid-request-body`/`#invalid-parameter`. A resposta real é `type: about:blank`, sem `properties` (`Failed to read request`, `Failed to convert …`), assim como `405` e `415`.
* Os erros `422` vêm com `type` `#business-rule-violation`. O fragmento `#unprocessable-entity` não existe e saiu dos exemplos.
* A tabela de erros de cada página de endpoint passou a trazer o `errorCode`, os `423`/`429` aplicáveis e os desfechos por webhook. Correções: Cadastrar Vínculo usa `EMPLOYMENT_RELATIONSHIP_TERMINATED` (não `EMPLOYMENT_RELATIONSHIP_NOT_ACTIVE`); em Submeter Ofertas, parcelas acima de 96 saem como erro de validação sem `HV`; no desembolso, toda indisponibilidade chega como `SERVICE_UNAVAILABLE_GTBANKER`; Reenviar Link responde `404` (não `400`) para contrato inexistente; vínculo ou simulação inexistente em Criar Simulação/Proposta é `400`, não `404`.

### Leilão: horário de abertura para ofertas e filtro por data

**Adicionado** *(aditivo, não-breaking)*

* [Listar Solicitações](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md) (`GET /api/v1/originator/auction/solicitations`): campo `openForOffersAt` — quando a solicitação ficou disponível para ofertas — e filtros `from`/`to` por esse campo, em janela meio-aberta `[from, to)`. O `discoveredAt` marca a leitura na Dataprev, até cerca de 1 minuto antes de a solicitação aceitar oferta; filtrar por ele deixava solicitações de fora. Veja [Consulta incremental](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md#consulta-incremental).

**Alterado** *(aditivo, não-breaking)*

* A listagem passa a vir ordenada por `openForOffersAt,id` quando `sort` não é enviado. Antes não havia ordem garantida.

***

## 2026-09-29

### Simulação sem vínculo e regra do primeiro vencimento

**Adicionado** *(aditivo, não-breaking)*

* [Simular sem Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md) (`POST /api/v1/originator/simulations`) e [Simular sem Vínculo por Parcela](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo-por-parcela.md) (`POST /api/v1/originator/simulations/by-installment`): calculam a simulação sem employee nem vínculo cadastrados, para simular a migração de um contrato antes de o vínculo novo existir. Respondem `200` sem `publicId`, não validam margem nem regras de elegibilidade, e o resultado não é gravado nem pode ser convertido em proposta.

**Corrigido**

* A documentação da [regra de vencimento automático](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md#regra-de-vencimento-automatico) dizia dia 28 do mês seguinte (ou do segundo mês seguinte a partir do dia 21). Desde 06/08/2026 (v0.6.2) o cálculo é +2/+3: `loanDate` até o dia 20 → dia 28, dois meses depois; do dia 21 em diante → dia 28, três meses depois. Ex.: `loanDate` `2027-01-04` → primeiro vencimento `2027-03-28`. A documentação não tinha acompanhado.
* Nas respostas de [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md) e [Criar Simulação por Parcela](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao-por-parcela.md), o campo do teto de CET se chama `effectiveCostWithinLimit` (a documentação dizia `effectiveCostLimitReached`), e as tabelas de erros passam a listar `409` (mesma `Idempotency-Key` em processamento), a recusa do simulador de crédito (`LOAN_SIMULATOR_ERROR`) e `503`.
* `amortizationMethod` saiu do corpo de [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md) e [Criar Simulação por Parcela](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao-por-parcela.md). O sistema de amortização vem só da configuração do originador (sem configuração, `PRICE_ACTUAL_DAYS`). Se o campo continuar sendo enviado, a API o ignora sem erro.
* [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md): os campos extras do Problem Details (`message`, `errors`, `errorCode`, `retryAfter`, `limit`, `resetAt`) vêm dentro de `properties`, não na raiz, e `resetAt` é epoch em milissegundos. A API não mudou; só a documentação.
* [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md): a chave vale por originador, **não** por endpoint — reutilizá-la em outra rota devolve a resposta guardada da primeira. A resposta é guardada com qualquer status, inclusive erro; depois de um `429` ou `503`, reenvie com uma chave nova.

***

## 2026-09-24

### Endpoints fora da documentação e com remoção programada

**Removido / Descontinuado**

Os endpoints abaixo saíram desta documentação e **serão removidos da API**. Se a sua integração usa algum deles, avise a Giro.Tech antes da remoção.

| Endpoint                                                                                                                                   | Substituto                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/originator/renegotiations` e `GET /api/v1/originator/renegotiations/{contractPublicId}` — renegociação de contrato encerrado | Nenhum. A Dataprev migra o contrato sozinha; veja [Migração Automática por Término de Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/migracao-automatica-termino-vinculo.md). Todos os contratos originados pela plataforma são posteriores a 24/07/2025 e caem na migração automática |
| `GET /api/v1/originator/employees/{publicId}/simulations` e `GET /api/v1/originator/simulations/{id}` — listar e buscar simulação          | Guarde a resposta de [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/criar-simulacao.md)                                                                                                                                                                    |
| `GET /api/v1/originator/employees/{publicId}/proposals` e `GET /api/v1/originator/proposals/{id}` — listar e buscar proposta               | Guarde a resposta de [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md)                                                                                                                                                                       |
| `PUT /api/v1/originator/employees/{publicId}` — atualizar employee (já descontinuado)                                                      | [Criar Employee](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md), que cadastra e atualiza por CPF                                                                                                                                                           |
| `GET /api/v1/originator/employees/{publicId}/contracts` — listar contratos                                                                 | [Buscar Contrato por Request Number ou Número da CCB](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md) e os webhooks `CONTRACT_*`                                                                                                        |
| `GET /api/v1/loan-limits` — limites de empréstimo                                                                                          | Nenhum. Os limites vigentes são aplicados pelas [regras de elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md) na simulação e na proposta                                                                                                                           |
| `GET` e `PUT /api/v1/originator/eligibility-rules` — regras de elegibilidade                                                               | Nenhum. As regras são configuradas pela Giro.Tech para o originador; o conceito segue em [Elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md)                                                                                                                       |

**Alterado**

* [Ajustar parcelas antes da migração automática](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md) é o novo nome de "Alterar contrato encerrado" (`POST /api/v1/originator/terminated-loan-alterations`). O endpoint não mudou; o nome passa a dizer o que ele faz na prática: ajustar número e valor das parcelas vincendas de um contrato na situação 15 para que ele migre já ajustado. O guia \[Renegociação por Término de Vínculo] foi substituído por [Migração Automática por Término de Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/migracao-automatica-termino-vinculo.md).

**Alterado** *(breaking)*

* Em [Transferências de Pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/transferencias-pagamento-por-contrato.md), o campo `verbasRescisorias` passa a se chamar **`fromSeverancePay`**, com o mesmo valor (`boolean`, nulo quando a Dataprev não informa). O nome antigo deixa de ser devolvido.

***

## 2026-09-18

### Contrato migrado é recusado na renegociação e na alteração

**Alterado**

* Renegociar contrato encerrado passa a recusar com `422 RENEGOTIATION_CLOSED_CONTRACT_MIGRATED` o contrato que a Dataprev já migrou para um vínculo novo. Antes a chamada era aceita com `202`, o contrato de renegociação era criado e a recusa chegava depois, pelo webhook `ENDORSEMENT_FAILED`, com o código `HZ` do provedor.
* [Alterar contrato encerrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md) passa a recusar o mesmo caso com `422 TERMINATED_LOAN_CONTRACT_MIGRATED`, sem chamar a Dataprev.

**Adicionado** *(aditivo, não-breaking)*

* Campo **`migrated`** em [Novos vínculos (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-global.md), [por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-por-contrato.md) e no payload de `TERMINATED_LOAN_NEW_BOND`. `employmentRelationship.actionable` continua descrevendo só o vínculo novo; é `migrated` que diz se o contrato encerrado ainda aceita renegociação.

### Leilão: número da proposta com o código Dataprev e `offerId` fora da resposta

**Alterado** *(aditivo, não-breaking)*

* O `proposalNumber` das ofertas de [leilão](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao.md) passa a ser `GT-{prefixo}-{único}`, sempre com 20 caracteres, em que o prefixo é o código Dataprev do seu originador (ex.: `GT-XX-7K3F9Q2M1ZX4AB`). Antes era `GT-{originatorId}-{único}`. Números já emitidos continuam válidos nas consultas.
* O `sourceId` das entregas do webhook [`AUCTION_OFFER_ACCEPTED`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#auction_offer_accepted) passa a ser o `proposalNumber` da oferta.
* Ao [criar uma proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md) (ou no `quote` de uma renegociação), um `proposalNumber` informado precisa ser uma oferta de leilão sua, para o mesmo trabalhador e a mesma `solicitationId`, ainda não convertida em contrato. Caso contrário a resposta é `422` com `errorCode` = `AUCTION_OFFER_NOT_FOUND`. `proposalNumber` vazio equivale a ausente.

**Removido / Descontinuado** — **Breaking**

* [Listar solicitações](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md) passa a trazer **somente** solicitações em `OPEN_FOR_OFFERS`. As demais (triagem, descartadas, expiradas, já ofertadas) deixam de aparecer; o parâmetro `status` continua aceito, e qualquer valor diferente de `OPEN_FOR_OFFERS` devolve página vazia.
* **`offerId`** sai de `AuctionOfferResponse` em [Listar ofertas e obter oferta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-ofertas.md). Era a chave interna da oferta; use o `proposalNumber`, que já endereça `GET /auction/offers/{proposalNumber}`.

### Número do contrato na Dataprev com o código do originador

**Alterado** *(aditivo, não-breaking)*

* `dataprevContractNumber` de contratos novos passa a vir no formato `GT<código><número da CCB>` (ex.: `GTNF00001192`) para originadores com código Dataprev cadastrado. O formato `<n>GT<número da CCB>` (ex.: `2GT00000028`) continua válido e os contratos já averbados mantêm o número. Trate o campo como identificador opaco — ver o padrão na renegociação.
* Na estratégia `ORIGINATOR_PROVIDED`, um `contractNumber` já usado por outro contrato do originador passa a responder `409` — `CONTRACT_NUMBER_ALREADY_USED` em [Criar contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md) e `RENEGOTIATION_CONTRACT_NUMBER_ALREADY_USED` em Renegociar empréstimo encerrado. Na renegociação, `contractNumber` ausente nessa estratégia responde `400` `RENEGOTIATION_CONTRACT_NUMBER_REQUIRED`.
* Na renegociação cuja raiz não comporta o sufixo `A<n>`, o número composto segue o mesmo padrão de contrato novo — antes era `<código>GT<número da CCB>` (ex.: `NFGT00000028`), agora `GTNF00000028`. Os exemplos das páginas de renegociação foram atualizados.

### Tipo do documento do empregador como enum

**Adicionado** *(aditivo, não-breaking)*

* **`employerTaxIdType`** (`CNPJ` / `CPF`) nos retornos que vêm de arquivo Dataprev: [lançamentos contábeis](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/lancamentos-contabeis-global.md), [transferências de pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/transferencias-pagamento-global.md), [empréstimos encerrados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-global.md) e [novos vínculos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-global.md). A migração automática ganhou o mesmo campo na entrada abaixo. É o mesmo campo e o mesmo enum que funcionário, margem e leilão já usam.

**Descontinuado**

* **`employerRegistrationTypeCode`** (`1` = CNPJ, `2` = CPF) sai da documentação desses retornos. O campo continua sendo enviado, para não quebrar quem já lê, mas deixa de fazer parte do contrato: use `employerTaxIdType`.

### Migração automática: CNPJ completo e vínculo na plataforma

**Adicionado** *(aditivo, não-breaking)*

* **`employerTaxId`**, **`employerTaxIdType`** e **`employmentRelationshipPublicId`** em `previousBond` e `currentBond` de [Migrações automáticas (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-global.md), [por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-por-contrato.md) e do webhook [`CONTRACT_MIGRATED_AUTOMATICALLY`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#contract_migrated_automatically). `employerTaxId` é o documento completo do empregador — o CNPJ da matriz quando a Dataprev entrega só a raiz —, com o mesmo sentido de `employerTaxId` na listagem de vínculos do empregado. `employmentRelationshipPublicId` vem quando o vínculo já existe na plataforma.

**Alterado**

* Numa migração encadeada (A→B e depois B→C), o `previousBond` de B→C passa a ser B — o destino da migração anterior do mesmo contrato —, e não mais o vínculo da averbação.
* **`previousBond.employerRegistrationNumber`** passa a vir como a raiz de 8 caracteres do CNPJ (ou o CPF), a mesma forma de `currentBond`, sempre que o documento guardado permite afirmá-la. Antes podia vir com 14 dígitos quando o vínculo da averbação foi cadastrado com o CNPJ completo. Pode vir `null` quando o documento guardado não permite afirmar a raiz — compare empregadores por `employerTaxId`.
* **Raiz de CNPJ alfanumérico** (CNPJ novo da Receita, 8 caracteres) passa a ser completada como matriz, como a numérica: aceita em [Cadastrar vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/cadastrar-vinculo.md), onde antes era recusada com `400`, e devolvida como `employerTaxId` completo nos vínculos que vêm da Dataprev.
* **Vínculo de** [**novos vínculos**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-global.md): o vínculo criado a partir da oportunidade passa a ter `employerTaxId` com o CNPJ da matriz, em vez da raiz com zeros à esquerda (`00000011222333`), e deixa de aparecer duplicado na listagem de vínculos do empregado quando a consulta de margem já tinha trazido o mesmo vínculo.

**Removido / Descontinuado**

* **`employerRegistrationTypeCode`** deixa de ser documentado em `previousBond`/`currentBond` da migração. O tipo do empregador passa a ser `employerTaxIdType` (`CNPJ`/`CPF`). O campo numérico continua na resposta por compatibilidade.

***

## 2026-09-17

### Contrato migrado e nova rescisão

**Alterado**

* **`migrated`** em [Empréstimos encerrados (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-global.md) e [por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-por-contrato.md) passa a considerar só migração **posterior à rescisão atual**. Um contrato que migrou e voltou a ser encerrado por uma nova rescisão aparece com `migrated: false`, porque está de novo na situação 15.

**Corrigido** *(documentação)*

* O contrato migrado **não** some da listagem de empréstimos encerrados, como diziam as entradas de 2026-09-10 e as páginas de término de vínculo: ele continua listado com `migrated: true`.
* Os valores de `guarantee` são repassados como a Dataprev devolve — não há garantia de que venham nulos sem garantia — e, fora da transferência de grupo econômico, a migração não leva nenhuma garantia, não só a de verbas rescisórias.

***

## 2026-09-16

### Migração automática: garantia depois da migração e o papel da alteração (Manual 018 v1.5)

O Manual de Comunicação 018 **v1.5** (15/09/2026) detalhou o que a migração automática faz com a garantia e com o desconto, e restringiu o uso da alteração de contrato encerrado.

**Adicionado** *(aditivo, não-breaking)*

* **`guarantee`** em [Migrações automáticas (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-global.md), [por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-por-contrato.md) e no webhook [`CONTRACT_MIGRATED_AUTOMATICALLY`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#contract_migrated_automatically): `hasGuarantees`, `fgtsBalanceAmount`, `fgtsPenaltyAmount` e `severancePercentage`, como a Dataprev os devolve **depois** da migração. Fora da transferência de grupo econômico a migração não leva a garantia; na transferência ela vai junto. Decida só por `hasGuarantees`. `guarantee: null` significa garantia não informada (migração lida antes desta versão ou resposta sem o bloco).

**Alterado** *(documentação; nenhum comportamento mudou)*

* [Alterar contrato encerrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md): a descrição da operação no OpenAPI dizia que ela ajustava a parcela "à margem do vínculo novo". Pela v1.5, a alteração serve só para refletir o que mudou no período sem vínculo elegível (ex.: amortização); readequar a parcela à margem do vínculo novo é refinanciamento depois da migração, que a API não expõe.
* A janela da alteração passa a citar a **transferência de grupo econômico** (motivos `11`, `12`, `13` e `43`), que migra assim que o desligamento é informado — na prática, sem janela.

### Prazo de assinatura da CCB definido pelo originador

Até agora o link de assinatura valia **7 dias**, fixos, para toda operação. Quem vende em ação de rua quer 48 horas — passado disso a margem consignável já pode ter sido consumida por outro empréstimo e a averbação recusa uma CCB assinada. Quem colhe assinatura via RH quer mais folga. Agora o prazo é por contrato.

**Adicionado** *(aditivo, não-breaking)*

* **`signatureExpirationDate`** em [Criar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md) — `string` no formato `yyyy-MM-dd`, opcional, não pode ser no passado. Devolvido também no `ContractResponse` e, portanto, em [Buscar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md) e Listar Contratos. Quem não enviar o campo continua com os mesmos **7 dias** de prazo de hoje.

**Alterado** *(mudança de comportamento — leia mesmo que você não use o campo novo)*

* **Contrato não assinado agora é encerrado quando o prazo vence.** O `documentStatus` vai a **`EXPIRED`**, o contrato é **cancelado** (`status` = `CANCELLED`) e o webhook **`CONTRACT_SIGNING_FAILED`** é entregue com `errorCode` = **`SIGNATURE_EXPIRED`** — o mesmo desfecho das demais falhas de assinatura. Antes, contrato não assinado ficava em `PENDING_SIGNATURE` indefinidamente e nenhum webhook era emitido.

{% hint style="warning" %}
**Isso vale também para quem não enviar `signatureExpirationDate`.** Sem o campo, o prazo continua sendo de 7 dias — o que muda é que, vencido esse prazo, o contrato passa a ser encerrado em vez de ficar parado. Se a sua integração trata contrato pendente como algo que permanece aberto, ou se ela ainda não consome `CONTRACT_SIGNING_FAILED`, vale revisar antes desta versão entrar.

O `errorCode` `SIGNATURE_EXPIRED` já constava no [catálogo de webhooks](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md), mas na prática nunca era emitido para contrato. Passa a ser.

Contratos criados **antes** desta versão não são afetados retroativamente: eles não têm prazo registrado e seguem como estão.
{% endhint %}

**Pontos de atenção**

* O prazo conta a partir da **geração do link**, não da criação do contrato — entre as duas coisas há a geração do PDF, que é assíncrona. O `201` da criação não confirma o prazo.
* **Reenviar o link não estende o prazo.** [Reenviar Link de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-giro/reenviar-link-assinatura.md) notifica de novo a mesma assinatura. Depois do vencimento ele responde `INVALID_STATUS`, e o caminho é criar um contrato novo.
* Data que já passou quando o link é gerado é **encurtada para o fim do dia corrente**, nunca estendida para o padrão de 7 dias.
* Na [assinatura gerenciada pelo originador](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador.md) o campo é aceito e devolvido, mas quem controla o prazo do link é o próprio originador.
* A verificação de vencimento é periódica: há uma defasagem de alguns minutos entre o prazo expirar e o `documentStatus` mudar.

***

## 2026-09-14

### Lançamentos contábeis: total e partes do desconto dividido no mesmo evento

O empregador pode dividir o desconto de uma parcela em mais de uma rubrica do mesmo evento de remuneração (S-1200), e cada rubrica chega como um lançamento separado. A Dataprev compara cada lançamento com a parcela inteira e marca `analysisInstallmentValueCorrect = false` em todas as partes, mesmo quando a soma bate.

**Adicionado** *(aditivo, não-breaking)*

Em cada item de [Lançamentos contábeis por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/lancamentos-contabeis-por-contrato.md) e [Lançamentos contábeis (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/lancamentos-contabeis-global.md):

* **`eventDeductionAmount`** — soma de `deductionAmount` dos lançamentos com o mesmo `eSocialEventId`, contrato e competência. Compare com `loanInstallmentValue` para saber se a parcela foi descontada inteira.
* **`eventEntryCount`** — quantos lançamentos compõem o evento.
* **`eventEntries`** — a lista desses lançamentos (`publicId`, `dataprevId`, `deductionAmount`), repetida em todos eles. Na consulta global as partes podem cair em páginas diferentes; a lista evita varrer as outras páginas.

**Sem mudança:** `deductionAmount` e as flags `analysis*` continuam exatamente como a Dataprev envia. Um desconto não dividido traz `eventEntryCount = 1` e `eventDeductionAmount` igual a `deductionAmount`.

***

## 2026-09-11

### `HW` deixou de somar a margem: a parcela da alteração não pode mais subir

O Manual de Comunicação 018 **v1.4** (10/09/2026) reescreveu a regra `HW` da [Alterar contrato encerrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md). O teto de `installmentAmount` era a **soma** da margem disponível atual com a parcela originalmente registrada; passou a ser **apenas** o valor da parcela registrada no contrato.

**Alterado** *(breaking para quem aumentava a parcela)*

* `installmentAmount` acima do valor registrado agora é recusado com **`422 TERMINATED_LOAN_INSTALLMENT_AMOUNT_ABOVE_REGISTERED`**, pela própria plataforma, sem chamada à Dataprev. A resposta traz `registeredInstallmentAmount` e `requestedInstallmentAmount`.
* Antes, esse caso ou passava (quando havia margem) ou voltava da Dataprev como `providerErrorCode` `HW` no webhook de falha. Quem dependia de aumentar a parcela precisa rever o cálculo.
* O valor de referência é o que a Dataprev reporta como registrado no contrato encerrado — numa segunda alteração, o que a primeira deixou lá.

**Sem mudança:** `BJ` (saldo devedor), `PL` (refinanciamento aberto) e `AO` (nome) continuam sendo avaliadas só pela Dataprev. A regra `HV` também consta como alterada no histórico da v1.4, mas a mudança foi de redação — o teto de parcelas segue sendo parâmetro do sistema da Dataprev.

***

## 2026-09-10

### Migração automática de contratos encerrados por término de vínculo

Desde setembro de 2026 a Dataprev move sozinha os contratos encerrados por término de vínculo para um vínculo novo ativo do mesmo trabalhador (Manual de Comunicação 018 §3), sem comando da instituição financeira. **Não existe endpoint para provocar nem para cancelar** — o que a plataforma entrega é como acompanhar o que já aconteceu.

Vale para contratos formalizados a partir de **24/07/2025** (Lei 15.179).

**Adicionado** *(aditivo, não-breaking)*

* **`GET /api/v1/originator/contracts/{contractPublicId}/dataprev/contract-migrations`** — [Migrações automáticas por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-por-contrato.md).
* **`GET /api/v1/originator/dataprev/contract-migrations`** — [Migrações automáticas (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/migracoes-automaticas-global.md), com paginação.
* **Evento** [**`CONTRACT_MIGRATED_AUTOMATICALLY`**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md)**.** `source` = `CONTRACT`; `sourceId` é o `publicId` do contrato quando o contrato migrado é seu, e o número do contrato na Dataprev quando não é. O payload traz `previousBond` e `currentBond` completos e o `migratedAt`.

{% hint style="danger" %}
**O contrato migrado desaparece da listagem de empréstimos encerrados.** Ele deixa a situação 15, e quem acompanha o funil só por [Empréstimos encerrados (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-global.md) vê o contrato sumir sem explicação. Assine o evento ou consulte as migrações.
{% endhint %}

{% hint style="warning" %}
**O contrato migrado não recebe número novo.** Diferente da renegociação, o `dataprevContractNumber` continua o mesmo — é isso que permite casar a migração com o empréstimo encerrado que você já acompanhava, e é por isso que o payload não tem campo de contrato novo.
{% endhint %}

**Alterado**

* **A renegociação manual** (Renegociar contrato encerrado) fica restrita a contratos averbados na vigência da MP 1.292 (12/03/2025) com previsão contratual e a contratos tombados. Para os demais, renegociar depois da migração responde erro do provedor.

## 2026-09-08

### Alteração de contrato encerrado antes da migração automática

A Dataprev passou a migrar sozinha os contratos encerrados por término de vínculo para um vínculo novo ativo do trabalhador, sem comando da instituição financeira (Manual de Comunicação 018 §3). O que fica com o originador é ajustar o plano de pagamento **antes** de ela mover — para que o contrato migre com parcela e prazo que caibam na margem do vínculo novo.

**Adicionado** *(aditivo, não-breaking)*

* **`POST /api/v1/originator/terminated-loan-alterations`** — [Alterar contrato encerrado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/alterar-emprestimo-encerrado.md). Altera **exclusivamente** `numeroParcelas` e `valorParcela` de um empréstimo na situação 15. Não migra nada, não cria contrato, e o empréstimo permanece na situação 15. `202`, não `201`.
* **`GET /api/v1/originator/terminated-loan-alterations/{publicId}`** — [Consultar alteração](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/consultar-alteracao-emprestimo-encerrado.md).
* **Eventos** [**`TERMINATED_LOAN_ALTERED` e `TERMINATED_LOAN_ALTERATION_FAILED`**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md)**.** `source` = `CONTRACT`, `sourceId` = `publicId` da alteração.

{% hint style="warning" %}
**A janela é curta e não reabre.** Depois que a Dataprev migra o contrato, ele sai da situação 15 e a alteração é recusada com `HZ`. Contrato com garantia migra a partir do **21º** ou do **31º dia** após o desligamento; sem garantia, imediatamente. Não há correção depois.
{% endhint %}

{% hint style="info" %}
A regra `HW` limita `valorParcela` à **soma** da margem disponível atual com a parcela original — ou seja, a parcela **pode subir**, não está presa ao valor original. O manual não diz de qual vínculo é essa margem, e a plataforma não avalia `HW` localmente: o valor pedido é encaminhado e a Dataprev decide, devolvendo `HW` em `providerErrorCode` quando recusa.
{% endhint %}

***

## 2026-09-03

### Execução de garantia FGTS visível para o originador

Quando o vínculo termina, a garantia constituída na averbação — saldo de FGTS e/ou multa rescisória — pode ser executada junto à Dataprev. A execução já acontecia; o originador é que não tinha como saber dela: não havia evento, não havia endpoint, e a execução deliberadamente não altera o status do contrato.

**Adicionado** *(aditivo, não-breaking)*

* **Evento** [**`GUARANTEE_EXECUTED`**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md)**.** Disparado quando a Dataprev aceita a execução da garantia. Traz o `protocol`, a `transferForecastDate` e os valores efetivamente executados. `source` = `CONTRACT`, `sourceId` = `publicId` do contrato.
* **`GET /api/v1/originator/contracts/{publicId}/guarantee-execution`** — [Consultar execução de garantia](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/consultar-execucao-de-garantia.md). Consulta sob demanda do mesmo resultado, para reconciliação. Contrato sem execução responde `404` com `errorCode` `GUARANTEE_EXECUTION_NOT_FOUND`.

{% hint style="warning" %}
A execução é **irreversível** e a Dataprev permite **uma por contrato** — não existe evento de reversão, e o mesmo contrato não gera uma segunda entrega. `transferForecastDate` é previsão, não confirmação de repasse recebido: conciliar o valor que entrou continua sendo do integrador. E a execução **não** dá baixa na dívida nem muda o status do contrato.
{% endhint %}

{% hint style="info" %}
`protocol` trafega como **string**, não número: são até 32 dígitos, que não cabem em inteiro de 64 bits. Ler o campo como inteiro corrompe o valor em silêncio.
{% endhint %}

***

## 2026-08-26

### Renegociação por término de vínculo em uma única chamada

A renegociação publicada em 2026-08-23 exigia criar uma proposta antes e endereçava a oportunidade por um identificador que não servia para nada mais. As duas coisas mudam, e a listagem de novos vínculos muda de rota junto.

**Alterado** *(**breaking**)*

* **`POST /api/v1/originator/proposals/{proposalPublicId}/renegotiations` → `POST /api/v1/originator/renegotiations`.** A precificação vai pronta no bloco `quote` — o mesmo corpo de [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md) — e não é preciso criar proposta antes: ela nasce na mesma transação dos guards, então renegociação recusada não deixa proposta órfã. Não há trabalhador nem proposta no path; quem seleciona os dois é o `quote.employmentRelationshipPublicId`.
* **`GET /api/v1/originator/dataprev/new-bonds` → `GET /api/v1/originator/dataprev/new-employment-relationships`**, e o mesmo para a variante por contrato.
* **O campo `newBondPublicId` deixa de existir.** Ele endereçava a linha de oportunidade, que não é o que o chamador precisa endereçar. O bloco `newBond` de cada item virou **`employmentRelationship`** e carrega o próprio **`publicId`** como primeiro campo — antes o identificador do vínculo ficava um nível acima do objeto que ele identifica.
* O `publicId` do vínculo vem `null` quando o empréstimo encerrado é de outra instituição (`closedLoanSource = INGESTED`): esse caso não é renegociação, é portabilidade.

**Corrigido**

* O `publicId` do vínculo novo passa a existir **desde a primeira leitura** da listagem. Antes ele dependia de uma varredura assíncrona, e uma oportunidade recém-descoberta podia aparecer sem identificador — deixando visível algo que ainda não era acionável.

{% hint style="warning" %}
`quote.insuranceAmount` é **obrigatório** quando `quote.simulationPublicId` não é informado. Sem ele a resposta é `400`.
{% endhint %}

***

## 2026-08-25

### Cadastro de vínculo empregatício com margem de outro provedor

Originador que consulta a margem em outro provedor agora pode cadastrar o vínculo diretamente, sem consumir uma consulta de margem da plataforma. O vínculo criado é referenciado em `employmentRelationshipPublicId` na criação da proposta e é o que alimenta a averbação.

**Adicionado** *(aditivo, não-breaking)*

* [Cadastrar Vínculo Empregatício](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/cadastrar-vinculo.md) — `POST /api/v1/originator/employees/{publicId}/employment-relationships`. Obrigatórios: `registrationNumber`, `employerTaxId`, `employerTaxIdType` e `availableMargin` — exatamente o que a averbação consome, mais a margem conferida antes dela.
* `employerTaxId` aceita o documento do empregador nas formas em que ele costuma chegar: completo, com máscara, raiz de 8 dígitos ou com os zeros à esquerda truncados. A plataforma guarda o documento completo como identidade do vínculo e preserva a forma recebida para a averbação.
* Idempotente pela chave `registrationNumber` + `employerTaxId`: reenviar o mesmo par atualiza o vínculo (`200`) em vez de duplicá-lo (`201`), inclusive entre formas diferentes do mesmo documento.

**Pontos de atenção**

* O endpoint substitui a **consulta de margem**, não a **autorização** — o trabalhador continua precisando autorizar a Giro na Dataprev.
* `usableMargin` não é campo de entrada: é derivada de `availableMargin`.
* Vínculo encerrado não é reativado por este endpoint (`409`, `EMPLOYMENT_RELATIONSHIP_NOT_ACTIVE`).
* Enquanto não houver uma consulta de margem da plataforma, o vínculo não é elegível a renegociação.

***

## 2026-08-24

### Consulta de empréstimos encerrados por término de vínculo

A Dataprev encerra o empréstimo quando o vínculo empregatício do trabalhador termina (`situacaoEmprestimo.codigo = 15`). Até aqui esse encerramento só era visível de forma indireta, pelo bloco `terminatedContract` das listagens de novos vínculos — o que exigia um vínculo novo já capturado. Agora ele é consultável diretamente e notificado por webhook.

**Adicionado** *(aditivo, não-breaking)*

* `GET /api/v1/originator/contracts/{contractPublicId}/dataprev/terminated-bond-loans` — o encerramento registrado para o empréstimo de um contrato. Ver [Empréstimos encerrados por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-por-contrato.md).
* `GET /api/v1/originator/dataprev/terminated-bond-loans` — todos os encerramentos do originador, com paginação e filtro por `updatedFrom`/`updatedTo` sobre a data de atualização na Dataprev. Ver [Empréstimos encerrados (global)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/emprestimos-encerrados-global.md).
* Evento de webhook `CONTRACT_TERMINATED_BOND` (`source` = `CONTRACT`), disparado quando a varredura encontra um empréstimo encerrado por término do vínculo. Ver [Webhooks — Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

Ambas as listagens incluem encerramentos cujo contrato **não existe** na plataforma — empréstimos de terceiros conhecidos apenas pela varredura. Nesses casos `contractNumber` e `requestNumber` vêm nulos e o `dataprevContractNumber` é o único identificador.

O campo `installmentAmount` é o teto da parcela numa renegociação do empréstimo encerrado, e para empréstimo de terceiro estas são as únicas fontes desse valor.

## 2026-08-23

### Renegociação de contrato encerrado por término de vínculo

Novo fluxo para mover o saldo de um empréstimo encerrado por término de vínculo (situação 15 na Dataprev) para o novo vínculo do trabalhador. Guia completo em Renegociação por Término de Vínculo.

**Adicionado** *(aditivo, não-breaking)*

* `POST /api/v1/originator/proposals/{proposalPublicId}/renegotiations` — Renegociar contrato encerrado. Responde `202`: o contrato nasce síncrono, a operação na Dataprev é assíncrona.
* `GET /api/v1/originator/renegotiations/{contractPublicId}` — Consultar renegociação, com o bloco `outcome` (código, mensagem e hash da Dataprev) quando o resultado chega.
* O `numeroContrato` da renegociação na Dataprev deriva do contrato encerrado com sufixo `A<n>` (ex.: `XXGT00000001` → `XXGT00000001A1`). `dataprevContractNumber` e `contractNumber` **não se correspondem** neste fluxo — ver o padrão.
* O resultado sai pelos webhooks já existentes `ENDORSEMENT_ENDORSED` / `ENDORSEMENT_FAILED`. Não há assinatura, formalização nem desembolso: `ENDORSED` é terminal.

***

### Adicionado

* **`publicId` (UUIDv7) nas entidades que ainda não tinham**: documento de autorização (`authorizationDocumentPublicId` no upload; `publicId` no response), subscription e entregas de webhook. Respostas de contrato, proposta e simulação ganham `employeePublicId`; o contrato da API de origination ganha `proposalPublicId`; o upload de contrato assinado responde `contractPublicId`. Campos podem vir ausentes até o backfill alcançar registros antigos.
* `GET /api/v1/originator/proposals/{publicId}` passa a aceitar o identificador público (o numérico legado segue aceito na janela de depreciação).

### Removido / Descontinuado

* **Identificadores numéricos internos saíram da documentação** — a referência, os exemplos e as collections Postman passam a usar exclusivamente os identificadores públicos (`publicId`, `simulationPublicId`, `employmentRelationshipPublicId`, `bondPublicId`, `proposalPublicId`, `contractPublicId`). Os campos numéricos (`id`, `simulationId`, `employmentRelationshipId`, `bondId`, `relationshipId`, `proposalId`) continuam sendo **aceitos e retornados pela API por janela de depreciação**, mas não devem mais ser usados em integrações novas. As entradas antigas deste changelog preservam os nomes vigentes à época.

## 2026-08-19

### Parcela da proposta aceita os campos bancários do documento

Cada item de `installments` em [Criar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md) passa a aceitar quatro campos opcionais que a Giro repassa ao banco emissor na formalização da CCB, sem interpretar nem validar além do tamanho.

**Adicionado** *(aditivo, não-breaking)*

* `documentNumber` (máx. 10) — número identificador do vencimento.
* `ourNumber` (máx. 32) — nosso número do documento no banco emissor.
* `ourNumberBankCode` (máx. 3) — código do banco do nosso número.
* `participantControl` (máx. 25) — controle do participante.
* Os quatro são devolvidos como enviados em Buscar Proposta e Listar Propostas.
* Campo omitido não é enviado ao banco emissor. A exceção é `documentNumber`: sem ele a plataforma continua gerando `{contractNumber}{installmentNumber}`, como antes — informe o seu valor para sobrescrever.

## 2026-08-17

### `requestId` das consultas Dataprev passa a ser UUID v7

O `requestId` retornado pelas consultas assíncronas sob demanda — [Consultar Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md), [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md) e [Consultar FGTS Disponível](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md) — e devolvido nos webhooks correspondentes passa a ser um **UUID v7 de 36 caracteres**, no lugar do id de 16 caracteres Base64 URL-safe usado até aqui.

**Alterado** *(breaking para quem valida tamanho fixo)*

* Requisições novas passam a receber `requestId` no formato UUID v7 (ex.: `0198f2b3-6e91-7c44-8a2d-5f7b9c3e1a06`).
* Requisições já existentes **continuam retornando o `requestId` de 16 caracteres** — o campo não é reescrito. As duas gerações coexistem permanentemente: consultas históricas seguem válidas com o id antigo.
* **Se sua integração valida `requestId` com tamanho fixo de 16 caracteres, ela vai quebrar.** Trate `requestId` como uma string opaca de 16 a 36 caracteres, sem assumir um tamanho fixo.

## 2026-08-16

### Novos vínculos de contratos encerrados

Um contrato encerrado por término de vínculo cujo CPF voltou a ter vínculo empregatício passa a aparecer como oportunidade na API — em duas listagens e em um evento de webhook.

**Adicionado** *(aditivo, não-breaking)*

* Endpoint **`GET /api/v1/originator/contracts/{contractPublicId}/dataprev/new-employment-relationships`** — [Novos vínculos por contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-por-contrato.md). Retorna as oportunidades ligadas ao empréstimo encerrado do contrato. Array vazio enquanto o contrato não foi encerrado pela Dataprev ou o CPF ainda não tem novo vínculo capturado.
* Endpoint **`GET /api/v1/originator/dataprev/new-employment-relationships`** — [Novos vínculos global](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/termino-de-vinculo/novos-vinculos-global.md). Página com todas as oportunidades do originador. Filtros `foundFrom`, `foundTo`, `actionable` e `taken`; ordenação por `availableMarginAmount` ou `foundAt`, padrão `availableMarginAmount,desc`.
* Evento [**`TERMINATED_LOAN_NEW_BOND`**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#terminated_loan_new_bond) e o `source` de mesmo nome, ambos novos. Emitido quando a varredura casa um novo vínculo com um empréstimo encerrado por término de vínculo. O campo acionável do payload é o `employmentRelationshipPublicId`, o mesmo que volta em `quote.employmentRelationshipPublicId` na renegociação.

{% hint style="info" %}
**Use `actionable`, não `eligible`.** Nestas respostas, `eligible=false` com `ineligibilityReasonCode=8` é o corpo normal — a oportunidade existe justamente porque a Dataprev marca o novo vínculo como inelegível por já haver um empréstimo encerrado por término de vínculo. Na listagem global, `actionable` é o único filtro de elegibilidade: não existe parâmetro `eligible`.
{% endhint %}

***

## 2026-08-11

### `forceRefresh` removido da consulta de margem por vínculo

**Removido** *(breaking)*

* O campo **`forceRefresh`** do corpo de `POST /api/v1/originator/employees/{publicId}/authorized-bonds/{bondId}/margin-queries` **não existe mais**. O corpo aceita apenas `forceIneligible`.
* Remova `forceRefresh` do corpo. Para atualizar o employee inteiro, use [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) (`POST /employees/{publicId}/margin`).

### `GET /margin` read-only para todas as integrações

**Alterado** *(breaking)*

* O `GET /employees/{publicId}/margin` é **read-only para todos** — não há mais ativação por integração.
* Sem margem disponível e sem consulta em andamento, responde `422` com `errorCode: MARGIN_REFRESH_REQUIRED`. Chame [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) e aguarde o webhook.

### Bloco `disbursementReview` no webhook `PAYMENT_REVISION`

**Adicionado** *(aditivo, não-breaking)*

* Bloco **`disbursementReview`** no `data` do evento [`PAYMENT_REVISION`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_revision), em camelCase, com `ticket`, `createdAt`, `expiresAt` e **`availableActions`**. É o contrato estável do evento — o bloco `dados` continua sendo repasse verbatim do GTBanker, em português, e permanece inalterado.
* Campo **`availableActions`** (array): `NEW_ACCOUNT` (informar conta ou PIX ainda não usados na operação) e `RETRY` (reenviar a mesma conta da tentativa que falhou, só em instabilidade bancária). Ticket emitido antes desta mudança chega como `["NEW_ACCOUNT"]`, o comportamento histórico.
* Regras de aceitação da emenda em [Atualizar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md): ticket de uso único, prazo `expiresAt`, e recusa de conta reaproveitada de tentativa anterior.

**Corrigido**

* Documentado o **503** de `PUT /api/v1/originator/disbursement-accounts` (`UPSTREAM_SERVER_ERROR_GTBANKER` / `SERVICE_UNAVAILABLE_GTBANKER`), que já era retornado mas não constava no contrato. É seguro retentar em ambos os casos: com `SERVICE_UNAVAILABLE_GTBANKER` a requisição não chegou ao GTBanker e o ticket segue válido até `expiresAt`; com `UPSTREAM_SERVER_ERROR_GTBANKER` não há como saber se a emenda foi aplicada antes da falha, e como o ticket é de uso único a retentativa pode responder **400**.
* Documentado que a recusa de negócio do GTBanker no modo `ticket` retorna **400 sem `errorCode`**, com o motivo em texto livre em `detail` — os casos não são distinguíveis programaticamente.

### Verificação de CPF por `POST` com o CPF no corpo

O CPF sai da URL. A verificação de cadastro passa a ser um `POST` que recebe o CPF no corpo da requisição.

**Adicionado** *(aditivo, não-breaking)*

* Endpoint **`POST /api/v1/originator/employees/lookup`** — [Verificar Employee por CPF](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/verificar-cpf.md). Recebe `{"cpf": "..."}` no corpo e devolve o mesmo contrato de resposta do endpoint anterior: `exists` e, quando encontrado, `publicId`. Sempre `200 OK`. Rate limit igual ao do endpoint anterior.

**Removido / Descontinuado** *(**breaking** na remoção — ver abaixo)*

* **`GET /api/v1/originator/employees/by-cpf/{cpf}` está descontinuado.** Continua funcionando, com o mesmo comportamento e o mesmo contrato de resposta, e está marcado como `deprecated` no OpenAPI. **Será removido em uma release futura**, anunciada com antecedência neste changelog.

{% hint style="warning" %}
**Por que a mudança:** o CPF no path é um dado pessoal que fica registrado fora da aplicação — logs de acesso do servidor e do ingress, proxies e CDNs intermediários, histórico do navegador e cabeçalhos `Referer`. No corpo de um `POST` sobre HTTPS ele não vai para nenhum desses lugares.

**O que quebra e quando:** nada quebra agora — o `GET` antigo continua atendendo. Quando ele for removido, toda chamada a `GET /employees/by-cpf/{cpf}` passará a responder `404`.

**Como migrar** (três alterações, nenhuma no tratamento da resposta):

1. Método: `GET` → `POST`.
2. URL: `/api/v1/originator/employees/by-cpf/{cpf}` → `/api/v1/originator/employees/lookup` (sem o CPF).
3. Corpo: enviar `{"cpf": "12345678901"}` com `Content-Type: application/json`.

Autenticação, códigos de status e formato da resposta são idênticos. Um `cpf` ausente ou fora do pattern `^\d{11}$` responde `400`, como antes.
{% endhint %}

***

## 2026-08-07

### Atualização explícita de margem e `GET /margin` read-only

Pedir uma margem nova deixa de ser efeito colateral do `GET` e passa a ser uma chamada própria.

**Adicionado** *(aditivo, não-breaking)*

* Endpoint **`POST /api/v1/originator/employees/{publicId}/margin`** — [Solicitar Atualização de Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md). Dispara uma consulta por vínculo elegível. Responde `202` (`status: PROCESSING`) com `requestId` / `requestIds`, ou `200` quando encerra sem consulta pendente (`NO_BONDS`, `NOT_ELIGIBLE`, …). Tem rate limit próprio, menor que o do restante da API.
* Novo `errorCode` **`MARGIN_REFRESH_REQUIRED`** no catálogo de [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

**Alterado** *(**breaking** na ativação — ver abaixo)*

* O **`GET /api/v1/originator/employees/{publicId}/margin` passa a ser read-only**: lê a margem disponível (`200`), informa consulta em andamento (`202`) ou responde **`422 MARGIN_REFRESH_REQUIRED`** quando não há nem uma coisa nem outra. Ele deixa de disparar a consulta ao Dataprev. Ver [O `GET` read-only](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#o-get-read-only).

{% hint style="warning" %}
**O que quebra:** um estado que hoje devolve `202 PROCESSING` e converge sozinho em polling de `GET` passa a devolver `422`, e o `GET` não converge mais por conta própria — um laço só de `GET` fica preso. Trate `422 MARGIN_REFRESH_REQUIRED` como "chame o `POST`", não como erro fatal.

**Ativação por originador.** A mudança entra desligada e é habilitada **uma integração por vez**, com data combinada previamente. Até a sua ativação o `GET` mantém o comportamento atual (`200`/`202`, ainda disparando a consulta), e o `POST` já está disponível — dá para migrar antes.
{% endhint %}

A primeira consulta de margem continua sendo disparada automaticamente após a autorização Dataprev, com o resultado no webhook `MARGIN_QUERY_COMPLETED`. Nada muda aí.

***

## 2026-08-05

### Campos `rejectionReason` e `cancelReason` no ContractResponse

**Adicionado** *(aditivo, não-breaking)*

* Campo **`rejectionReason`** (`string`, nullable) em `ContractResponse`: motivo da pendência de desembolso, em texto livre. Preenchido apenas por `PAYMENT_REVISION` / `PAYMENT_FAILURE`; `null` nos demais casos — inclusive em contratos `CANCELLED`. Limpo automaticamente em `PAYMENT_SUCCESS`. Ver detalhes em [Buscar Contrato por Request Number / CCB](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md) e [Webhooks — Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).
* Campo **`cancelReason`** (`string`, nullable) em `ContractResponse`: motivo do cancelamento do contrato, em texto livre. Preenchido quando o contrato vai a `CANCELLED` com um motivo registrado (ex.: `Cancelado pelo funcionário`). `null` enquanto o contrato não for cancelado.
* Campos documentados em todas as páginas de resposta de contrato: [Buscar Contrato por Request Number / CCB](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md), Listar Contratos, [Criar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md) e [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/cancelar-contrato.md).

***

## 2026-07-29

### Enums Dataprev (margem e homologação)

Documentação completa dos mapeamentos entre códigos numéricos Dataprev e valores string expostos na API.

**Adicionado** *(aditivo, não-breaking)*

* [Categoria do Trabalhador (`WorkerCategory`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/categoria-trabalhador.md) — 46 categorias.
* [Motivo de Desligamento (`TerminationReason`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-desligamento.md) — 49 códigos.
* [Motivo de Inelegibilidade (`IneligibilityReason`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/motivo-inelegibilidade.md) — 8 códigos (inclui código 8 antes ausente).
* [Pessoa Exposta Politicamente (`PoliticallyExposedPerson`)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/pessoa-exposta-politicamente.md).
* Índice [Enums da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums.md) e links a partir de margem, create-worker e glossário.

**Corrigido**

* OpenAPI `politicallyExposedPerson`: valores alinhados ao código (`EXPOSED_LEVEL_1`, `EXPOSED_LEVEL_2` em vez de `EXPOSED`/`RELATED`).

***

## 2026-09-01

### Atributos de elegibilidade para cessão

**Adicionado** *(aditivo, não-breaking)* — bloco opcional `eligibilityAttributes` no payload de criação de contrato, com 20 campos sobre empregador, trabalhador e operação.

Os dados não são usados pelo GTPayroll: são repassados ao Fundo que adquire o recebível, e é ele quem os utiliza na avaliação do crédito.

O bloco e cada um dos campos são opcionais. Integrações existentes seguem funcionando sem mudança — contrato criado sem o bloco é cedido normalmente, apenas sem as informações complementares.

Ver [Atributos de Elegibilidade para Cessão](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/atributos-de-cessao.md) para a lista completa de campos, os valores aceitos nos enums e exemplo de payload.

***

## 2026-07-28

### Autorização sempre gerenciada pelo originador

A assinatura da autorização Dataprev passa a ser **sempre coletada pelo originador**. O fluxo em que a Giro coletava a assinatura do termo (link B2B, reenvio de link) sai da documentação, e a autorização passa a ter dois caminhos: [**Termo em PDF**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf.md) (gerado por você ou pela Giro) e [**Termo em Trilha Opt-In**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in.md). A assinatura do **contrato (CCB)** não muda — continua com as estratégias `GIRO` e `ORIGINATOR_MANAGED`.

**Removido / Descontinuado** *(breaking a prazo — endpoints ainda respondem)*

* `POST /api/v1/originator/employees/{publicId}/authorization-documents/sign` (gerar link de assinatura B2B) — removido da documentação e do spec OpenAPI.
* `POST /api/v1/originator/employees/{publicId}/authorization/resend` (reenviar link de autorização) — removido da documentação e do spec OpenAPI.
* `POST /api/v1/originator/employees/{publicId}/authorization` (enviar autorização / retry manual) — removido da documentação e do spec OpenAPI. O envio à Dataprev **já era automático** nos três caminhos de autorização; este endpoint existia apenas como retry manual.
* `PUT /api/v1/originator/employees/{publicId}` (atualizar employee) — marcado como `deprecated`. Use `POST /api/v1/originator/employees`, que é **idempotente por CPF**: retorna `201` ao criar e `200` ao reusar, atualizando parcialmente os campos enviados.
* Webhook `AUTHORIZATION_SIGN_URL_READY` e a variante `SIGNATURE_LINK_RESEND` com `source = AUTHORIZATION_DOCUMENT` — descontinuados junto com o fluxo. O `SIGNATURE_LINK_RESEND` de **contrato** continua ativo.

**Alterado** *(aditivo, não-breaking)*

* [Criar Employee](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md) passa a documentar o comportamento **idempotente por CPF** (`201` cria, `200` reusa e atualiza parcialmente, `409` quando o employee está inativo) e ganha exemplo do caminho de **trilha de opt-in**, ao lado do de PDF assinado em Base64 que já existia.
* [Criar Documento de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/criar-documento-autorizacao.md) passa a descrever apenas o caminho em que **a Giro gera o termo**, deixando explícito que o `201` volta com `status: PENDING` e o termo ainda não existe.

### Enviar termo sempre reautoriza

Enviar um termo de autorização significa "coletei um novo aceite". A partir de agora isso **sempre** cria um `nsu` novo, reautoriza na Dataprev e dispara uma **consulta de margem nova**, mesmo que o trabalhador já tenha autorização válida. Vale para os três caminhos que recebem termo: `signed-authorizations`, `authorization-trails` e o bloco `authorization` embutido no `POST /employees`.

Antes, um reenvio para trabalhador já autorizado era descartado em silêncio: a resposta vinha `200 ALREADY_AUTHORIZED` e **nenhum webhook era emitido**.

**Alterado** *(breaking)*

* [`POST .../signed-authorizations`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md) e [`POST .../authorization-trails`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md) não retornam mais `200` com `status: ALREADY_AUTHORIZED` — a resposta é **sempre `202` com `status: PROCESSING`** e um `nsu` novo. Quem trata `ALREADY_AUTHORIZED` como "nada a fazer" precisa remover esse ramo.
* O campo `authorizationExpiresAt` sai das respostas desses dois endpoints; ele só existia para o caso `ALREADY_AUTHORIZED`. Para consultar validade, use [Consultar Status da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md).
* O bloco `authorization` do [Criar Employee](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md) passa a devolver `status` sempre `PROCESSING`.

**Corrigido**

* Reenvio de termo para trabalhador já autorizado voltou a emitir os webhooks: `AUTHORIZATION_COMPLETED` seguido de um `MARGIN_QUERY_COMPLETED` por vínculo, **a cada envio**.

{% hint style="warning" %}
**Tem custo.** Cada envio de termo consome chamadas reais na Dataprev (autorização + margem). Quem só quer garantir o cadastro do trabalhador deve **omitir** o objeto `authorization` no `POST /employees`.
{% endhint %}

***

## 2026-07-27

### Envio direto do termo de autorização já assinado

Novo endpoint para originadores `ORIGINATOR_MANAGED` que já possuem o termo assinado gerado pelo próprio sistema: o PDF assinado é enviado em **uma única chamada**, sem `Criar Documento` e sem `upload-signed`.

**Adicionado** *(aditivo, não-breaking)*

* [`POST /api/v1/originator/employees/{publicId}/signed-authorizations`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md): recebe o PDF assinado em base64 (`signedDocument`), valida o CPF (`documentNumber`) contra o employee, gera o `nsu` na própria chamada, cria o documento já em `SIGNED` e dispara a autorização Dataprev automaticamente. Retorna `202` com `status: PROCESSING` ou `200` com `status: ALREADY_AUTHORIZED` quando o trabalhador já está autorizado. Campos opcionais: `fileName` e `signedAt`. Exige `authorizationSignatureStrategy = ORIGINATOR_MANAGED` (senão `403`).

> O `200`/`ALREADY_AUTHORIZED` descrito acima foi **superado em 2026-07-28**: o endpoint passou a responder sempre `202`/`PROCESSING`. Ver [Enviar termo sempre reautoriza](#enviar-termo-sempre-reautoriza).

***

## 2026-07-24

### Autorização no cadastro de employee

O `POST /api/v1/originator/employees` passa a aceitar um objeto opcional `authorization` que dispara automaticamente o fluxo de autorização Dataprev junto com o cadastro, por um de dois caminhos mutuamente exclusivos: `trail` (trilha de opt-in) ou `signedDocumentBase64` (PDF assinado em Base64). O disparo é **atômico** — se a autorização falhar, o cadastro inteiro é revertido e a API responde com erro (`403` originador não habilitado/sem permissão, `422` autorização inválida, `400` payload inválido) em vez de `201`.

**Adicionado** *(aditivo, não-breaking)*

* Campo opcional `authorization` no request de `POST /api/v1/originator/employees`, com `trail` **ou** `signedDocumentBase64` (no máximo um; ambos → `400`).
* Bloco `authorization` no `201` (`status`, `nsu`, `dataprevAuthorizationStatus`) quando o disparo ocorre.
* Novo código `422` no endpoint: autorização inválida (CPF da trilha divergente do employee ou documento que não é PDF) — reverte o cadastro.

Ver [Criar Employee](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md).

## 2026-07-20

### Consulta de margem — campos de identidade do trabalhador

Os retornos de margem passam a expor dados de identidade do trabalhador já persistidos pela Dataprev, alinhando `GET /margin`, webhook `MARGIN_QUERY_COMPLETED` e `GET /margin-queries/{requestId}`.

**Adicionado** *(aditivo, não-breaking)*

* [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) e webhook **`MARGIN_QUERY_COMPLETED`**: cada item de `employmentRelationships[]` passa a incluir os campos opcionais `birthDate`, `motherName` e `gender` (além de `activeConsignmentsCount`, já documentado).
* [`GET /margin-queries/{requestId}`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md): o objeto `relationship` passa a incluir `birthDate`, `motherName`, `gender` e `activeConsignmentsCount`.

***

## 2026-07-19

### Payload do webhook `AUCTION_SOLICITATIONS_REFRESHED` simplificado — **breaking**

* **Alterado (breaking).** O campo `data` do evento passa a conter **um único campo, `refreshedCount`**. Os campos `discovered`, `persistedNew`, `skipped`, `windowStart` e `windowEnd` **não são mais enviados**.

  Antes:

  ```json
  { "discovered": 12, "persistedNew": 3, "skipped": false,
    "windowStart": "2026-06-12T12:00:00Z", "windowEnd": "2026-06-13T12:00:00Z" }
  ```

  Agora:

  ```json
  { "refreshedCount": 3 }
  ```

  O envelope (`source` = `AUCTION`, `eventType`, `sourceId` = `originatorId`) permanece igual.

  **Ação necessária:** ajuste a desserialização do evento. Se sua integração decide algo a partir de `persistedNew` — por exemplo, só consultar a listagem quando havia solicitações novas —, note que **`refreshedCount` não é equivalente**: ele conta solicitações que **mudaram de estado**, incluindo as descartadas por inelegibilidade. Consultar [Listar Solicitações](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md) ao receber o evento continua sendo a forma correta de saber o que está disponível para oferta.

  **Quando o evento é enviado:** antes, ao concluir uma atualização sob demanda ou uma varredura periódica que encontrasse novidades. Agora, quando a varredura de elegibilidade da plataforma processa solicitações recém-ingeridas — somente se ao menos uma mudou de estado.

### Endpoint de atualização do leilão removido — **breaking**

* **Removido (breaking).** `POST /api/v1/originator/auction/solicitations/refresh` **deixou de existir** e passa a responder `404`.

  O endpoint permitia forçar uma varredura na Dataprev sem esperar o ciclo automático. A ingestão de solicitações passou a ser contínua e independente do ciclo da API, então não há substituto — e nem necessidade dele.

  **Ação necessária:** remova as chamadas ao endpoint. Para saber de novas solicitações, reaja ao webhook `AUCTION_SOLICITATIONS_REFRESHED` ou consulte [Listar Solicitações](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/listar-solicitacoes.md) periodicamente.

***

## 2026-07-04

### Coleção Postman de eventos de webhook

* Nova coleção **`GTPayroll-Webhook-Events`** publicada nos assets do GitBook — um request POST por `eventType`, com envelope `{ source, eventType, data }` e autenticação via variáveis `webhook_url`, `auth_header_key` e `auth_header_value`. Ver [Webhooks — Collection Postman](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks.md#collection-postman) e [README](https://docs.giro.tech/desenvolvedores/api-gtpayroll.md).

***

## 2026-07-03

### Correção de conta de desembolso sem ticket + esclarecimento do CONTRACT\_FORMALIZATION\_FAILED

`PUT /api/v1/originator/disbursement-accounts` passa a aceitar `ticket` **opcional**. Quando a formalização de um contrato falha por dado incorreto (ex.: chave Pix), o originador pode chamar o endpoint sem `ticket` para corrigir a conta — a plataforma reenvia a formalização automaticamente, sem precisar aguardar nenhum evento do GTBanker. Ver [Atualizar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md).

**Alterado** *(aditivo, não-breaking)*

* `ticket` deixa de ser obrigatório em `PUT /api/v1/originator/disbursement-accounts`. Enviado, comportamento inalterado (amend pós-formalização via GTBanker). Omitido, novo comportamento: corrige `pix`/`bankAccount` do contrato e reenvia a formalização — só válido quando a formalização está `FAILED`/`RETRYING` (senão `422`, `errorCode: FORMALIZATION_NOT_CORRECTABLE`).
* Esclarecida a descrição do webhook `CONTRACT_FORMALIZATION_FAILED`: o gatilho é o esgotamento de tentativas do contrato (cobre tanto o processamento normal da formalização quanto o scheduler de retry), não uma fila específica. `reason` agora documentado como podendo trazer o erro real da última tentativa (ex.: mensagem de recusa do GTBanker) em vez de só o texto genérico de esgotamento. Ver [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#contract_formalization_failed).

**Corrigido**

* O evento `CONTRACT_FORMALIZATION_FAILED` agora dispara de forma confiável em todos os casos de falha definitiva de formalização. Antes, o disparo dependia de um mecanismo interno que podia nunca disparar em determinados cenários, ou disparar prematuramente enquanto o contrato ainda seria retentado.

## 2026-06-28

### Garantia FGTS no leilão — campos de cadastro, regra de cobertura e validação

A solicitação de proposta do leilão (homologação) passa a aceitar **garantia FGTS**, e a submissão de ofertas com garantia ganha **validação preventiva de cobertura** e o esclarecimento do formato das taxas.

**Adicionado** *(aditivo, não-breaking)*

* `POST /api/v1/originator/dataprev/worker-solicitations` ([Cadastrar Proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/solicitacao-extra-trabalhador.md)) passa a aceitar os campos **opcionais** `valorSaldoDisponivelGarantiaFgts`, `valorMultaRescisoriaGarantiaFgts` e `percVerbaRescisoriaGarantia` (0 a 35). Quando qualquer um é informado, a solicitação é registrada **com garantia** (flag derivada automaticamente). Sem eles, o comportamento é o de hoje (sem garantia).

**Alterado** *(esclarecimento de contrato, não-breaking)*

* [Submeter Ofertas](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/submeter-ofertas.md): a garantia FGTS da `warrantyOffer` precisa **cobrir o empréstimo** conforme o canal — **leilão (com proposta) = 100% exato** (tolerância R$ 0,01), **canal banco (sem proposta) = 50%**. Garantia que não respeita a cobertura é recusada com **`422`** (com o valor esperado na mensagem) **antes** de chegar à Dataprev; garantia acima do saldo proposto na solicitação é recusada com **`400`** (`FI`).
* As taxas e CET da oferta (`monthlyInterestRate`, `annualInterestRate`, `monthlyEffectiveCost`, `annualEffectiveCost`) devem ter **no máximo 2 casas decimais** — valores com mais casas são recusados. Arredonde para 2 casas antes de enviar.
* O percentual de verba rescisória dado em garantia (`severancePercentage` / `percVerbaRescisoriaGarantia`) é limitado a **35%**; quando 0, **omita o campo** — a garantia não é aceita com campos zerados.

***

## 2026-06-26

### Cadastrar Proposta na Dataprev (homologação)

Novo endpoint de **homologação** para cadastrar uma solicitação extra de trabalhador na Dataprev — massa de dados que alimenta o [leilão de propostas](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao.md). Depende de o trabalhador já existir na massa via [Criar trabalhador (homologação)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/criar-trabalhador-originator.md). Ver [Cadastrar Proposta (homologação)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/solicitacao-extra-trabalhador.md).

**Adicionado** *(aditivo, não-breaking)*

* `POST /api/v1/originator/dataprev/worker-solicitations` — cadastra a solicitação extra (`cpfTrabalhador`, `matricula`, inscrição do empregador, `numeroParcelas`, `valorLiberado`); retorna `201` com os valores registrados. Disponível apenas em homologação. Erros: `400` (payload inválido), `412` (trabalhador inexistente na massa de homologação).

***

### Aprovação de pagamento (payment-approval)

Novo passo de **confirmação explícita do originador** entre a averbação e a formalização. Para originadores com `requiresPaymentApproval = true` e `formalizationStrategy = GTBANKER`, o contrato averbado **não** segue automaticamente para o GTBanker: fica em `PENDING_PAYMENT_APPROVAL` aguardando a confirmação do originador, que libera o contrato para a formalização via novo endpoint. Para os demais originadores o fluxo permanece o de hoje. Guia em [Aprovação de Pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/aprovacao-de-pagamento.md).

**Adicionado** *(aditivo, não-breaking)*

* `POST /api/v1/originator/contracts/{contractNumber}/payment-approval` — confirma a aprovação de pagamento de um contrato em `PENDING_PAYMENT_APPROVAL` (assíncrono; `202 Accepted` com `status: ENDORSED`). O contrato passa a `ENDORSED` e segue para a formalização no GTBanker. Erros: `404` (contrato não encontrado ou de outro originador) e `409` (`errorCode: CONTRACT_NOT_PENDING_PAYMENT_APPROVAL`, contrato não está aguardando aprovação).
* Novo estado de contrato **`PENDING_PAYMENT_APPROVAL`** — averbado, aguardando a confirmação do originador (apenas quando `requiresPaymentApproval = true` + `formalizationStrategy = GTBANKER`). Caminho do contrato: `SIGNED` → `PENDING_PAYMENT_APPROVAL` → `ENDORSED` → `FORMALIZED` → `COMPLETED`.
* Novo evento de webhook **`CONTRACT_PAYMENT_APPROVAL_REQUIRED`** (source `CONTRACT`) — disparado quando o contrato entra em `PENDING_PAYMENT_APPROVAL`; payload com `requestNumber`, `contractNumber` e `status` (= `PENDING_PAYMENT_APPROVAL`). É **adicional** ao `ENDORSEMENT_ENDORSED` (averbação concluída), que continua sendo disparado normalmente; o originador precisa estar inscrito no novo evento. Ver [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#contract_payment_approval_required).
* Para **rejeitar** (não prosseguir) um contrato em `PENDING_PAYMENT_APPROVAL`, use a [desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md) existente (`POST /api/v1/originator/contracts/exclude`) — não há endpoint de rejeição dedicado.

***

## 2026-06-25

### Regra de cobertura de garantias (FGTS) documentada

Novo guia detalhando a **regra de cobertura de garantias** que a Dataprev aplica em operações com garantia (FGTS e/ou verbas rescisórias): cobertura exigida por canal (100% no leilão / 50% no canal próprio), verba rescisória **binária** (margem disponível integral), comparação **monetária** com tolerância de **R$ 0,01**, e a regra **exato vs. mínimo** (sobre-cobertura é aceita só quando a garantia é somente verbas rescisórias; com FGTS, valores acima do exigido **reprovam**). Ver [Cobertura de Garantias (FGTS)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/cobertura-de-garantias.md).

**Documentado** *(esclarecimento, não-breaking)*

* Novo guia [Cobertura de Garantias (FGTS)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/cobertura-de-garantias.md) com os percentuais por canal, momentos de validação (cadastramento da proposta no leilão e averbação) e exemplos numéricos.
* A descrição do código **`FI`** em [Submeter Ofertas](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/leilao/submeter-ofertas.md) passa a referenciar a regra de cobertura aplicada pela Dataprev. Comportamento da API inalterado — apenas documentação.

***

## 2026-06-19

### Webhook de atualização do leilão também na varredura automática

O webhook **`AUCTION_SOLICITATIONS_REFRESHED`** passa a ser entregue não só na atualização sob demanda, mas também na **varredura automática periódica** do leilão — quando ela descobre novas solicitações. Ver [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#auction_solicitations_refreshed).

**Alterado** *(aditivo, não-breaking)*

* O webhook **`AUCTION_SOLICITATIONS_REFRESHED`** agora também é disparado quando a **varredura automática periódica** da plataforma persiste novas solicitações de proposta — antes era enviado apenas ao concluir uma atualização sob demanda (`POST .../auction/solicitations/refresh`, endpoint removido em 2026-07-19). Na varredura periódica o evento só é entregue quando há novas solicitações (`persistedNew > 0`). O payload e o `sourceId` (= `originatorId`) permanecem iguais. Retrocompatível: integrações que já consomem o evento continuam funcionando — apenas podem passar a recebê-lo com mais frequência.

***

## 2026-06-13

### Consulta de FGTS disponível + leitura/webhook enriquecidos

Nova consulta assíncrona de **FGTS disponível** (saldo + multa rescisória) por vínculo, e o último snapshot FGTS passa a aparecer (read-time) nas leituras de margem e de lastro. Ver [Consultar FGTS Disponível](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md).

**Adicionado**

* Novos endpoints de [Consulta de FGTS Disponível](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-fgts-disponivel.md), no mesmo padrão assíncrono das demais consultas Dataprev: `POST .../employees/{publicId}/authorized-bonds/{bondId}/fgts-availability-queries` (primária) e `POST .../employees/{publicId}/employment-relationships/{relationshipId}/fgts-availability-queries` → `202 { requestId, status }`; resultado em `GET /api/v1/originator/fgts-availability-queries/{requestId}` (`availableBalance`, `severanceFine`, `referenceAt`).
* Novos eventos de webhook **`FGTS_AVAILABILITY_QUERY_COMPLETED`** e **`FGTS_AVAILABILITY_QUERY_FAILED`** (source `EMPLOYEE`). Ver [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#fgts_availability_query_completed-fgts_availability_query_failed).
* Campo **opcional** `fgtsAvailability { availableBalance, severanceFine, referenceAt }` (ou `null`) no resultado da [Consulta de Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md), no [`GET /margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) e na [Listagem de Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) — último snapshot FGTS `COMPLETED` do vínculo, resolvido em tempo de leitura.

**Alterado** *(aditivo, não-breaking)*

* O webhook **`AUTHORIZED_BONDS_LISTED`** passa a incluir, no payload, `bondCount` e a lista `bonds[]` enriquecida (mesma estrutura do `GET` de listagem, incluindo `fgtsAvailability` por lastro). Retrocompatível: integrações que seguem chamando o `GET` por `requestId` continuam funcionando.
* Os webhooks **`MARGIN_QUERY_COMPLETED`** e a listagem de vínculos herdam o `fgtsAvailability` em cada vínculo/lastro (aditivo, `null` quando não há snapshot).

**Alterado**

* O campo `ineligibilityReason` da [Listagem de Vínculos Autorizados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-vinculos-autorizados.md) passa a emitir o **código de domínio em inglês** (ex.: `LEGACY_LOAN_REGISTERED_ESOCIAL`), alinhado ao valor que as leituras de margem/vínculo já retornam. Integrações que dependiam dos códigos antigos em português neste endpoint devem atualizar o mapeamento. O campo `employerTaxIdType` (`CNPJ`/`CPF`) não muda.

***

## 2026-06-11

### Alertas de afastamento/desligamento na margem + margem completa no webhook

A [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) passa a expor **alertas de afastamento e desligamento** do trabalhador informados pela Dataprev, e o webhook `MARGIN_QUERY_COMPLETED` passa a carregar a **margem completa** no payload (não só a notificação). Ver [Alertas do trabalhador](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#alertas-do-trabalhador-alerts) e [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#margin_query_completed).

**Adicionado**

* Cada `employmentRelationships[]` da [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) passa a trazer um array **opcional** `alerts` com alertas de **afastamento** (`alertType: SUSPENSION`) e **desligamento** (`alertType: TERMINATION`) do trabalhador. Cada alerta tem `alertType`, `alertTypeDescription`, `referenceDate`, `eventId`, os campos de afastamento (`suspensionReasonCode`, `suspensionReasonDescription`, `suspensionStartDate`, `suspensionEndDate`) e os de desligamento (`terminationReasonCode`, `terminationReasonDescription`, `terminationDate`, `priorNoticeDate`, `priorNoticeEndDate`); datas em ISO `AAAA-MM-DD` e campos não aplicáveis ao tipo vêm `null`. Ausente/`null` quando não há alertas.

**Alterado** *(aditivo, não-breaking)*

* O webhook **`MARGIN_QUERY_COMPLETED`** passa a incluir o array `employmentRelationships[]` no payload — a **margem completa** (mesma estrutura do `GET /margin`, incluindo os `alerts`). Antes o payload era apenas a notificação e o integrador chamava o `GET /margin`; agora a margem vem junto. Retrocompatível: integrações que ignoram `employmentRelationships` e seguem chamando o `GET /margin` continuam funcionando.

### Empréstimos legados na margem + webhook

A [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) passa a expor os **empréstimos legados** do trabalhador informados pela Dataprev (contratos consignados e não consignados já existentes), e o mesmo array flui para o payload do webhook `MARGIN_QUERY_COMPLETED` via `employmentRelationships[]`. Ver [Empréstimos legados](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#emprestimos-legados-legacyloans) e [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#margin_query_completed).

**Adicionado** *(aditivo, não-breaking)*

* Cada `employmentRelationships[]` da [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) passa a trazer um array **opcional** `legacyLoans` com os empréstimos legados do trabalhador. Cada item tem `financialInstitutionCode`, `contractNumber`, `contractType` (`NON_PAYROLL_UNSECURED` ou `PAYROLL_DEDUCTED`), `contractTypeDescription`, `contractStartDate`, `contractEndDate`, `totalInstallments`, `paidInstallments`, `installmentAmount`, `loanAmount`, `disbursedAmount`, `outstandingBalance`, `monthlyInterestRate`, `monthlyCet` e `sourceUpdatedAt`; datas em ISO `AAAA-MM-DD` e campos indisponíveis vêm `null`. Ausente/`null` quando não há empréstimos legados. O array também flui para o payload do webhook **`MARGIN_QUERY_COMPLETED`** junto de `employmentRelationships[]` (mesma estrutura do `GET /margin`). Retrocompatível: integrações que ignoram `legacyLoans` continuam funcionando.

### Catálogo de eventos de webhook completo no contrato

O enum `WebhookEventType` do contrato OpenAPI passa a listar todos os eventos efetivamente disparados pela plataforma. Foram incluídos os que já eram entregues e descritos no [catálogo de eventos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md) mas não constavam no enum: `AUTHORIZATION_SIGN_URL_READY` e `DATAPREV_WINDOW_OPENED`/`DATAPREV_WINDOW_CLOSED` — os de listagem de vínculos (`AUTHORIZED_BONDS_LISTED`/`AUTHORIZED_BONDS_LISTING_FAILED`) já constavam.

**Alterado** *(apenas contrato/documentação, não-breaking)*

* O enum `WebhookEventType` passa a listar os 32 tipos de evento (antes 27). É mudança apenas de **contrato/documentação** — o comportamento e os payloads dos webhooks não mudam; integrações existentes continuam funcionando.

***

## 2026-06-10

### Re-autorização de termo vencido + status `SUPERSEDED`

Quando o **termo de autorização** (30 dias a partir da assinatura) vence, a [consulta de margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) responde `200` com `status: TERM_EXPIRED` (**sem webhook**) — o trabalhador precisa **re-autorizar**. Ao re-autorizar, o termo anterior é preservado como **lastro auditável** (novo status `SUPERSEDED`) e um **novo documento, com novo NSU**, passa a vigorar. Novo guia [Ciclo de Vida da Autorização e Re-autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ciclo-de-vida-da-autorizacao.md).

**Alterado** *(aditivo, não-breaking)*

* O enum `DocumentStatus` (em respostas de **status da autorização**) passa a incluir **`SUPERSEDED`** — documento substituído por uma re-autorização posterior, mantido como lastro. Trate-o como estado **terminal / não-vigente**.
* A consulta de margem documenta explicitamente `status: TERM_EXPIRED` no corpo do `200` (valor já existente no contrato): **sempre inspecione o campo `status`**, não apenas o código HTTP. Termo expirado é sinalizado na resposta, não há webhook para isso.

### Autorização via Lastro — opt-in via API (sem PDF)

Novo caminho de **autorização Dataprev** em que o originador coleta o opt-in no próprio canal digital e **envia a trilha de aceite via API**, sem gerar nem assinar um termo PDF. A escolha é **por trabalhador** e o estado final é idêntico ao do fluxo de assinatura de PDF (`AUTHORIZATION_COMPLETED`). Guia em [Estratégias de Assinatura — Termo em Trilha Opt-In](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md#termo-em-trilha-opt-in) e página [Criar Trilha de Autorização (Lastro)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md).

**Adicionado**

* `POST /api/v1/originator/employees/{publicId}/authorization-trails` — recebe a trilha de aceite opt-in (snapshot forense `timestamp`/`ipAddress`/`sessionId`/`fingerprint` + timeline `events[]` opcional em texto livre) e dispara a autorização Dataprev pelo canal **Web Correspondente**. Retorna `202` (`PROCESSING`) ou `200` (`ALREADY_AUTHORIZED`, idempotente). Requer o originador habilitado como **`ORIGINATOR_MANAGED`** (senão `403`); `422` se o `documentNumber` não casar com o CPF do empregado. Suporta o header `Idempotency-Key`. Página [Criar Trilha de Autorização (Lastro)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md).

> O `200`/`ALREADY_AUTHORIZED` descrito acima foi **superado em 2026-07-28**: o endpoint passou a responder sempre `202`/`PROCESSING`. Ver [Enviar termo sempre reautoriza](#enviar-termo-sempre-reautoriza).

***

## 2026-06-09

### Desaverbação (de-endorsement) + retry diferenciado de averbação

Novo fluxo para **desaverbar** (excluir a averbação no convênio) um contrato já averbado e ainda não pago — a pedido do originador ou automaticamente após 5 dias da formalização sem confirmação de pagamento. Guia em [Desaverbação (de-endorsement)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md).

**Adicionado**

* `POST /api/v1/originator/contracts/exclude` — solicita a desaverbação de um contrato averbado (assíncrono; `202` com a averbação em `EXCLUDING`). Identificação por `requestNumber` **ou** `contractNumber`. Página [Desaverbar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desaverbar-contrato.md).
* Webhook **`ENDORSEMENT_EXCLUDING`** — desaverbação aceita e em processamento.
* Webhook **`ENDORSEMENT_EXCLUDED`** — desaverbação concluída: contrato `CANCELLED` e margem consignável restaurada.
* Webhook **`ENDORSEMENT_EXCLUSION_FAILED`** — desaverbação não concluída (esgotou retentativas): a averbação volta para `ENDORSED` e o contrato permanece averbado.
* Erros `409` (campo `errorCode`): `ENDORSEMENT_NOT_ENDORSED`, `CONTRACT_ALREADY_PAID`, `CONTRACT_ALREADY_CANCELLED`, `EXCLUSION_IN_PROGRESS`, `ENDORSEMENT_NOT_FOUND`.

**Alterado** *(aditivo, não-breaking)*

* O enum `endorsementStatus` (em `ContractResponse` e no payload `EndorsementWebhookPayload`) passa a incluir **`EXCLUDING`** e **`EXCLUDED`**.
* Retry de averbação diferenciado por motivo ("teimosinha"): respostas de **margem consignável excedida** (Dataprev `HW`) deixam de ser falha permanente e voltam a ser **retentadas** — o originador recebe `ENDORSEMENT_RETRYING` a cada tentativa, em vez de `ENDORSEMENT_FAILED` imediato.

***

### Consultas Dataprev sob demanda (Originator)

Dois fluxos assíncronos para consultar o e-consignado Dataprev **sob demanda**, sem alterar o fluxo automático de margem pós-autorização. Padrão uniforme `POST → 202 {requestId} → webhook → GET por requestId`. Guia completo em [Consultas Dataprev (sob demanda)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md).

**Adicionado**

* `POST /api/v1/originator/employees/{publicId}/authorized-bonds-queries` — solicita a listagem de vínculos autorizados do trabalhador (assíncrono).
* `GET /api/v1/originator/authorized-bonds-queries/{requestId}` — resultado da listagem, com o `bondId` de cada vínculo.
* `POST /api/v1/originator/employees/{publicId}/authorized-bonds/{bondId}/margin-queries` — solicita a margem de um vínculo específico (assíncrono). Body opcional `{ forceIneligible }`.
* `GET /api/v1/originator/margin-queries/{requestId}` — resultado da consulta de margem por vínculo.
* Webhook **`AUTHORIZED_BONDS_LISTED`** — listagem de vínculos concluída.
* Webhook **`AUTHORIZED_BONDS_LISTING_FAILED`** — falha permanente na listagem.
* Erros `422` (campo `errorCode`): **`EMPLOYEE_NOT_AUTHORIZED`** (employee não autorizado no Dataprev) e **`BOND_NOT_ELIGIBLE`** (vínculo inelegível enviado sem `forceIneligible=true`).

**Alterado** *(aditivo, não-breaking)*

* Webhooks **`MARGIN_QUERY_COMPLETED`** e **`MARGIN_QUERY_FAILED`** passam a incluir os campos opcionais **`requestId`** e **`bondId`** — preenchidos apenas no fluxo de margem **por vínculo**; ausentes/nulos no fluxo automático por employee.

***

*Entradas anteriores a esta página não foram versionadas em changelog. A partir daqui, cada release registra suas mudanças de contrato no topo, com a respectiva data.*

[Central de Atendimento — giro.tech](https://giro.tech/central-de-atendimento/)
