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

# Processo de Homologação

Todo originador valida a integração no ambiente de homologação antes de operar em produção. Este guia traz a massa de teste, os cenários e o checklist.

***

## Como funciona

**Você monta a sua própria massa de teste**: cadastra na base de homologação da Dataprev, via `POST /api/v1/originator/dataprev/workers`, os trabalhadores de que precisa, com margem, elegibilidade, categoria, data de admissão e motivo de inelegibilidade. Depois disso, o trabalhador segue o fluxo normal da API (`POST /api/v1/originator/employees`, autorização, margem, simulação, proposta e contrato).

{% hint style="info" %}
O endpoint só existe em **homologação** (`https://ingress.gtpayroll.staging.giro.tech`). Ver [Criar trabalhador na Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/criar-trabalhador-originator.md).
{% endhint %}

***

## Montando a massa de teste

Um trabalhador por cenário. Corpo completo em [Criar trabalhador na Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/criar-trabalhador-originator.md); os campos que definem o cenário:

| Cenário        | Como cadastrar                                                                                             | O que valida                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Com margem** | `elegivel: true` + `valorMargemDisponivel` folgado (e `valorBaseMargem`/`valorTotalVencimentos` coerentes) | Fluxo de originação completo, até a averbação                           |
| **Sem margem** | `elegivel: true` + `valorMargemDisponivel: 0`                                                              | Tratamento de trabalhador sem margem consignável                        |
| **Inelegível** | `elegivel: false` + `codigoInelegivel` com o motivo desejado                                               | Rejeição por elegibilidade e o `ineligibilityReason` devolvido pela API |
| **Desligado**  | `dataDesligamento` + `codigoMotivoDesligamento`                                                            | Alertas de desligamento e o bloqueio de novas operações                 |

```http
POST /api/v1/originator/dataprev/workers
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpfTrabalhador": "12345678901",
  "matricula": "0001",
  "codigoInscricaoEmpregador": 1,
  "numeroInscricaoEmpregador": "12345678000199",
  "nome": "FULANO DE TAL",
  "dataNascimento": "1990-05-15",
  "codigoCategoriaTrabalhador": 101,
  "elegivel": true,
  "valorTotalVencimentos": 5000.00,
  "valorBaseMargem": 5000.00,
  "valorMargemDisponivel": 1750.00,
  "dataAdmissao": "2022-04-01"
}
```

{% hint style="warning" %}
**O `nome` tem que ser idêntico ao do Employee.** A Dataprev compara o nome na averbação: se divergir do enviado em `POST /api/v1/originator/employees`, a averbação é **rejeitada por divergência cadastral**, só no fim do fluxo.
{% endhint %}

{% hint style="warning" %}
**Não use CPFs reais.** Gere CPFs válidos sintéticos.
{% endhint %}

***

## Etapas da homologação

### 1. Configuração inicial

* Receber o token JWT de homologação
* Configurar a URL base de homologação (`https://ingress.gtpayroll.staging.giro.tech`)
* Cadastrar a assinatura de webhook para receber os eventos do fluxo
* Montar a massa de teste com `POST /api/v1/originator/dataprev/workers` (ver acima)

### 2. Validação do fluxo completo (trabalhador com margem)

```
Criar trabalhador na Dataprev → Criar Employee → Autorizar (termo em PDF ou trilha opt-in)
  → Consultar Margem → Criar Simulação → Criar Proposta → Criar Contrato
```

| Passo             | Endpoint                                                                                  | O que validar                                                    |
| ----------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Criar trabalhador | `POST /api/v1/originator/dataprev/workers`                                                | Retorno `201`; `nome` idêntico ao do Employee                    |
| Criar Employee    | `POST /api/v1/originator/employees`                                                       | Retorno `201`, `publicId` gerado                                 |
| Autorizar         | `POST .../{publicId}/signed-authorizations` ou `POST .../{publicId}/authorization-trails` | Retorno `202` com `status: PROCESSING` e o `nsu` gerado          |
| Consultar Status  | `GET .../{publicId}/authorization/status`                                                 | Polling até `AUTHORIZED`, ou o webhook `AUTHORIZATION_COMPLETED` |
| Consultar Margem  | `GET .../{publicId}/margin`                                                               | Retorno `200` com a margem que você cadastrou                    |
| Criar Simulação   | `POST .../{publicId}/simulations`                                                         | Retorno `201` com cálculos financeiros                           |
| Criar Proposta    | `POST .../{publicId}/proposals`                                                           | Retorno `201` com dados consolidados                             |
| Criar Contrato    | `POST /api/v1/originator/proposals/{proposalPublicId}/contracts`                          | Retorno `201`; `signUrl` ou webhook `CONTRACT_DOCUMENT_READY`    |

### 3. Validação de cenários de erro

#### Trabalhador sem margem

1. Cadastre um trabalhador com `valorMargemDisponivel: 0` e crie o Employee correspondente
2. Autorize pelo caminho que você usa e aguarde a conclusão
3. Consulte a margem: deve vir zerada
4. Valide que sua aplicação trata a ausência de margem sem quebrar a jornada

