> 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/fluxo-e2e-originacao.md).

# Fluxo E2E de Originação

O fluxo de consignado na API Originator, do cadastro ao desembolso, com checklist por etapa e as diferenças entre configurações de originador.

***

## Configurações de Originador

A **autorização Dataprev** é sempre coletada pelo originador (termo em PDF ou trilha opt-in). Variam por perfil a **assinatura do contrato**, a **formalização** e as regras de elegibilidade.

### Perfil A — contrato gerenciado pela Giro

| Configuração                                       | Valor      |
| -------------------------------------------------- | ---------- |
| `contractSignatureStrategy`                        | `GIRO`     |
| `formalizationStrategy`                            | `GTBANKER` |
| Regras de elegibilidade e de limites do empréstimo | Aplicadas  |

### Perfil B — contrato gerenciado pelo originador

| Configuração                                       | Valor                |
| -------------------------------------------------- | -------------------- |
| `contractSignatureStrategy`                        | `ORIGINATOR_MANAGED` |
| `formalizationStrategy`                            | `ORIGINATOR_MANAGED` |
| Regras de elegibilidade e de limites do empréstimo | Dispensadas          |

> **Info:** Assinatura, formalização e dispensa de regras são configuradas de forma independente no onboarding e podem ser combinadas (ex.: assinatura GIRO com formalização ORIGINATOR\_MANAGED). Ver [Estratégias de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md) e [Elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md).

***

## Etapa 1 — Criar Employee

`POST /api/v1/originator/employees`

Igual em todos os perfis. Sem o objeto `authorization` no corpo, a autorização só começa na Etapa 2.

**Checklist:**

* [ ] Enviar request com CPF (11 dígitos), nome, data de nascimento, nome da mãe, gênero, telefone, e-mail
* [ ] Receber `201 Created` com `publicId`
* [ ] Anotar o `publicId`, usado em todas as etapas seguintes
* [ ] Opcional: conferir o employee em `GET /api/v1/originator/employees/{publicId}`

***

## Etapa 2 — Autorizar o trabalhador na Dataprev

Três caminhos, escolhidos **por trabalhador**, todos terminando em `AUTHORIZATION_COMPLETED`. Ver [Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md).

**Caminho A —** [**Termo em PDF, envio direto**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md) **(1 chamada)**

`POST /api/v1/originator/employees/{publicId}/signed-authorizations`

* [ ] Gerar o termo e coletar a assinatura inteiramente no seu sistema
* [ ] Enviar o PDF assinado em base64 (`signedDocument`) + `documentNumber` (CPF)
* [ ] Receber `202` com `status: PROCESSING` e o `nsu` gerado pela própria chamada
* [ ] Sem upload posterior: a plataforma envia à Dataprev

> **Info:** O `signedDocument` precisa ser base64 válido, ter no máximo 10 MB e começar com `%PDF`. O `documentNumber` precisa casar com o CPF do employee, senão `422` (`CPF_MISMATCH`).

**Caminho B —** [**Termo gerado pela Giro**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro.md) **(3 chamadas)**

`POST /api/v1/originator/employees/{publicId}/authorization-documents`

* [ ] Chamar o endpoint e receber `nsu` e `status: PENDING` (o PDF ainda não existe)
* [ ] Receber webhook **`AUTHORIZATION_DOCUMENT_READY`** com `presignedUrl`
* [ ] Baixar o PDF via `presignedUrl` (ou via `GET .../authorization/{nsu}/document`)
* [ ] Coletar a assinatura no seu provedor
* [ ] Upload do assinado: `POST .../authorization/{nsu}/upload-signed` (multipart `signedDocument`)
* [ ] Acompanhar via `GET .../authorization/status` até `SIGNED`

> **Atenção:** não faça o upload antes do `AUTHORIZATION_DOCUMENT_READY`: o documento enviado não seria o termo que a Giro gerou. Use este caminho para usar o termo da plataforma ou ter o **NSU reservado antes** da assinatura.

**Caminho C —** [**Termo em Trilha Opt-In**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in.md) **(sem PDF)**

`POST /api/v1/originator/employees/{publicId}/authorization-trails`

