> 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/upload-documento-assinado.md).

# Upload de Documento Assinado

Envia o PDF do termo de autorização já assinado, no último 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). A Giro envia o documento à Dataprev automaticamente.

* Requer o `NSU` retornado por [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) e o PDF assinado pelo trabalhador no seu provedor.
* **Sempre reautoriza:** mesmo com autorização Dataprev válida, o envio reautoriza na Dataprev e dispara uma **consulta de margem nova**, com custo real na Dataprev. Vale para o primeiro envio do `nsu` e para o reenvio. Para só conferir a situação, use [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md).
* **Reenvio:** se o `nsu` já está em `SIGNED`, `PROCESSED` ou `SUPERSEDED`, todo termo vivo do employee vira `SUPERSEDED` e um documento novo é criado em `SIGNED`, com **`nsu` novo**. A resposta traz o `nsu` novo, não o do path.
* Se já existe autorização em andamento para o employee, o reenvio aproveita o resultado dela.

## Request

`POST /api/v1/originator/employees/{publicId}/authorization/{nsu}/upload-signed`

| Parâmetro        | Local            | Tipo     | Descrição                                                        |
| ---------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `publicId`       | path             | `string` | Identificador público do employee (16 caracteres)                |
| `nsu`            | path             | `string` | NSU do documento de autorização (retornado ao criar o documento) |
| `signedDocument` | body (multipart) | file     | Arquivo PDF do termo de autorização assinado                     |

Content-Type: `multipart/form-data`, com um único campo de arquivo `signedDocument`.

## Response (200)

| Campo                           | Tipo            | Descrição                                                                                   |
| ------------------------------- | --------------- | ------------------------------------------------------------------------------------------- |
| `authorizationDocumentPublicId` | `string (uuid)` | Identificador público do documento                                                          |
| `nsu`                           | `string`        | NSU do documento (no reenvio, o novo)                                                       |
| `status`                        | `string`        | Status do envio: `PROCESSING` (documento recebido e em processamento), `SUCCESS` ou `ERROR` |
| `message`                       | `string`        | Mensagem descritiva                                                                         |

Depois, consulte o [status da autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md) até `AUTHORIZED` ou aguarde o webhook `AUTHORIZATION_COMPLETED`, seguido de `MARGIN_QUERY_COMPLETED` (a consulta de margem é automática; não é preciso chamar `GET /margin`).

## Exemplo

```http
POST /api/v1/originator/employees/abcd1234efgh5678/authorization/20250115000001/upload-signed
Authorization: Bearer {originatorToken}
Content-Type: multipart/form-data

signedDocument: [arquivo PDF]
```

Resposta:

```json
{
  "authorizationDocumentPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b07",
  "nsu": "20250115000001",
  "status": "PROCESSING",
  "message": "Documento recebido e enviado para processamento."
}
```

## Erros

| Código | `errorCode`                  | Situação                                                                                                                                                |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | —                            | `Documento de autorização não encontrado para NSU: <nsu>` — `nsu` inexistente, de outro originador ou de outro employee                                 |
| 400    | —                            | `Upload de documento de autorização assinado disponível apenas para ORIGINATOR_MANAGED`                                                                 |
| 400    | —                            | `Erro ao processar documento de autorização assinado` — falha ao processar o arquivo, inclusive transitória. Consulte o status e reenvie com chave nova |
| 404    | —                            | `Employee não encontrado` — inexistente ou de outro originador                                                                                          |
| 423    | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev                                                                                                                         |

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).

## Upload do documento de autorização assinado

