> 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/ciclo-de-vida-da-autorizacao.md).

# Ciclo de Vida da Autorização e Re-autorização

A autorização Dataprev (consulta de margem via CTPS Digital) vence. Este guia mostra a validade, como a consulta de margem sinaliza o vencimento e como re-autorizar.

{% hint style="info" %}
Vale para os dois caminhos de autorização, **termo em PDF** e **trilha opt-in**: ambos terminam em `AUTHORIZATION_COMPLETED` e seguem o mesmo ciclo de vida. Comparação dos caminhos em [Autorização (API Reference)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md#os-dois-caminhos-lado-a-lado).
{% endhint %}

***

## Validade da autorização

| Prazo                               | Duração                        | O que significa                                                                                     |
| ----------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Termo (manifestação de vontade)** | **30 dias** a partir do aceite | Validade legal da autorização, no PDF ou na trilha. Vencido, exige **novo aceite** (re-autorização) |
| **Token de consulta**               | Curto                          | Renovado pela plataforma sem novo aceite enquanto o termo for válido. Você não precisa gerenciá-lo  |

```mermaid
flowchart LR
    A1[Trabalhador assina o termo<br/>termo em PDF] --> B[Autorização ativa<br/>margem disponível]
    A2[Trabalhador aceita opt-in<br/>trilha · sem PDF] --> B
    B -->|"token expira (curto)"| C[Plataforma renova o token<br/>automaticamente · mesmo termo]
    C --> B
    B -->|"termo expira (30 dias)"| D[Termo vencido<br/>margem retorna TERM_EXPIRED]
    D -->|"novo termo assinado"| A1
    D -->|"nova trilha de opt-in"| A2
```

***

## Status do documento de autorização

Retornado por [Consultar Status da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md):

| Status                  | Significado                                                   | O que fazer                             |
| ----------------------- | ------------------------------------------------------------- | --------------------------------------- |
| `PENDING` / `GENERATED` | Documento criado / PDF pronto, aguardando assinatura          | Coletar a assinatura e subir o assinado |
| `PENDING_SIGNATURE`     | Assinatura iniciada                                           | Aguardar                                |
| `SIGNED`                | Assinado; autorização válida                                  | Consultar a margem                      |
| `PROCESSED`             | Assinado e processado pela Dataprev                           | —                                       |
| `EXPIRED`               | A **janela de assinatura** venceu sem o assinado ser recebido | Gerar novo documento                    |
| `INELIGIBLE`            | CPF/vínculo inelegível na Dataprev (falha permanente)         | Não há margem para este trabalhador     |
| `SUPERSEDED`            | Substituído por uma re-autorização e mantido como lastro      | Nenhuma; o novo documento é o vigente   |

* `PENDING`, `GENERATED`, `PENDING_SIGNATURE`, `SIGNED` e `EXPIRED` só existem no **termo em PDF**. Na trilha não há PDF nem janela de assinatura.
* O envio da trilha ([Criar Trilha de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md)) retorna sempre `status` = `PROCESSING`, com `dataprevAuthorizationStatus` (ex.: `PENDING_SUBMISSION`, `AUTHORIZED`).
* **Todo envio de termo ou trilha reautoriza**: o documento anterior vira `SUPERSEDED` (a evidência do aceite original nunca é sobrescrita) e um novo documento, com **novo NSU**, passa a valer.

***

## Consulta de margem com termo expirado

[Consultar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md) com termo vencido responde **`200`** (não é erro nem `202`):

```json
{
  "status": "TERM_EXPIRED",
  "reason": "Autorização expirada, necessário re-autorizar"
}
```

{% hint style="warning" %}
`200` não quer dizer margem disponível: **sempre inspecione `status`**. **Não há webhook de termo expirado**: `MARGIN_QUERY_COMPLETED` / `MARGIN_QUERY_FAILED` só saem na conclusão da consulta ou em falha permanente da Dataprev.
{% endhint %}

***

## Como re-autorizar

Repita o fluxo de autorização, como na primeira vez, conforme a sua [estratégia de assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md). O caminho é escolhido por trabalhador e não precisa ser o mesmo do aceite original. Não é preciso cancelar o termo anterior.

**Caminho A —** [**Termo em PDF**](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf.md)

1. Envie o termo assinado direto ([Enviar Termo Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md)) ou peça um novo termo à Giro ([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) seguido de [Upload de Documento Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/upload-documento-assinado.md)).
2. O trabalhador assina de novo e é gerado um novo termo (novo NSU).

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

1. O trabalhador aceita de novo o opt-in no seu canal digital.
2. Envie a nova trilha em [`POST .../authorization-trails`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md): novo termo (novo NSU), sem PDF.

Nos dois caminhos, o termo anterior vira `SUPERSEDED` e, concluída a nova autorização (webhook `AUTHORIZATION_COMPLETED`), a consulta de margem volta a responder normalmente.

```mermaid
sequenceDiagram
    autonumber
    participant O as Originador
    participant API as GTPayroll
    participant T as Trabalhador
    O->>API: GET /margin (termo vencido)
    API-->>O: 200 { status: TERM_EXPIRED }
    alt Caminho A — termo em PDF
        O->>T: Coleta nova assinatura no provedor próprio
        T-->>O: Termo assinado
        O->>API: Envia o assinado (signed-authorizations ou upload-signed)
        Note over API: novo termo / novo NSU
    else Caminho B — trilha opt-in
        T->>O: Re-coleta o opt-in no canal digital
        O->>API: POST .../authorization-trails (nova trilha)
        Note over API: novo termo / novo NSU (sem PDF)
    end
    Note over API: termo anterior → SUPERSEDED (lastro)
    API-->>O: webhook AUTHORIZATION_COMPLETED quando concluir
    O->>API: GET /margin
    API-->>O: 200 { status: OK, employmentRelationships: [...] }
```

***

## Autorização rejeitada (`AUTHORIZATION_FAILED`)

Se a Dataprev rejeitar a autorização (CPF/vínculo inelegível, trabalhador não encontrado ou tentativas esgotadas), chega o webhook **`AUTHORIZATION_FAILED`** e o documento fica `INELIGIBLE`. Em geral a causa é cadastral.

Para tentar de novo, re-autorize como acima; não há limite de tentativas. A Dataprev só é consultada **depois** que o novo termo é assinado (gerar o termo não basta), e só adianta **se a causa foi corrigida** (ex.: vínculo regularizado no eSocial). Sem isso, volta `AUTHORIZATION_FAILED`.

***

## Resumo

| Situação                    | Resposta da margem                                               | Ação do originador                                              |
| --------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| Termo válido, margem pronta | `200` · `status: OK`                                             | Prosseguir para a simulação                                     |
| Consulta em andamento       | `202` · `status: PROCESSING`                                     | Aguardar e consultar de novo                                    |
| **Termo expirado**          | `200` · `status: TERM_EXPIRED`                                   | **Re-autorizar** (novo termo assinado ou nova trilha de opt-in) |
| CPF/vínculo inelegível      | falha permanente · webhook `AUTHORIZATION_FAILED` · `INELIGIBLE` | Corrigir a causa e re-autorizar                                 |
