> 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/estrategias-de-assinatura.md).

# Estratégias de Assinatura

Quem coleta cada assinatura: a da **autorização Dataprev** e a do **contrato (CCB)**. As duas são configuradas de forma independente, por originador, no onboarding.

| Assinatura               | Quem gerencia                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| **Autorização Dataprev** | Sempre o **originador**: você coleta o aceite (termo em PDF ou opt-in em trilha) e envia à Giro     |
| **Contrato (CCB)**       | **GIRO** (a Giro.Tech coleta a assinatura) ou **ORIGINATOR\_MANAGED** (você coleta no seu provedor) |

***

## Autorização Dataprev

Você sempre coleta o aceite. O que muda é a forma do lastro, e a escolha é **por trabalhador** (os dois caminhos convivem):

| Caminho                    | Evidência custodiada                                               | Página                                                                                                                             |
| -------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Termo em PDF**           | PDF do termo assinado pelo trabalhador                             | [Termo em PDF](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf.md)                     |
| **Termo em Trilha Opt-In** | Trilha de aceite (IP, timestamp, sessão, fingerprint), **sem PDF** | [Termo em Trilha Opt-In](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in.md) |

Nos dois, o resultado é o trabalhador autorizado na Dataprev e o webhook `AUTHORIZATION_COMPLETED`.

### Termo em PDF — quem gera o documento

1. **Termo próprio (1 chamada)** — `POST /api/v1/originator/employees/{publicId}/signed-authorizations` Você gera o termo, coleta a assinatura e envia o PDF assinado em base64. A chamada gera o NSU e a autorização segue à Dataprev. Ver [Enviar Termo Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md).
2. **Termo gerado pela Giro (3 chamadas)** — ver [Termo Gerado pela Giro](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro.md):
   * **Criar documento** — `POST /api/v1/originator/employees/{publicId}/authorization-documents` Reserva o **NSU** e gera o PDF. Nenhum link é enviado ao trabalhador.
   * **Upload do assinado** — `POST /api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed` Envie o PDF assinado (multipart `signedDocument`); a autorização segue à Dataprev.
   * **Consultar status** — `GET /api/v1/originator/employees/{publicId}/authorization/status` Acompanhe até `AUTHORIZED`. Ao fim chega `AUTHORIZATION_COMPLETED`. Se a Dataprev recusar em definitivo (CPF/vínculo inelegível ou tentativas esgotadas), chega **`AUTHORIZATION_FAILED`** e o documento fica `INELIGIBLE`.

```mermaid
sequenceDiagram
    participant O as Originador
    participant P as GTPayroll
    O->>P: POST /api/v1/originator/employees/{publicId}/authorization-documents
    P-->>O: nsu, status PENDING
    P-->>O: webhook AUTHORIZATION_DOCUMENT_READY (presignedUrl)
    Note over O: Baixa o termo e coleta a assinatura
    O->>P: POST /api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed
    P-->>O: nsu, status PROCESSING
    Note over P: Envia para Dataprev
    P-->>O: webhook AUTHORIZATION_COMPLETED
```

### Termo em Trilha Opt-In

Você coleta o **opt-in** no seu canal digital (app/site) e envia a **trilha de aceite** por API, sem PDF. A Giro custodia a trilha como lastro e autoriza na Dataprev pelo canal digital **Web Correspondente**.

Exige o originador habilitado como `ORIGINATOR_MANAGED` em `authorizationSignatureStrategy`; sem isso, `403 ORIGINATOR_OPT_IN_NOT_ENABLED`.

1. O trabalhador aceita o opt-in no seu canal.
2. Você monta a **trilha**: IP, timestamp, sessão, fingerprint e, opcionalmente, a timeline `events[]` em texto livre.
3. Chame `POST /api/v1/originator/employees/{publicId}/authorization-trails` ([Criar Trilha de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md)).
4. A Giro confere o CPF da trilha contra o do employee (divergente: `422 CPF_MISMATCH`), guarda a trilha amarrada ao NSU e envia a autorização à Dataprev.
5. Chegam `AUTHORIZATION_COMPLETED` e, em seguida, `MARGIN_QUERY_COMPLETED`.

**Responsabilidade probatória.** Na trilha, você **atesta** que coletou o aceite e responde pela robustez da trilha. A Giro custodia o lastro, amarrado ao NSU. A trilha **não vai para a Dataprev**, que recebe só canal, data/hora, NSU e CPF. Ver [Trilha de Auditoria](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/trilha-de-auditoria.md).

{% hint style="info" %}
Os dois caminhos também podem ser disparados **no cadastro do trabalhador**, 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).
{% endhint %}