> Envia o PDF do termo de autorização já assinado (ORIGINATOR\_MANAGED).\
> O documento é enviado automaticamente para o Dataprev após o upload.\
> \
> \*\*Sempre reautoriza:\*\* mesmo que o empregado já possua autorização Dataprev válida,\
> o envio do termo reautoriza na Dataprev (prazo renovado) e dispara uma consulta de\
> margem \*\*nova\*\* — isso tem custo real na Dataprev. Vale tanto para o\
> primeiro envio do \`nsu\` quanto para o reenvio. Para apenas consultar a situação,\
> use \`GET /{publicId}/authorization/status\`.\
> \
> \*\*Reenvio (documento já assinado):\*\* quando o \`nsu\` informado já está em estado\
> terminal de assinatura (\`SIGNED\`, \`PROCESSED\` ou \`SUPERSEDED\`), a requisição\
> \*\*não\*\* falha mais com \`400\`. Todo termo vivo do employee (\`SIGNED\` ou \`PROCESSED\`)\
> é congelado como \`SUPERSEDED\` (lastro imutável) e um documento novo é criado já em\
> \`SIGNED\`, com \*\*\`nsu\` novo\*\*, apontando para o PDF recém-enviado. O employee fica\
> sempre com um único termo assinado vivo, inclusive quando o \`nsu\` informado é antigo.\
> \
> A resposta traz o \`nsu\` do documento novo, não o informado no path.\
> \
> Quando já existe uma autorização em voo para o mesmo empregado, o reenvio não gera\
> um \`AUTHORIZE\_QUERY\` adicional — o resultado em voo atende os dois envios.<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/{nsu}/upload-signed":{"post":{"summary":"Upload do documento de autorização assinado","description":"Envia o PDF do termo de autorização já assinado (ORIGINATOR_MANAGED).\nO documento é enviado automaticamente para o Dataprev após o upload.\n\n**Sempre reautoriza:** mesmo que o empregado já possua autorização Dataprev válida,\no envio do termo reautoriza na Dataprev (prazo renovado) e dispara uma consulta de\nmargem **nova** — isso tem custo real na Dataprev. Vale tanto para o\nprimeiro envio do `nsu` quanto para o reenvio. Para apenas consultar a situação,\nuse `GET /{publicId}/authorization/status`.\n\n**Reenvio (documento já assinado):** quando o `nsu` informado já está em estado\nterminal de assinatura (`SIGNED`, `PROCESSED` ou `SUPERSEDED`), a requisição\n**não** falha mais com `400`. Todo termo vivo do employee (`SIGNED` ou `PROCESSED`)\né congelado como `SUPERSEDED` (lastro imutável) e um documento novo é criado já em\n`SIGNED`, com **`nsu` novo**, apontando para o PDF recém-enviado. O employee fica\nsempre com um único termo assinado vivo, inclusive quando o `nsu` informado é antigo.\n\nA resposta traz o `nsu` do documento novo, não o informado no path.\n\nQuando já existe uma autorização em voo para o mesmo empregado, o reenvio não gera\num `AUTHORIZE_QUERY` adicional — o resultado em voo atende os dois envios.\n","tags":["Authorization"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}},{"name":"nsu","in":"path","required":true,"description":"NSU do documento de autorização","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["signedDocument"],"properties":{"signedDocument":{"type":"string","format":"binary","description":"Arquivo PDF do termo assinado"}}}}}},"responses":{"200":{"description":"Upload realizado com sucesso. No reenvio de um documento já assinado, o `nsu`\nretornado é o do documento novo — diferente do informado no path.\n","content":{"application/json":{"schema":{"type":"object","description":"Resposta do upload do documento de autorização assinado.","properties":{"authorizationDocumentPublicId":{"type":"string","format":"uuid","nullable":true,"description":"Identificador público opaco do documento de autorização. Pode vir ausente em registros antigos."},"nsu":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","SUCCESS","ERROR"],"description":"Status do envio do documento para processamento Dataprev"},"message":{"type":"string"}}}}}},"400":{"description":"`nsu` inválido, estratégia diferente de `ORIGINATOR_MANAGED`, ou falha ao processar o arquivo (pode ser transitória — reenvie com chave nova).","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**."}}}}}}}},"409":{"description":"Documento em transição de estado durante o reenvio: outra requisição simultânea\nsobre o mesmo `nsu` reivindicou o documento primeiro. Só uma delas cria o documento\nnovo. Repetir a requisição resolve e reenvia de novo.\n","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."}}}}}}}},"502":{"description":"Falha ao fazer upload do documento para o armazenamento","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**."}}}}}}}}}}}}}
```
