> 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/enviar-termo-assinado-direto.md).

# Enviar Termo Assinado (envio direto)

Envia, em uma chamada, o termo de autorização já assinado pelo trabalhador. O documento é criado já em `SIGNED`, com um `NSU` novo devolvido na resposta, e a autorização Dataprev é disparada automaticamente. Dispensa [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 [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).

## Quando usar cada um

| Critério              | **Enviar Termo Assinado** (esta página)     | **Criar Documento + Upload**                                                                 | **Criar Trilha (opt-in)**                                                                                                                                                       |
| --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chamadas**          | 1                                           | 2 (+ download do PDF, se a Giro gerar)                                                       | 1                                                                                                                                                                               |
| **Endpoint(s)**       | `POST .../{publicId}/signed-authorizations` | `POST .../{publicId}/authorization-documents` → `POST .../authorization/{nsu}/upload-signed` | `POST .../{publicId}/authorization-trails`                                                                                                                                      |
| **Quem gera o termo** | Você                                        | A Giro                                                                                       | Não há PDF                                                                                                                                                                      |
| **Lastro enviado**    | PDF assinado (base64)                       | PDF assinado (multipart)                                                                     | [Trilha de opt-in](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md) (IP, sessão, fingerprint) |
| **NSU**               | Gerado pela chamada                         | Reservado antes da assinatura, no `Criar Documento`                                          | Gerado pela chamada                                                                                                                                                             |
| **Use quando**        | Você já tem o PDF assinado pelo seu sistema | Você quer o termo da Giro, ou precisa do `NSU` antes para carimbá-lo no documento            | Você coleta o opt-in no seu canal digital, sem PDF                                                                                                                              |

Nos três:

* O originador precisa estar habilitado na estratégia `ORIGINATOR_MANAGED`; sem isso, `403`.
* A escolha é por trabalhador.
* O envio à Dataprev é automático, e o acompanhamento é pelos webhooks `AUTHORIZATION_COMPLETED` / `AUTHORIZATION_FAILED` ou por [Consultar Status](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md).

## Request

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

| Parâmetro         | Local  | Tipo               | Descrição                                         |
| ----------------- | ------ | ------------------ | ------------------------------------------------- |
| `publicId`        | path   | `string`           | Identificador público do employee (16 caracteres) |
| `Idempotency-Key` | header | `string` (max 255) | Opcional. Ver [Idempotência](#idempotencia)       |

### Corpo

| Campo            | Tipo                 | Obrigatório | Descrição                                                                                                                                                                                                       |
| ---------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signedDocument` | `string` (base64)    | Sim         | PDF do termo assinado, em base64. O conteúdo decodificado precisa começar com `%PDF` e ter até **10 MB (10.485.760 bytes)**. A string base64 tem até 15.000.000 caracteres (base64 aumenta o tamanho em \~33%). |
| `documentNumber` | `string`             | Sim         | CPF do trabalhador, com ou sem máscara. Precisa ser o CPF do employee, senão `422`.                                                                                                                             |
| `fileName`       | `string` (max 255)   | Não         | Nome original do arquivo.                                                                                                                                                                                       |
| `signedAt`       | `string` (date-time) | Não         | Instante da assinatura, ISO-8601. Não pode ser futuro. Ausente, vale o instante do recebimento.                                                                                                                 |

O `signedDocument` é validado antes de qualquer gravação, nesta ordem: base64 válido, conteúdo não vazio, tamanho, assinatura `%PDF`. Arquivo que não é PDF é rejeitado mesmo com extensão `.pdf`.

## Response (202)

| Campo                         | Tipo     | Descrição                                                                                                    |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `status`                      | `string` | Sempre `PROCESSING`: documento gravado e autorização Dataprev enfileirada.                                   |
| `nsu`                         | `string` | NSU do documento criado nesta chamada.                                                                       |
| `dataprevAuthorizationStatus` | `string` | Status da autorização Dataprev do employee no momento da resposta (ex.: `PENDING_SUBMISSION`, `AUTHORIZED`). |

Depois do `202`, 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`. A consulta de margem é disparada automaticamente em seguida, com um `MARGIN_QUERY_COMPLETED` por vínculo.

{% hint style="warning" %}
**Enviar termo sempre reautoriza.** Mesmo com autorização Dataprev válida, cada envio cria um `nsu` novo, reautoriza na Dataprev e dispara uma **consulta de margem nova**, com custo real na Dataprev, e gera os dois webhooks de novo. O endpoint não retorna `200`/`ALREADY_AUTHORIZED`.

Para só conferir a situação, use [Consultar Status da Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/consultar-status-autorizacao.md). Para atualizar a margem, use o fluxo por vínculo (`authorized-bonds/{bondPublicId}/margin-queries`).
{% endhint %}

## Exemplo

```http
POST /api/v1/originator/employees/abcd1234efgh5678/signed-authorizations
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: 7d9f3a1c-5b2e-4c8a-9f1d-2e6b8c0a4d31

{
  "signedDocument": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI...",
  "documentNumber": "52998224725",
  "fileName": "termo-autorizacao-assinado.pdf",
  "signedAt": "2026-07-24T12:00:00Z"
}
```

Resposta `202`:

```json
{
  "status": "PROCESSING",
  "nsu": "140520251000000123",
  "dataprevAuthorizationStatus": "PENDING_SUBMISSION"
}
```

No reenvio para trabalhador já autorizado a resposta tem a mesma forma, com `nsu` novo.

## Idempotência

Replays com a mesma `Idempotency-Key` retornam a mesma resposta, com o header `Idempotency-Replayed: true`. Sem a chave não há idempotência por estado: cada envio é um aceite novo e reautoriza. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md).

## Erros

| Código | `errorCode`                      | Situação                                                                                                                                                                             |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | —                                | `signedDocument` ou `documentNumber` ausente, CPF inválido, `signedAt` no futuro, `fileName` acima de 255 caracteres, `signedDocument` acima do tamanho máximo (`properties.errors`) |
| 400    | —                                | JSON malformado (`type: about:blank`)                                                                                                                                                |
| 400    | `SIGNED_DOCUMENT_INVALID_BASE64` | `signedDocument` não é Base64 válido                                                                                                                                                 |
| 400    | `SIGNED_DOCUMENT_EMPTY`          | Documento decodificado vazio                                                                                                                                                         |
| 400    | `SIGNED_DOCUMENT_NOT_PDF`        | Documento decodificado não começa com `%PDF`                                                                                                                                         |
| 403    | `ORIGINATOR_OPT_IN_NOT_ENABLED`  | Originador fora de `ORIGINATOR_MANAGED`                                                                                                                                              |
| 404    | —                                | Employee não encontrado ou de outro originador                                                                                                                                       |
| 413    | `SIGNED_DOCUMENT_TOO_LARGE`      | Documento decodificado acima de 10.485.760 bytes                                                                                                                                     |
| 422    | `CPF_MISMATCH`                   | `documentNumber` diferente do CPF do employee                                                                                                                                        |
| 423    | `DATAPREV_SUSPENSION_WINDOW`     | Janela de suspensão da Dataprev                                                                                                                                                      |
| 429    | —                                | Mais de 75 requisições por segundo                                                                                                                                                   |
| 502    | —                                | Falha ao armazenar o documento. Nada é gravado; reenvie com chave nova                                                                                                               |

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

## Enviar documento de autorização já assinado

> Endpoint \*\*B2B\*\* para o originador que já possui o termo de autorização assinado\
> pelo trabalhador. Diferente do fluxo em duas chamadas\
> (\`POST /authorization-documents\` para a Giro gerar o PDF, depois\
> \`POST /authorization/{nsu}/upload-signed\`), aqui \*\*o documento assinado é enviado\
> direto\*\*: a Giro não gera PDF nenhum.\
> \
> É o gêmeo de \`POST /authorization-trails\` — mesma ideia, trocando a trilha de\
> opt-in por um PDF assinado como lastro.\
> \
> \*\*Fluxo:\*\* a requisição valida o vínculo, armazena o PDF, cria o\
> \`AuthorizationDocument\` já em \`SIGNED\` com um \`nsu\` novo e enfileira a autorização\
> Dataprev (canal \`ORIGINATOR\_UPLOAD\`, provider \`ORIGINATOR\`). Quando a\
> resposta \`202\` chega, o documento já está persistido com lastro; o que continua\
> assíncrono é o processamento da autorização na Dataprev.\
> \
> \*\*Pré-condições:\*\*\
> \- Originador autenticado deve ser o dono do \`publicId\` informado.\
> \- Originador deve estar configurado com\
> &#x20; \`authorizationSignatureStrategy=ORIGINATOR\_MANAGED\` (senão \`403\`).\
> \- \`documentNumber\` deve casar com o CPF do empregado (senão \`422\`).\
> \- \`signedDocument\` deve ser um PDF em base64 (o decodificado precisa começar\
> &#x20; com \`%PDF\`), de no máximo 10 MB.\
> \
> \*\*Sempre reautoriza:\*\* mesmo que o empregado já possua autorização Dataprev válida,\
> o envio cria um \`nsu\` novo, reautoriza na Dataprev e dispara uma consulta de margem\
> \*\*nova\*\* — isso tem custo real na Dataprev. A resposta é sempre \`202\`\
> com \`status=PROCESSING\`; \`ALREADY\_AUTHORIZED\` não é mais retornado. Para apenas\
> consultar a situação, use \`GET /{publicId}/authorization/status\`.\
> \
> \*\*Eventos:\*\* o \`AUTHORIZATION\_COMPLETED\` é sempre emitido ao fim do processamento,\
> seguido do \`MARGIN\_QUERY\_COMPLETED\` por vínculo. Quando já existe uma autorização\
> em voo para o mesmo empregado, o envio não gera um \`AUTHORIZE\_QUERY\` adicional —\
> o resultado em voo atende os dois envios e o webhook sai por ele.\
> \
> O header opcional \`Idempotency-Key\` vale para todo \`POST\` sob \`/api/v1/originator/\*\` (replays retornam a mesma resposta,\
> com o header \`Idempotency-Replayed: true\`).<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}/signed-authorizations":{"post":{"summary":"Enviar documento de autorização já assinado","description":"Endpoint **B2B** para o originador que já possui o termo de autorização assinado\npelo trabalhador. Diferente do fluxo em duas chamadas\n(`POST /authorization-documents` para a Giro gerar o PDF, depois\n`POST /authorization/{nsu}/upload-signed`), aqui **o documento assinado é enviado\ndireto**: a Giro não gera PDF nenhum.\n\nÉ o gêmeo de `POST /authorization-trails` — mesma ideia, trocando a trilha de\nopt-in por um PDF assinado como lastro.\n\n**Fluxo:** a requisição valida o vínculo, armazena o PDF, cria o\n`AuthorizationDocument` já em `SIGNED` com um `nsu` novo e enfileira a autorização\nDataprev (canal `ORIGINATOR_UPLOAD`, provider `ORIGINATOR`). Quando a\nresposta `202` chega, o documento já está persistido com lastro; o que continua\nassíncrono é o processamento da autorização na Dataprev.\n\n**Pré-condições:**\n- Originador autenticado deve ser o dono do `publicId` informado.\n- Originador deve estar configurado com\n  `authorizationSignatureStrategy=ORIGINATOR_MANAGED` (senão `403`).\n- `documentNumber` deve casar com o CPF do empregado (senão `422`).\n- `signedDocument` deve ser um PDF em base64 (o decodificado precisa começar\n  com `%PDF`), de no máximo 10 MB.\n\n**Sempre reautoriza:** mesmo que o empregado já possua autorização Dataprev válida,\no envio cria um `nsu` novo, reautoriza na Dataprev e dispara uma consulta de margem\n**nova** — isso tem custo real na Dataprev. A resposta é sempre `202`\ncom `status=PROCESSING`; `ALREADY_AUTHORIZED` não é mais retornado. Para apenas\nconsultar a situação, use `GET /{publicId}/authorization/status`.\n\n**Eventos:** o `AUTHORIZATION_COMPLETED` é sempre emitido ao fim do processamento,\nseguido do `MARGIN_QUERY_COMPLETED` por vínculo. Quando já existe uma autorização\nem voo para o mesmo empregado, o envio não gera um `AUTHORIZE_QUERY` adicional —\no resultado em voo atende os dois envios e o webhook sai por ele.\n\nO header opcional `Idempotency-Key` vale para todo `POST` sob `/api/v1/originator/*` (replays retornam a mesma resposta,\ncom o header `Idempotency-Replayed: true`).\n","tags":["Authorization"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Identificador público do employee (16 caracteres)","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência opcional. Quando presente, requisições repetidas com a\nmesma chave retornam a mesma resposta (header `Idempotency-Replayed: true`).\nA chave é retida por 7 dias. Depois desse prazo ela é expurgada e uma\nrequisição com a mesma chave é tratada como nova, sendo reprocessada.\n","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envio do termo de autorização já assinado pelo trabalhador, em base64.\n","required":["signedDocument","documentNumber"],"properties":{"signedDocument":{"type":"string","format":"byte","minLength":1,"description":"PDF do termo assinado, codificado em base64. O conteúdo decodificado precisa\ncomeçar com `%PDF` e não pode passar de 10 MB.\n"},"documentNumber":{"type":"string","minLength":11,"maxLength":14,"description":"CPF do trabalhador, com ou sem máscara. Deve casar com o CPF do empregado\nidentificado por `publicId` (senão `422`).\n"},"fileName":{"type":"string","maxLength":255,"description":"Nome original do arquivo, guardado junto do documento."},"signedAt":{"type":"string","format":"date-time","description":"Momento da assinatura pelo trabalhador. Quando ausente, o instante do\nrecebimento é usado. Não pode ser futuro.\n"}}}}}},"responses":{"202":{"description":"Documento aceito; `nsu` emitido. O envio ao armazenamento e o disparo da\nautorização Dataprev acontecem de forma assíncrona. Replays de\n`Idempotency-Key` retornam esta mesma resposta com `Idempotency-Replayed: true`.\n","content":{"application/json":{"schema":{"type":"object","description":"Resposta do envio direto do termo de autorização já assinado.\nO documento já está persistido quando a resposta chega; o processamento da\nautorização na Dataprev é que segue assíncrono.\n","properties":{"status":{"type":"string","enum":["PROCESSING"],"description":"Sempre `PROCESSING` (reusa `SendAuthorizationStatus`). O envio do termo **sempre**\ncria documento novo e reautoriza, mesmo com autorização válida vigente — por isso\n`ALREADY_AUTHORIZED` não é mais retornado por este endpoint.\n"},"nsu":{"type":"string","description":"NSU do `AuthorizationDocument` criado."},"dataprevAuthorizationStatus":{"type":"string","enum":["NOT_STARTED","PENDING_SIGNATURE","PENDING_SUBMISSION","AUTHORIZED","EXPIRED"],"description":"Status de autorização Dataprev do employee no momento da resposta\n(enum `DataprevAuthorizationStatus`).\n"}}}}}},"400":{"description":"Dados inválidos, corpo ilegível ou documento inválido.","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":"Originador fora de `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**."}}}}}}}},"404":{"description":"Employee não encontrado para o originador autenticado","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**."}}}}}}}},"413":{"description":"Documento decodificado acima de 10.485.760 bytes.","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**."}}}}}}}},"422":{"description":"`documentNumber` diferente do CPF do employee.","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."}}}}}}}},"429":{"description":"Mais de 75 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","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**."}}}}}}}},"502":{"description":"Falha ao armazenar o documento. Nada é persistido; reenviar.","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**."}}}}}}}}}}}}}
```

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