#### Trabalhador inelegível

1. Cadastre um trabalhador com `elegivel: false` e o `codigoInelegivel` do motivo que quer exercitar
2. Autorize e aguarde a conclusão
3. Consulte a margem: o vínculo volta com `isEligible: false` e o `ineligibilityReason` correspondente
4. Valide que sua aplicação exibe o motivo e bloqueia a simulação

### 4. Validação de endpoints auxiliares

* Testar [Reenvio de link de assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-giro/reenviar-link-assinatura.md)
* Testar [Cancelamento de contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/cancelar-contrato.md)

### 5. Validação do desembolso (perfil `GTBANKER`)

Só para `formalizationStrategy = GTBANKER`. Em homologação, o desembolso é simulado por **chaves PIX e contas de teste**, e cada valor força um resultado (sucesso, revisão, falha, instabilidade bancária). Lista em [Chaves PIX de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md).

Use a chave em `pix.key` (com `pix.keyType: RANDOM`) ou a conta em `bankAccount` ao [Criar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md) e acompanhe os webhooks:

| Resultado no GTBanker | Webhook do GTPayroll                                                                                                       | O que validar                                                                                                                                                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCESSO_DESEMBOLSO`  | [`PAYMENT_SUCCESS`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_success)   | Contrato passa a `COMPLETED`; `rejectionReason` limpo                                                                                                                                                                                                                   |
| `REVISAO_DESEMBOLSO`  | [`PAYMENT_REVISION`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_revision) | Contrato **permanece** em `FORMALIZED`; `rejectionReason` preenchido com o ticket; correção via [Atualizar Conta de Desembolso](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desembolso/atualizar-conta-desembolso.md) **com** `ticket` |
| `FALHA_DESEMBOLSO`    | [`PAYMENT_FAILURE`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#payment_failure)   | Contrato **permanece** em `FORMALIZED`; `rejectionReason` com código e mensagem; resolução pela equipe Giro                                                                                                                                                             |

{% hint style="warning" %}
`PAYMENT_REVISION` exige o programa de revisão de desembolso habilitado para o originador; sem ele, o cenário chega como `PAYMENT_FAILURE`. Confirme com a equipe de integração.
{% endhint %}

Se a formalização falha **antes** do GTBanker (ex.: dado bancário inválido), o evento é [`CONTRACT_FORMALIZATION_FAILED`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md#contract_formalization_failed); corrija pelo mesmo endpoint **sem** `ticket`, que reenvia a formalização.

### 6. Validação da integração embedded (se aplicável)

Se usar o [widget embedded](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/integracao-embedded.md):

* Validar renderização do widget no iframe/WebView
* Validar recebimento dos eventos (`gt:ready`, `gt:flow_complete`, `gt:flow_error`)
* Validar handler de `gt:open_url` para assinatura digital
* Testar nos dispositivos/navegadores alvo

***

## Cenários avançados de homologação

Bordas que costumam aparecer só em produção. Valide as que se aplicam à sua integração antes do go-live.

{% hint style="info" %}
Os cenários 1 e 2 dependem da configuração do originador: trilha opt-in e envio de termo assinado exigem `authorizationSignatureStrategy = ORIGINATOR_MANAGED` (sem isso, `403 ORIGINATOR_OPT_IN_NOT_ENABLED`). Ver [Estratégias de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md) e os [dois caminhos de autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md#os-dois-caminhos-lado-a-lado).
{% endhint %}

| # | Cenário                                    | Pré-condição                                                                                                                                                                                | Passos                                                                                                                                                                                                                                                                                                                                        | O que validar                                                                                                                                                                                                                                                                                                                                                                                                                           |
| - | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Autorização via Lastro (opt-in)**        | Originador com `authorizationSignatureStrategy = ORIGINATOR_MANAGED`; trabalhador cadastrado com margem (`elegivel: true`, `valorMargemDisponivel` > 0) e o Employee correspondente criado. | 1. Colete o opt-in no seu canal. 2. `POST /api/v1/originator/employees/{publicId}/authorization-trails` com a trilha de aceite (`authenticationType: "opt-in"`, `timestamp`, `ipAddress`, `sessionId`, lastro). 3. Aguarde os webhooks.                                                                                                       | Resposta `202` com `status: PROCESSING` e `nsu`; webhook `AUTHORIZATION_COMPLETED` (mesmo estado final do fluxo de PDF) **sem nenhum PDF enviado**; em seguida, consulta de margem automática (`MARGIN_QUERY_COMPLETED`).                                                                                                                                                                                                               |
| 2 | **Expiração de termo + re-autorização**    | Employee autorizado com **termo vencido**: peça à equipe de integração para envelhecer o termo do employee de teste, ou reaproveite um autorizado em rodada anterior.                       | 1. Consulte a margem ([`GET .../margin`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md)). 2. Re-autorize repetindo o seu fluxo de autorização (PDF ou Lastro). 3. Consulte a margem novamente.                                                                                                | Margem retorna `200` com `status: TERM_EXPIRED` (**inspecione o `status`**); após a re-autorização, o termo anterior fica `SUPERSEDED`, um novo NSU passa a valer e a margem volta a `200` com `status: OK`. Ver [Ciclo de Vida da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ciclo-de-vida-da-autorizacao.md).                                                                                            |
| 3 | **Desaverbação**                           | Contrato averbado (`ENDORSED`), **não** `CANCELLED`/`COMPLETED` e formalização **não** `PAID`.                                                                                              | 1. Leve um contrato até `ENDORSED`. 2. `POST /api/v1/originator/contracts/exclude` ([Desaverbar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desaverbar-contrato.md)). 3. Acompanhe os webhooks. 4. Reenvie a solicitação enquanto estiver em `EXCLUDING`.                                          | Resposta `202`; averbação transita `ENDORSED → EXCLUDING → EXCLUDED` com os webhooks `ENDORSEMENT_EXCLUDING` e `ENDORSEMENT_EXCLUDED`; no sucesso o contrato fica `CANCELLED` e a margem é **restaurada**; reenvio durante o processamento retorna `409 EXCLUSION_IN_PROGRESS`. Ver [Desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md).                                                         |
| 4 | **Idempotência**                           | Qualquer `POST` da API Originator (ex.: simulação, proposta, contrato ou trilha de autorização).                                                                                            | 1. Envie uma requisição `POST` com um `Idempotency-Key` único. 2. Reenvie a **mesma** requisição com a **mesma** chave após a conclusão. 3. (Opcional) Reenvie a chave durante o processamento.                                                                                                                                               | O reenvio retorna a **mesma resposta** (status/body) com `Idempotency-Replayed: true`, **sem duplicar**; durante o processamento, `409 Conflict`. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md).                                                                                                                                                                                       |
| 5 | **Vínculo inelegível + `forceIneligible`** | Employee `AUTHORIZED` com ao menos um vínculo **inelegível** (cadastre com `elegivel: false` e o `codigoInelegivel` desejado).                                                              | 1. Liste os vínculos: `POST .../authorized-bonds-queries` e `GET .../authorized-bonds-queries/{requestId}`. 2. Guarde o `bondPublicId` de um item com `eligible: false`. 3. Solicite a margem desse vínculo: `POST .../authorized-bonds/{bondPublicId}/margin-queries` **sem** `forceIneligible`. 4. Reenvie **com** `forceIneligible: true`. | A listagem retorna o vínculo com `eligible: false` e o `ineligibilityReason`; o `POST` sem o flag retorna `422 BOND_NOT_ELIGIBLE`; com `forceIneligible: true` a consulta é iniciada (`202`) e o resultado no `GET` traz `isEligible: false` + `ineligibilityReason`. Ver [Consultar Margem por Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev/consultar-margem-por-vinculo.md). |

{% hint style="info" %}
**Múltiplos vínculos:** cadastre o **mesmo CPF** mais de uma vez em [Criar trabalhador na Dataprev](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/dataprev/criar-trabalhador-originator.md), variando `matricula` e `numeroInscricaoEmpregador`. Cada combinação vira um vínculo na listagem de vínculos.
{% endhint %}

{% hint style="warning" %}
`forceIneligible` **não** dispensa a autorização: employee não `AUTHORIZED` recebe `422 EMPLOYEE_NOT_AUTHORIZED` nos dois `POST` de consulta sob demanda.
{% endhint %}

***

## Checklist de homologação

* [ ] Token JWT configurado e funcionando
* [ ] Massa de teste criada via `POST /api/v1/originator/dataprev/workers`
* [ ] Fluxo completo com trabalhador com margem (happy path)
* [ ] Tratamento de trabalhador sem margem
* [ ] Tratamento de trabalhador inelegível (`ineligibilityReason`)
* [ ] Consulta de bancos
* [ ] Reenvio de link de assinatura
* [ ] Cancelamento de contrato
* [ ] Desembolso simulado com as [chaves PIX de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md) — `PAYMENT_SUCCESS`, `PAYMENT_REVISION` e `PAYMENT_FAILURE` (perfil `GTBANKER`)
* [ ] Integração embedded validada (se aplicável)
* [ ] Tratamento de erros HTTP (401, 403, 404, 409)

**Cenários avançados:**

* [ ] Termo em trilha opt-in — `AUTHORIZATION_COMPLETED` sem PDF (se habilitado)
* [ ] Expiração de termo (`TERM_EXPIRED`) + re-autorização (`SUPERSEDED`)
* [ ] Desaverbação — `ENDORSED → EXCLUDING → EXCLUDED`, contrato `CANCELLED` e margem restaurada
* [ ] Idempotência — reenvio com mesmo `Idempotency-Key` (`Idempotency-Replayed: true`, sem duplicação)
* [ ] Vínculo inelegível — `422 BOND_NOT_ELIGIBLE` sem flag; consulta com `forceIneligible=true`

***

## Aprovação e go-live

Concluídas as validações, a equipe de integração:

1. Revisa os testes com você
2. Entrega o token JWT de **produção**
3. Libera o domínio de produção (se necessário)
4. Ativa o originador em produção

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