> 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-trilha-opt-in/criar-trilha-autorizacao.md).

# Criar Trilha de Autorização

Recebe a trilha de aceite opt-in coletada no seu canal digital e dispara a autorização Dataprev, sem PDF. A Dataprev recebe só canal (**Web Correspondente**), data/hora, NSU e CPF; o lastro (IP, fingerprint, sessão, geolocalização, timeline) fica custodiado pela Giro, amarrado ao NSU.

* O originador precisa estar habilitado na estratégia `ORIGINATOR_MANAGED`; sem isso, `403`.
* A escolha é por trabalhador: para outros empregados, o mesmo originador pode usar o [Termo em PDF](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf.md).
* O originador atesta que coletou o aceite e responde pela robustez da trilha; a Giro custodia o lastro como evidência imutável. Ver [Trilha de Auditoria](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/trilha-de-auditoria.md).

## Request

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

| 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                                                                                                |
| -------------------- | --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| `name`               | `string` (max 200)                | Sim            | Nome do trabalhador que aceitou.                                                                         |
| `email`              | `string` (formato email, max 150) | Não            | E-mail do trabalhador.                                                                                   |
| `phone`              | `string` (max 20)                 | Não            | Telefone do trabalhador.                                                                                 |
| `documentNumber`     | `string`                          | Sim            | CPF do trabalhador. Precisa ser o CPF do employee, senão `422`.                                          |
| `authenticationType` | `string`                          | Sim            | Único valor aceito: `"opt-in"`.                                                                          |
| `timestamp`          | `string` (date-time)              | Sim            | Instante do aceite, ISO-8601 UTC (`yyyy-MM-dd'T'HH:mm:ss'Z'`).                                           |
| `ipAddress`          | `string`                          | Sim            | IP de origem do aceite (IPv4 ou IPv6).                                                                   |
| `sessionId`          | `string` (10–50)                  | Sim            | Identificador da sessão do aceite.                                                                       |
| `fingerprint`        | `object`                          | Não (nullable) | Dados do device no aceite. Subcampos opcionais.                                                          |
| `events`             | `array`                           | Não (nullable) | Timeline de auditoria em texto livre (ver abaixo). Normalmente ausente: o snapshot já registra o aceite. |

#### Objeto `fingerprint`

| Campo            | Tipo               | Obrigatório | Descrição                                        |
| ---------------- | ------------------ | ----------- | ------------------------------------------------ |
| `fingerprintId`  | `string` (max 64)  | Não         | Identificador do device gerado no navegador/app. |
| `lat`            | `number`           | Não         | Latitude.                                        |
| `lng`            | `number`           | Não         | Longitude.                                       |
| `name`           | `string` (max 200) | Não         | Nome associado ao device.                        |
| `device`         | `string` (max 50)  | Não         | Tipo de device (ex.: `Web`, `Android`, `iOS`).   |
| `browser`        | `string` (max 512) | Não         | User-agent / navegador.                          |
| `browserVersion` | `string` (max 50)  | Não         | Versão do navegador.                             |

#### Campo opcional `events[]`

Timeline em texto livre (apresentou termo, enviou mensagem, leu, aceitou...), guardada literalmente como lastro. Não há enum; há um [vocabulário recomendado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/trilha-de-auditoria.md#vocabulario-recomendado-de-eventos-de-auditoria).

| Campo         | Tipo                    | Obrigatório             | Descrição                           |
| ------------- | ----------------------- | ----------------------- | ----------------------------------- |
| `occurredAt`  | `string` (date-time)    | Sim (se o item existir) | Instante do evento, ISO-8601 UTC.   |
| `description` | `string` (max 500)      | Sim (se o item existir) | Descrição do evento.                |
| `ipAddress`   | `string`                | Não                     | IP de origem do evento (IPv4/IPv6). |
| `geo`         | `object` `{ lat, lng }` | Não                     | Geolocalização do evento.           |

## Response (202)

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

Ao fim do processamento chega o webhook `AUTHORIZATION_COMPLETED`, seguido de um `MARGIN_QUERY_COMPLETED` por vínculo (a consulta de margem é automática).

{% hint style="warning" %}
**Enviar trilha 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).
{% endhint %}

## Exemplo

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