* [ ] Coletar o opt-in do trabalhador no seu canal digital (app/site)
* [ ] Montar a trilha (IP, timestamp, sessão, fingerprint e, opcionalmente, timeline `events[]` em texto livre)
* [ ] Enviar a trilha (ver [Criar Trilha de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md))
* [ ] Receber `202` com `status: PROCESSING`
* [ ] Sem PDF e sem upload: a plataforma autoriza na Dataprev pelo canal **Web Correspondente**. A trilha fica com a Giro, amarrada ao NSU; a Dataprev recebe só canal, data/hora, NSU e CPF.

> **Atalho:** os caminhos A e C também podem ser disparados **junto com a Etapa 1**, no objeto `authorization` do `POST /api/v1/originator/employees`. Ver [Autorização no cadastro](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/employees/criar-employee.md#autorizacao-no-cadastro-opcional).

### Como os três caminhos convergem (decisão por employee)

```mermaid
flowchart TD
    START[Preciso autorizar a consulta<br/>de dados do trabalhador] --> Q{Existe termo em PDF?}
    Q -->|Sim, gerado por mim| A[Caminho A:<br/>envio direto]
    Q -->|Sim, gerado pela Giro| B[Caminho B:<br/>criar, baixar, subir assinado]
    Q -->|Não, tenho o opt-in| TRAIL[Caminho C:<br/>trilha opt-in]
    A --> DP[Autorização Dataprev]
    B --> DP
    TRAIL --> DP
    DP --> AUTH[Employee AUTORIZADO<br/>token válido]
    AUTH --> WH[Webhook AUTHORIZATION_COMPLETED]
    AUTH --> NEXT[Segue o fluxo:<br/>consulta de margem / proposta]
```

***

## Etapa 3 — Aguardar a conclusão da autorização

O envio à Dataprev é automático nos três caminhos; aqui você só acompanha.

**Checklist:**

* [ ] Aguardar **`AUTHORIZATION_COMPLETED`** (sucesso) **ou** **`AUTHORIZATION_FAILED`** (recusa definitiva: CPF/vínculo inelegível, trabalhador inexistente ou tentativas esgotadas; documento fica `INELIGIBLE` e nova tentativa só depois de corrigir o cadastro — ver [Ciclo de Vida da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ciclo-de-vida-da-autorizacao.md))
* [ ] Alternativa ao webhook: polling em `GET /api/v1/originator/employees/{publicId}/authorization/status` até `AUTHORIZED`

***

## Etapa 4 — Consultar Margem

`GET /api/v1/originator/employees/{publicId}/margin`

A plataforma consulta a margem sozinha depois da autorização; você só lê o resultado. Igual nos dois perfis.

**Checklist:**

* [ ] Aguardar webhook **`AUTHORIZATION_COMPLETED`** (etapa 3)
* [ ] Aguardar webhook **`MARGIN_QUERY_COMPLETED`**
* [ ] Chamar `GET /api/v1/originator/employees/{publicId}/margin` para obter os dados de margem
* [ ] Anotar `employmentRelationshipPublicId` e `availableMargin` do vínculo desejado

> **Atenção:** o `GET` não dispara consulta. Sem margem vigente nem consulta em andamento, ele responde `422 MARGIN_REFRESH_REQUIRED`, e polling não resolve. Para margem **nova** (ex.: dias depois da autorização), chame `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)): descarta a margem vigente, responde `202` e o resultado chega em `MARGIN_QUERY_COMPLETED`. Ver [O `GET` read-only](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#o-get-read-only).

***

## Etapa 4b (opcional) — Consultas de vínculos e margem sob demanda

A Etapa 4 usa **um** vínculo, o melhor elegível. Para escolher outro vínculo, inclusive inelegível, use as consultas sob demanda: `POST → 202 {requestId} → webhook → GET /{requestId}`.

**1. Listar vínculos autorizados**

* [ ] `POST /api/v1/originator/employees/{publicId}/authorized-bonds-queries` → `202 {requestId}`
* [ ] Aguardar webhook **`AUTHORIZED_BONDS_LISTED`**
* [ ] `GET /api/v1/originator/authorized-bonds-queries/{requestId}` → vínculos com **`bondPublicId`**, matrícula, empregador, `eligible` e motivo de inelegibilidade

**2. Consultar margem de um vínculo específico**

* [ ] `POST /api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/margin-queries` (body opcional `{ "forceIneligible": false }`) → `202 {requestId}`
* [ ] Aguardar webhook **`MARGIN_QUERY_COMPLETED`** (com `requestId` e o vínculo)
* [ ] `GET /api/v1/originator/margin-queries/{requestId}` → margem daquele vínculo

> **Info:** `forceIneligible: true` consulta vínculo inelegível (sem ele, `422 BOND_NOT_ELIGIBLE`). O `bondPublicId` é estável entre consultas. Ver [Consultas Dataprev (sob demanda)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultas-dataprev.md).

***

## Etapa 5 — Simular Empréstimo

`POST /api/v1/originator/employees/{publicId}/simulations`

Calcula parcelas, juros, IOF e CET. Muda conforme as regras de limites estejam aplicadas ou dispensadas.

### Perfil A — regras aplicadas

* [ ] Enviar simulação com valores dentro dos limites do produto
* [ ] Receber simulação com dados calculados (parcela, CET, IOF)
* [ ] Anotar o `publicId` da simulação (vai em `simulationPublicId`)
* [ ] **Teste de rejeição:** enviar valor acima do limite → deve retornar erro 400/422
* [ ] **Teste de rejeição:** parcelas acima do máximo → deve retornar erro
* [ ] **Teste de rejeição:** taxa de juros fora do range → deve retornar erro

### Perfil B — regras dispensadas

* [ ] Enviar simulação com valores dentro dos limites
* [ ] Receber simulação com dados calculados
* [ ] Anotar o `publicId` da simulação (vai em `simulationPublicId`)
* [ ] **Teste de bypass:** enviar valor acima do limite → deve funcionar normalmente
* [ ] **Teste de bypass:** parcelas acima do máximo → deve funcionar
* [ ] **Teste de bypass:** taxa de juros fora do range → deve funcionar

> **Migração de contrato:** para apresentar condições antes de o vínculo novo existir, use [Simular sem Vínculo](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes/simular-sem-vinculo.md) (`POST /api/v1/originator/simulations` ou `/simulations/by-installment`). A resposta não traz `publicId` e não vira proposta — para contratar, siga esta etapa normalmente.

> **Atenção:** a dispensa pode ser de todas as regras de elegibilidade ou só das de limites (valor, parcela, prazo, taxa). No segundo caso, margem, contratos ativos e PEP continuam valendo.

***

## Etapa 6 — Criar Proposta

`POST /api/v1/originator/employees/{publicId}/proposals`

Igual nos dois perfis.

**Checklist:**

* [ ] Enviar `simulationPublicId` + `employmentRelationshipPublicId` (os dados financeiros vêm da simulação). Sem `simulationPublicId`, todos os campos financeiros e as parcelas são obrigatórios
* [ ] Receber `201 Created` com o `publicId` da proposta
* [ ] Anotar o `publicId` da proposta para criar o contrato

***

## Etapa 7 — Criar Contrato

`POST /api/v1/originator/proposals/{proposalPublicId}/contracts`

Cria a CCB. A assinatura depende da estratégia.

### Perfil A — contractSignature GIRO

* [ ] Enviar contrato com dados de pagamento (PIX ou conta bancária), endereço, parcelas
* [ ] Opcional: `suppressNotification: true` para não enviar o WhatsApp ao trabalhador; o link chega em `signUrl` no webhook `CONTRACT_DOCUMENT_READY`
* [ ] Receber `201 Created` com `requestNumber`, `contractNumber`, `nsu`
* [ ] Trabalhador recebe o link de assinatura (ou você recebe a `signUrl` e notifica)
* [ ] Opcional: receber webhook **`CONTRACT_SIGNED`** (inscrição no evento) com URL do PDF assinado
* [ ] Acompanhar via `GET /api/v1/originator/contracts/by-request-number/{requestNumber}` até status de assinatura completa

### Perfil B — contractSignature ORIGINATOR\_MANAGED

* [ ] Enviar contrato com dados de pagamento, endereço, parcelas
* [ ] Receber `201 Created` com `requestNumber`, `contractNumber`, `nsu`
* [ ] PDF é gerado automaticamente
* [ ] Receber webhook **`CONTRACT_DOCUMENT_READY`** com `presignedUrl`
* [ ] Baixar PDF (webhook ou `GET .../contracts/{requestNumber}/document`)
* [ ] Coletar assinatura externamente
* [ ] Upload do assinado: `POST /api/v1/originator/contracts/{requestNumber}/upload-signed` (multipart `signedDocument`)
* [ ] Acompanhar via `GET /api/v1/originator/contracts/by-request-number/{requestNumber}`

***

## Etapa 8 — Averbação

Automática após a assinatura. Igual nos dois perfis.

**Checklist:**

* [ ] Verificar webhook **`ENDORSEMENT_PROCESSING`**
* [ ] Aguardar webhook **`ENDORSEMENT_ENDORSED`** (sucesso) ou **`ENDORSEMENT_FAILED`** (falha)
* [ ] Verificar `endorsementProtocol` no contrato

***

## Etapa 8b (condicional) — Aprovação de Pagamento

Só com `formalizationStrategy = GTBANKER` e `requiresPaymentApproval = true`. Nos demais casos o contrato vai direto para a Etapa 9. Ver [Aprovação de Pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/aprovacao-de-pagamento.md).

**Checklist:**

* [ ] Após `ENDORSEMENT_ENDORSED`, o contrato entra em `PENDING_PAYMENT_APPROVAL` (não é enviado ao GTBanker ainda)
* [ ] Aguardar webhook **`CONTRACT_PAYMENT_APPROVAL_REQUIRED`** (originador precisa estar inscrito no evento)
* [ ] Confirmar a aprovação: `POST /api/v1/originator/contracts/{contractNumber}/payment-approval` → `202 Accepted` com `status: ENDORSED`
* [ ] Contrato passa a `ENDORSED` e segue para a Etapa 9 (formalização no GTBanker)
* [ ] **Não prosseguir?** Use a [desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md) (`POST /api/v1/originator/contracts/exclude`); não há endpoint de rejeição

***

## Etapa 9 — Formalização

### Perfil A — formalizationStrategy GTBANKER

* [ ] Verificar webhook **`CCB_RECEIVED`** (source `GTBANKER`): contrato `FORMALIZED`
* [ ] Verificar webhook **`PAYMENT_SUCCESS`** (source `GTBANKER`): desembolso feito, contrato `COMPLETED`
* [ ] Correlacionar os dois eventos pelo `data.contract_public_id` (o `publicId` do contrato), não pelo `numero_ccb`, que pode chegar sem os zeros à esquerda

### Perfil B — formalizationStrategy ORIGINATOR\_MANAGED

* [ ] Após a averbação, contrato vai direto para `COMPLETED`; CCB e desembolso ficam com você
* [ ] Verificar que **não** chegam webhooks de source `GTBANKER`

***

## Webhooks por Etapa

| Webhook                              | Etapa                                                                               |  Contrato GIRO  | Contrato `ORIGINATOR_MANAGED` |
| ------------------------------------ | ----------------------------------------------------------------------------------- | :-------------: | :---------------------------: |
| `AUTHORIZATION_DOCUMENT_READY`       | 2 - Termo gerado pela Giro                                                          |        ✓        |               ✓               |
| `AUTHORIZATION_SIGNED`               | 2 - Termo assinado disponível                                                       | ✓ (se inscrito) |        ✓ (se inscrito)        |
| `AUTHORIZATION_COMPLETED`            | 3 - Enviar ao Dataprev                                                              |        ✓        |               ✓               |
| `AUTHORIZATION_EXPIRED`              | Autorização perdeu a validade; reautorizar                                          | ✓ (se inscrito) |        ✓ (se inscrito)        |
| `AUTHORIZATION_FAILED`               | 3 - Dataprev recusou em definitivo (CPF/vínculo inelegível) ou esgotou retentativas |        ✓        |               ✓               |
| `MARGIN_QUERY_COMPLETED`             | 4 - Consultar Margem (automático) e 4b - Margem por vínculo (com `requestId`)       |        ✓        |               ✓               |
| `AUTHORIZED_BONDS_LISTED`            | 4b - Listar vínculos (sob demanda)                                                  | ✓ (se inscrito) |        ✓ (se inscrito)        |
| `AUTHORIZED_BONDS_LISTING_FAILED`    | 4b - Listar vínculos (falha)                                                        | ✓ (se inscrito) |        ✓ (se inscrito)        |
| `CONTRACT_DOCUMENT_READY`            | 7 - Criar Contrato / link de assinatura                                             |        ✓        |               ✓               |
| `CONTRACT_SIGNED`                    | 7 - Contrato assinado (GIRO)                                                        | ✓ (se inscrito) |               -               |
| `ENDORSEMENT_PROCESSING`             | 8 - Averbação                                                                       |        ✓        |               ✓               |
| `ENDORSEMENT_ENDORSED`               | 8 - Averbação                                                                       |        ✓        |               ✓               |
| `CONTRACT_PAYMENT_APPROVAL_REQUIRED` | 8b - Aprovação de Pagamento (quando `requiresPaymentApproval`)                      | ✓ (se inscrito) |               -               |
| `CCB_RECEIVED`                       | 9 - Formalização                                                                    |        ✓        |               -               |
| `PAYMENT_SUCCESS`                    | 9 - Formalização                                                                    |        ✓        |               -               |

Payloads em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

***

## Referência Rápida — Endpoints

| Etapa                                                | Método | Path                                                                                     |
| ---------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Criar Employee                                       | POST   | `/api/v1/originator/employees`                                                           |
| Enviar Termo Assinado (envio direto)                 | POST   | `/api/v1/originator/employees/{publicId}/signed-authorizations`                          |
| Criar Documento Autorização (termo gerado pela Giro) | POST   | `/api/v1/originator/employees/{publicId}/authorization-documents`                        |
| Criar Trilha de Autorização (opt-in)                 | POST   | `/api/v1/originator/employees/{publicId}/authorization-trails`                           |
| Status Autorização                                   | GET    | `/api/v1/originator/employees/{publicId}/authorization/status`                           |
| Download Documento                                   | GET    | `/api/v1/originator/employees/{publicId}/authorization/{nsu}/document`                   |
| Upload Assinado (autorização)                        | POST   | `/api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed`              |
| Consultar Margem                                     | GET    | `/api/v1/originator/employees/{publicId}/margin`                                         |
| Solicitar Atualização de Margem                      | POST   | `/api/v1/originator/employees/{publicId}/margin`                                         |
| Listar Vínculos Autorizados (async)                  | POST   | `/api/v1/originator/employees/{publicId}/authorized-bonds-queries`                       |
| Resultado Listagem de Vínculos                       | GET    | `/api/v1/originator/authorized-bonds-queries/{requestId}`                                |
| Consultar Margem por Vínculo (async)                 | POST   | `/api/v1/originator/employees/{publicId}/authorized-bonds/{bondPublicId}/margin-queries` |
| Resultado Margem por Vínculo                         | GET    | `/api/v1/originator/margin-queries/{requestId}`                                          |
| Criar Simulação                                      | POST   | `/api/v1/originator/employees/{publicId}/simulations`                                    |
| Simular sem Vínculo (migração)                       | POST   | `/api/v1/originator/simulations`                                                         |
| Simular sem Vínculo por Parcela (migração)           | POST   | `/api/v1/originator/simulations/by-installment`                                          |
| Criar Proposta                                       | POST   | `/api/v1/originator/employees/{publicId}/proposals`                                      |
| Criar Contrato                                       | POST   | `/api/v1/originator/proposals/{proposalPublicId}/contracts`                              |
| Download Contrato                                    | GET    | `/api/v1/originator/contracts/{requestNumber}/document`                                  |
| Upload Assinado (contrato)                           | POST   | `/api/v1/originator/contracts/{requestNumber}/upload-signed`                             |
| Reenviar Link Contrato                               | POST   | `/api/v1/originator/contracts/{requestNumber}/resend`                                    |
| Consultar Contrato                                   | GET    | `/api/v1/originator/contracts/by-request-number/{requestNumber}`                         |
| Cancelar Contrato                                    | POST   | `/api/v1/originator/contracts/cancel`                                                    |
| Aprovação de Pagamento                               | POST   | `/api/v1/originator/contracts/{contractNumber}/payment-approval`                         |

***

## Collections Postman

### API Originator (referência completa)

Todos os endpoints da API Originator, por recurso:

{% file src="/files/29YjXyqQrkO9nCHKsO82" %}

Configure `baseUrl` e `originatorToken`.

### Fluxo E2E (automatizado)

Fluxo automatizado, com scripts que propagam variáveis entre requests:

{% file src="/files/VSarJSTIgYTsmgrDpAoM" %}

Configure `baseUrl`, `originatorTokenA` e `originatorTokenB` e rode cada pasta no Collection Runner com delay de 3-5 segundos.

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