> 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/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/criar-documento-autorizacao.md).

# Criar Documento de Autorização

Reserva o `NSU` e dispara a geração do termo de autorização em PDF pela Giro. É o primeiro passo do fluxo [Termo Gerado pela Giro](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro.md).

* Só é necessário quando a Giro gera o termo, ou quando você precisa do `NSU` antes da assinatura (por exemplo, para carimbá-lo no documento). Com o PDF já assinado pelo seu sistema, use [Enviar Termo Assinado (envio direto)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md); chamar este endpoint cria um registro que não será usado.
* A resposta vem com `status: PENDING`: o termo ainda não existe. Quando o PDF fica pronto chega o webhook **`AUTHORIZATION_DOCUMENT_READY`** com a `presignedUrl`. Não baixe nem suba o assinado antes disso.
* Se já existe documento pendente (`PENDING`, `GENERATED`, `PENDING_SIGNATURE` ou `SIGNATURE_PENDING_RETRY`) e não expirado, o endpoint retorna esse documento em vez de criar outro.
* O termo não é criado ao cadastrar o employee: a autorização começa por este endpoint ou por [Enviar Termo Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md).

## Request

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

| Parâmetro  | Local | Tipo     | Descrição                                         |
| ---------- | ----- | -------- | ------------------------------------------------- |
| `publicId` | path  | `string` | Identificador público do employee (16 caracteres) |

Sem corpo.

## Response (201)

| Campo         | Tipo                 | Descrição                                                                                                                                                                                       |
| ------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nsu`         | `string`             | NSU do documento. Use no [upload do assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro/upload-documento-assinado.md). |
| `status`      | `string`             | Status do documento (`PENDING`, `GENERATED`, `PENDING_SIGNATURE`, `SIGNATURE_PENDING_RETRY`, `SIGNED`, `REJECTED`, `EXPIRED`, `CANCELLED`, `FAILED`, `PROCESSED`, `INELIGIBLE`, `SUPERSEDED`)   |
| `createdDate` | `string` (date-time) | Data de criação do documento                                                                                                                                                                    |

## Exemplo

```http
POST /api/v1/originator/employees/abcd1234efgh5678/authorization-documents
Authorization: Bearer {originatorToken}
```

Resposta:

```json
{
  "nsu": "20250115000001",
  "status": "PENDING",
  "createdDate": "2025-01-15T10:00:00Z"
}
```

Próximos passos: aguardar `AUTHORIZATION_DOCUMENT_READY`, coletar a assinatura no seu provedor e enviar por [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). O envio à Dataprev é automático.

## Erros

| Código  | `errorCode`                  | Situação                                                                                                                                                                                  |
| ------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 404     | —                            | `Employee não encontrado` — inexistente ou de outro originador                                                                                                                            |
| 423     | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev                                                                                                                                                           |
| webhook | —                            | Falha na geração ou assinatura do termo chega por `AUTHORIZATION_DOCUMENT_FAILED` (`RETRY_EXHAUSTED`, `SIGNATURE_REJECTED`, `SIGNATURE_EXPIRED`, `SIGNATURE_CANCELLED`, `FRAUD_DETECTED`) |

Erros comuns a todos os endpoints — `401`, `403` de token, `409` de `Idempotency-Key` em processamento, `500` e `503` — e o formato `ProblemDetail` estão em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

## Criar documento de autorização

> Cria um documento de autorização para o employee (estratégia ORIGINATOR\_MANAGED).\
> Retorna o NSU para uso no upload do documento assinado.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Authorization","description":"Autorização Dataprev para consulta de dados"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/employees/{publicId}/authorization-documents":{"post":{"summary":"Criar documento de autorização","description":"Cria um documento de autorização para o employee (estratégia ORIGINATOR_MANAGED).\nRetorna o NSU para uso no upload do documento assinado.\n","tags":["Authorization"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}}],"responses":{"201":{"description":"Documento criado com sucesso","content":{"application/json":{"schema":{"type":"object","description":"Resposta da criação do documento de autorização. O `201` volta com `status: PENDING` —\na geração do PDF é assíncrona e o termo ainda não existe nesse instante. Aguarde o webhook\n`AUTHORIZATION_DOCUMENT_READY` antes de baixar o documento.\n","properties":{"nsu":{"type":"string","description":"NSU do documento gerado"},"status":{"type":"string","enum":["PENDING","GENERATED","PENDING_SIGNATURE","SIGNATURE_PENDING_RETRY","SIGNED","REJECTED","EXPIRED","CANCELLED","FAILED","PROCESSED","INELIGIBLE","SUPERSEDED"],"description":"Status do documento"},"createdDate":{"type":"string","format":"date-time","description":"Data de criação do documento"}}}}}},"400":{"description":"Dados inválidos (inclui cenários de validação e vínculo inválido entre identificadores) ou estratégia não é ORIGINATOR_MANAGED","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"401":{"description":"Não autenticado","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"Employee não encontrado ou de outro originador.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}}}}}}}
```