### Diferença entre os dois caminhos

| Aspecto                         | Termo em PDF                                                                    | Termo em Trilha Opt-In                               |
| ------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Quem coleta o aceite**        | O originador, no provedor de assinatura dele                                    | O originador, no canal digital dele                  |
| **Documento PDF**               | Sim                                                                             | **Não**                                              |
| **Quem gera o termo**           | A Giro ou o originador                                                          | Não se aplica                                        |
| **Endpoint**                    | `POST .../signed-authorizations` ou `POST .../authorization-documents` + upload | `POST .../employees/{publicId}/authorization-trails` |
| **Evidência (lastro)**          | PDF assinado + metadados                                                        | Trilha: IP, timestamp, sessão, fingerprint, device   |
| **Canal Dataprev**              | `Web Cliente` / `Agência`                                                       | `Web Correspondente` (canal 4)                       |
| **Responsabilidade probatória** | Compartilhada (Giro custodia o termo)                                           | **Do originador**; a Giro custodia a trilha          |
| **Latência**                    | Maior (PDF + espera da assinatura)                                              | Menor                                                |
| **Estado final**                | `Employee` autorizado + `AUTHORIZATION_COMPLETED`                               | **Idêntico**                                         |

***

## Contrato (CCB)

### Estratégia GIRO (padrão)

A Giro.Tech coleta a assinatura da CCB; você não implementa fluxo de assinatura.

```
1. Originador cria contrato via API
2. GTPayroll gera o PDF da CCB
3. Trabalhador recebe o link de assinatura por WhatsApp
4. Trabalhador assina digitalmente
5. Contrato assinado → averbação → desembolso
```

Você consome a `signUrl` (no webhook `CONTRACT_DOCUMENT_READY`) e o webhook `CONTRACT_SIGNED`.

**`suppressNotification: true`** na criação do contrato: a plataforma **não envia** o WhatsApp ao trabalhador. O link chega só na `signUrl` do `CONTRACT_DOCUMENT_READY`, e notificar o trabalhador passa a ser seu.

| Etapa                       | Endpoint                                       |
| --------------------------- | ---------------------------------------------- |
| Criar contrato              | `POST /proposals/{proposalPublicId}/contracts` |
| Reenviar link de assinatura | `POST /contracts/{requestNumber}/resend`       |

### Estratégia ORIGINATOR\_MANAGED

Você coleta a assinatura da CCB no seu provedor. O GTPayroll gera o documento, mas **não envia para assinatura**.

1. **Criar contrato** — `POST /api/v1/originator/proposals/{proposalPublicId}/contracts` O GTPayroll gera o PDF e envia o webhook **`CONTRACT_DOCUMENT_READY`** com `requestNumber`, `contractNumber`, `nsu` e `presignedUrl` do PDF.
2. **Baixar documento (opcional)** — `GET /api/v1/originator/contracts/{requestNumber}/document` Metadados e nova `presignedUrl` (ex.: a do webhook expirou).
3. **Upload do assinado** — `POST /api/v1/originator/contracts/{requestNumber}/upload-signed` PDF assinado em multipart `signedDocument`. O contrato segue para averbação e, conforme a estratégia de formalização, para desembolso ou conclusão.

{% hint style="warning" %}
Nesta estratégia, **reenviar link de assinatura** envia um webhook para você, que faz o reenvio pelo seu provedor.
{% endhint %}

### Comparativo (contrato)

| Aspecto                                     | GIRO                      | ORIGINATOR\_MANAGED       |
| ------------------------------------------- | ------------------------- | ------------------------- |
| Geração do PDF                              | GTPayroll                 | GTPayroll                 |
| Envio para assinatura e notificação         | Giro (WhatsApp)           | Originador                |
| Recebimento do assinado                     | Automático                | Upload via API            |
| Webhook `CONTRACT_SIGNED`                   | Sim (inscrição no evento) | Não aplicável             |
| Reenvio de link                             | API `resend`              | Webhook para o originador |
| Esforço de integração                       | Baixo                     | Médio-alto                |
| Controle sobre a experiência do trabalhador | Limitado                  | Total                     |

Sem provedor de assinatura próprio, use **GIRO**. Se já tem provedor, precisa de um específico por compliance ou quer controlar a experiência, use **ORIGINATOR\_MANAGED**.

***

## Estratégia de Formalização

Define como a CCB é processada após a averbação. É independente da estratégia de assinatura e também configurada no onboarding.

| Estratégia              | Descrição                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **GTBANKER**            | Formalização da CCB e desembolso pela plataforma de correspondente bancário da Giro |
| **ORIGINATOR\_MANAGED** | Originador gerencia a formalização                                                  |

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