{
  "name": "MARIA DA SILVA",
  "email": "maria@example.com",
  "phone": "+5561999990000",
  "documentNumber": "52998224725",
  "authenticationType": "opt-in",
  "timestamp": "2025-08-04T23:45:30Z",
  "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "sessionId": "sess-1a2b3c4d5e",
  "fingerprint": {
    "fingerprintId": "4c188fc4-2cb4-48cc-9236-7df953570638",
    "lat": -15.82891,
    "lng": -48.12751,
    "name": "MARIA DA SILVA",
    "device": "Web",
    "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0 Safari/537.36",
    "browserVersion": "120.0.0.0"
  },
  "events": [
    {
      "occurredAt": "2025-08-04T23:45:30Z",
      "description": "Aceite realizado — token via WhatsApp (+55 11 99999-9999)",
      "ipAddress": "2001:0db8:85a3::8a2e:0370:7334",
      "geo": { "lat": -15.82891, "lng": -48.12751 }
    }
  ]
}
```

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     | —                               | Payload inválido (`properties.errors`): campo obrigatório ausente/inválido, IP inválido, `sessionId` fora de 10–50, `authenticationType` ≠ `opt-in`, mais de 100 `events`, CPF malformado. Campos de evento aparecem indexados (`events[0].occurredAt`) |
| 400     | —                               | JSON malformado ou data inválida (`type: about:blank`)                                                                                                                                                                                                  |
| 403     | `ORIGINATOR_OPT_IN_NOT_ENABLED` | Originador fora de `ORIGINATOR_MANAGED`. Checado antes do employee                                                                                                                                                                                      |
| 404     | —                               | Employee não encontrado ou de outro originador                                                                                                                                                                                                          |
| 422     | `CPF_MISMATCH`                  | `documentNumber` diferente do CPF do employee                                                                                                                                                                                                           |
| 429     | —                               | Mais de 75 requisições por segundo                                                                                                                                                                                                                      |
| webhook | `DATAPREV_SUSPENSION_WINDOW`    | Este endpoint não é bloqueado pela janela de suspensão: responde `202`, e a falha chega por `AUTHORIZATION_FAILED`                                                                                                                                      |

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 trilha de autorização (opt-in)

> Endpoint \*\*B2B\*\* alternativo ao termo de autorização gerado/assinado pela Giro.\
> Em vez de a Giro gerar e o trabalhador assinar um PDF, o \*\*originador envia a\
> trilha de opt-in\*\* que comprova o aceite do trabalhador (snapshot forense:\
> \`timestamp\`, \`ipAddress\`, \`sessionId\`, \`fingerprint\` e, opcionalmente, uma\
> timeline de \`events\[]\` em texto livre).\
> \
> O sistema persiste a trilha como evidência, cria um \`AuthorizationDocument\`\
> no estado \`SIGNED\` (origem \`ORIGINATOR\_OPT\_IN\`) e dispara a autorização\
> Dataprev pelo caminho digital (canal \`WEB\_CORRESPONDENTE\`), reaproveitando o\
> pipeline de envio assíncrono existente.\
> \
> \*\*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\`).\
> \
> \*\*Sempre reautoriza:\*\* mesmo que o empregado já possua autorização Dataprev válida,\
> a trilha 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\`).\
> \
> \*\*Timeline opcional (\`events\[]\`):\*\* quando presente, é texto livre e fica guardada\
> literal junto da trilha (sem enum). Quando ausente — o caso\
> comum — o snapshot já é o registro do aceite.<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-trails":{"post":{"summary":"Enviar trilha de autorização (opt-in)","description":"Endpoint **B2B** alternativo ao termo de autorização gerado/assinado pela Giro.\nEm vez de a Giro gerar e o trabalhador assinar um PDF, o **originador envia a\ntrilha de opt-in** que comprova o aceite do trabalhador (snapshot forense:\n`timestamp`, `ipAddress`, `sessionId`, `fingerprint` e, opcionalmente, uma\ntimeline de `events[]` em texto livre).\n\nO sistema persiste a trilha como evidência, cria um `AuthorizationDocument`\nno estado `SIGNED` (origem `ORIGINATOR_OPT_IN`) e dispara a autorização\nDataprev pelo caminho digital (canal `WEB_CORRESPONDENTE`), reaproveitando o\npipeline de envio assíncrono existente.\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\n**Sempre reautoriza:** mesmo que o empregado já possua autorização Dataprev válida,\na trilha 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\n**Timeline opcional (`events[]`):** quando presente, é texto livre e fica guardada\nliteral junto da trilha (sem enum). Quando ausente — o caso\ncomum — o snapshot já é o registro do aceite.\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":{"description":"Variante da trilha usada pelo endpoint **avulso** `POST /employees/{publicId}/authorization-trails`,\nonde `documentNumber` é **obrigatório**. Reaproveita `CreateAuthorizationOptInTrailRequest` e apenas\nadiciona a exigência do `documentNumber` (no cadastro de employee o campo é opcional).\n","allOf":[{"type":"object","description":"Trilha de opt-in enviada pelo originador para comprovar\no aceite do trabalhador. O snapshot (`timestamp`/`ipAddress`/`sessionId`/`fingerprint`) já é\no registro forense do aceite; a timeline `events[]` é opcional e fica guardada literal.\n","required":["name","authenticationType","timestamp","ipAddress","sessionId"],"properties":{"name":{"type":"string","maxLength":200,"description":"Nome do trabalhador que realizou o aceite."},"email":{"type":"string","format":"email","maxLength":150,"description":"E-mail do trabalhador (opcional)."},"phone":{"type":"string","maxLength":20,"description":"Telefone do trabalhador (opcional)."},"documentNumber":{"type":"string","description":"CPF do trabalhador (somente dígitos). Deve casar com o CPF do empregado, senão 422.\n**Obrigatório** no endpoint avulso `POST /employees/{publicId}/authorization-trails`.\nNo cadastro de employee (`authorization.trail`) é **opcional**: quando ausente, é\nauto-preenchido com o CPF do employee; quando informado e divergente, a requisição falha com\n`422` e o cadastro é revertido (atômico), sem sobrescrever a evidência.\n"},"authenticationType":{"type":"string","pattern":"^opt-in$","description":"Tipo de autenticação. Único valor aceito é `opt-in`."},"timestamp":{"type":"string","format":"date-time","description":"Momento do aceite (ISO-8601 UTC)."},"ipAddress":{"type":"string","maxLength":45,"description":"IP (IPv4 ou IPv6) de onde o aceite foi realizado."},"sessionId":{"type":"string","minLength":10,"maxLength":50,"description":"Identificador da sessão em que o aceite ocorreu."},"fingerprint":{"type":"object","description":"Impressão digital do dispositivo/sessão no momento do aceite. Todos os subcampos são opcionais.\n","properties":{"fingerprintId":{"type":"string","maxLength":64,"description":"Identificador único do fingerprint."},"lat":{"type":"number","description":"Latitude da geolocalização."},"lng":{"type":"number","description":"Longitude da geolocalização."},"name":{"type":"string","maxLength":200,"description":"Nome associado ao fingerprint."},"device":{"type":"string","maxLength":50,"description":"Dispositivo (ex.: Web, Mobile)."},"browser":{"type":"string","maxLength":512,"description":"User-agent / navegador."},"browserVersion":{"type":"string","maxLength":50,"description":"Versão do navegador."}}},"events":{"type":"array","nullable":true,"maxItems":100,"description":"Timeline de auditoria opcional (texto livre). Ausente é o caso comum — o snapshot\njá é o registro do aceite. Quando presente, é guardada literal junto da trilha.\n","items":{"type":"object","description":"Item da timeline de auditoria opcional (texto livre). Quando o item está presente,\n`occurredAt` e `description` são obrigatórios.\n","required":["occurredAt","description"],"properties":{"occurredAt":{"type":"string","format":"date-time","description":"Momento do evento (ISO-8601 UTC)."},"description":{"type":"string","maxLength":500,"description":"Descrição do evento em texto livre."},"ipAddress":{"type":"string","maxLength":45,"description":"IP (IPv4 ou IPv6) associado ao evento (opcional)."},"geo":{"type":"object","description":"Ponto de geolocalização. Ambos os subcampos são opcionais.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}}}}},{"type":"object","required":["documentNumber"]}]}}}},"responses":{"202":{"description":"Trilha aceita; autorização Dataprev enfileirada. Replays de `Idempotency-Key`\nretornam esta mesma resposta com `Idempotency-Replayed: true`.\n","content":{"application/json":{"schema":{"type":"object","description":"Resposta do envio da trilha de opt-in.","properties":{"status":{"type":"string","enum":["PROCESSING"],"description":"Sempre `PROCESSING` (reusa `SendAuthorizationStatus`). O envio da trilha **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":"Trilha inválida ou corpo ilegível.","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`. Checado antes 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**."}}}}}}}},"404":{"description":"Employee inexistente ou não pertencente ao 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":"`Idempotency-Key` em processamento concorrente.","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**."}}}}}}}},"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**."}}}}}}}}}}}}}
```
