> 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/employees/criar-employee.md).

# Criar Employee

Cadastra ou atualiza um employee do originador. É **idempotente por CPF** (ver [Comportamento](#comportamento)).

## Request

`POST /api/v1/originator/employees`

Autenticação: `Authorization: Bearer {originatorToken}`. Aceita o header opcional `Idempotency-Key` (ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md)).

### Corpo

| Campo                  | Tipo                              | Obrigatório | Descrição                                                                                                             |
| ---------------------- | --------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `cpf`                  | `string` (11 dígitos)             | Sim         | CPF do trabalhador, apenas dígitos, sem pontuação.                                                                    |
| `name`                 | `string` (max 100)                | Sim         | Nome civil completo, como no documento oficial.                                                                       |
| `birthDate`            | `string` (date)                   | Não         | Data de nascimento (`yyyy-MM-dd`).                                                                                    |
| `motherName`           | `string` (max 100)                | Não         | Nome completo da mãe.                                                                                                 |
| `gender`               | `string` (enum)                   | Não         | Gênero: `MALE`, `FEMALE`, `NOT_INFORMED`.                                                                             |
| `idDocumentType`       | `string` (enum)                   | Não         | Tipo do documento de identificação (ver tabela abaixo).                                                               |
| `idDocumentNumber`     | `string` (max 50)                 | Não         | Número do documento de identificação.                                                                                 |
| `isPoliticallyExposed` | `boolean`                         | Não         | Indica se é Pessoa Politicamente Exposta (PPE/PEP).                                                                   |
| `phone`                | `string` (max 20)                 | Não         | Telefone de contato com DDD.                                                                                          |
| `email`                | `string` (formato email, max 100) | Não         | E-mail do trabalhador.                                                                                                |
| `partnerName`          | `string` (max 100)                | Não         | Nome do cônjuge ou parceiro.                                                                                          |
| `authorization`        | `object`                          | Não         | Dispara a autorização Dataprev no próprio cadastro. Ver [Autorização no cadastro](#autorizacao-no-cadastro-opcional). |

### Tipos de documento (`idDocumentType`)

| Valor                            | Significado            |
| -------------------------------- | ---------------------- |
| `GENERAL_REGISTRY`               | RG                     |
| `DRIVERS_LICENSE`                | CNH                    |
| `ELECTRONIC_DRIVERS_LICENSE`     | CNH-e                  |
| `NATIONAL_ID`                    | DNI                    |
| `WORK_CARD`                      | CTPS                   |
| `PASSPORT`                       | Passaporte             |
| `MILITARY_ID_CARD`               | CIM                    |
| `RESERVIST_CERTIFICATE`          | Certidão de Reservista |
| `MARITIME_CARD`                  | Carteira de Marítimo   |
| `PROFESSIONAL_ID_CARD`           | CIP                    |
| `INDIGENOUS_BIRTH_REGISTRY`      | RANI                   |
| `PROVISIONAL_MIGRATION_REGISTRY` | DPRNM                  |
| `FOREIGNER_REGISTRY`             | RNE/CIE                |

## Comportamento

* CPF novo para o originador: `201`, employee criado.
* CPF já cadastrado e ativo: `200`, mesmo employee (mesmo `publicId`), com os campos enviados atualizados. Campos nulos ou ausentes mantêm o valor atual. Não há outro endpoint de atualização.
* CPF cadastrado e inativo (`status != ACTIVE`): `409` (`errorCode: EMPLOYEE_INACTIVE`).
* Sem `authorization`, o cadastro não inicia a autorização: use depois um dos caminhos de [Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao.md).

## Autorização no cadastro (opcional) <a href="#autorizacao-no-cadastro-opcional" id="autorizacao-no-cadastro-opcional"></a>

Envia o consentimento do trabalhador junto com o cadastro, sem segunda chamada. Requer originador na estratégia `ORIGINATOR_MANAGED`. Envie **no máximo um** dos dois caminhos; os dois juntos dão `400`:

| Caminho                              | O que é                                                                                                                                                                                                                                                                                      |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorization.trail`                | Trilha de opt-in, com os campos de [Criar Trilha de Autorização](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in/criar-trilha-autorizacao.md). Aqui o `documentNumber` é opcional: ausente, vale o CPF do employee; divergente, `422`. |
| `authorization.signedDocumentBase64` | PDF do termo já assinado, em Base64. Precisa ser um PDF; cria o documento assinado e enfileira a autorização.                                                                                                                                                                                |

{% hint style="warning" %}
**Tudo ou nada:** se a autorização falhar (originador não habilitado, CPF divergente, Base64 inválido, conteúdo que não é PDF), o cadastro inteiro é revertido e a resposta é `403`/`422`/`400`. Um `201` com o bloco `authorization` significa cadastro e disparo feitos.
{% endhint %}

Com o disparo feito, a resposta inclui o bloco `authorization`:

| Campo                         | Tipo            | Descrição                                                                                                                                                                       |
| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                      | `string` (enum) | Sempre `PROCESSING`. O termo enviado **sempre** reautoriza, mesmo com autorização válida, e tem custo real na Dataprev: para só garantir o cadastro, **omita** `authorization`. |
| `nsu`                         | `string`        | NSU do documento de autorização gerado nesta chamada.                                                                                                                           |
| `dataprevAuthorizationStatus` | `string` (enum) | Situação da autorização Dataprev: `PENDING_SUBMISSION`, `PENDING_SIGNATURE`, `AUTHORIZED`, `EXPIRED`, `NOT_STARTED`.                                                            |

## Response

| Campo                     | Tipo                 | Descrição                                                                                                                                    |
| ------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`                | `string`             | Identificador público do employee (16 caracteres Base64 URL-safe).                                                                           |
| `cpf`                     | `string`             | CPF do trabalhador cadastrado.                                                                                                               |
| `name`                    | `string`             | Nome civil completo do trabalhador.                                                                                                          |
| `birthDate`               | `string` (date)      | Data de nascimento registrada.                                                                                                               |
| `motherName`              | `string`             | Nome completo da mãe registrado.                                                                                                             |
| `gender`                  | `string` (enum)      | Gênero no cadastro: `MALE`, `FEMALE`, `NOT_INFORMED`.                                                                                        |
| `idDocumentType`          | `string` (enum)      | Tipo do documento de identificação registrado.                                                                                               |
| `idDocumentNumber`        | `string`             | Número do documento de identificação registrado.                                                                                             |
| `isPoliticallyExposed`    | `boolean`            | Indicador de Pessoa Politicamente Exposta.                                                                                                   |
| `phone`                   | `string`             | Telefone de contato registrado.                                                                                                              |
| `email`                   | `string`             | E-mail registrado para contato.                                                                                                              |
| `partnerName`             | `string`             | Nome do cônjuge/parceiro registrado.                                                                                                         |
| `status`                  | `string` (enum)      | Situação cadastral: `ACTIVE`, `INACTIVE`, `REVOKED`.                                                                                         |
| `createdDate`             | `string` (date-time) | Data e hora de criação do cadastro (UTC).                                                                                                    |
| `lastModifiedDate`        | `string` (date-time) | Data e hora da última atualização do cadastro (UTC).                                                                                         |
| `employmentRelationships` | `array`              | Vínculos empregatícios do trabalhador (incluído quando disponível).                                                                          |
| `authorization`           | `object`             | Resultado do disparo. Só presente quando o request trouxe `authorization`. Ver [Autorização no cadastro](#autorizacao-no-cadastro-opcional). |

## Exemplo

```http
POST /api/v1/originator/employees HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "12345678901",
  "name": "João da Silva",
  "birthDate": "1990-05-20",
  "motherName": "Maria da Silva",
  "gender": "MALE",
  "phone": "11987654321",
  "email": "joao.silva@email.com"
}
```

Resposta `201`:

```json
{
  "publicId": "Kj8mP2xQ9nR4sT6v",
  "cpf": "12345678901",
  "name": "João da Silva",
  "birthDate": "1990-05-20",
  "motherName": "Maria da Silva",
  "gender": "MALE",
  "phone": "11987654321",
  "email": "joao.silva@email.com",
  "status": "ACTIVE",
  "createdDate": "2025-01-10T14:30:00Z",
  "lastModifiedDate": "2025-01-10T14:30:00Z"
}
```

### Exemplo com autorização (PDF assinado em Base64)

```http
POST /api/v1/originator/employees HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "52998224725",
  "name": "Alberto Pereira",
  "birthDate": "1985-08-20",
  "gender": "MALE",
  "phone": "11987654321",
  "email": "alberto@email.com",
  "authorization": {
    "signedDocumentBase64": "JVBERi0xLjQK...=="
  }
}
```

Resposta `201`:

```json
{
  "publicId": "Ab3nQ7xR2mT9sV5w",
  "cpf": "52998224725",
  "name": "Alberto Pereira",
  "status": "ACTIVE",
  "createdDate": "2025-01-10T14:31:00Z",
  "lastModifiedDate": "2025-01-10T14:31:00Z",
  "authorization": {
    "status": "PROCESSING",
    "nsu": "140520251000000123",
    "dataprevAuthorizationStatus": "PENDING_SUBMISSION"
  }
}
```

### Exemplo com autorização (trilha de opt-in)

```http
POST /api/v1/originator/employees HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "52998224725",
  "name": "Alberto Pereira",
  "birthDate": "1985-08-20",
  "gender": "MALE",
  "phone": "11987654321",
  "email": "alberto@email.com",
  "authorization": {
    "trail": {
      "name": "Alberto Pereira",
      "email": "alberto@email.com",
      "phone": "+5561999990000",
      "authenticationType": "opt-in",
      "timestamp": "2025-08-04T23:45:30Z",
      "ipAddress": "192.168.0.10",
      "sessionId": "sess-1a2b3c4d5e"
    }
  }
}
```

A resposta tem o mesmo formato do exemplo anterior.

### Exemplo de reenvio (reuso do employee)

Envie `cpf`, `name` e os campos a alterar; os demais são preservados. No exemplo só o contato muda, e `birthDate` e `motherName` voltam preservados. Incluir `authorization` reprocessa o termo: NSU novo e consulta de margem nova na Dataprev.

```http
POST /api/v1/originator/employees HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "cpf": "52998224725",
  "name": "Alberto Pereira",
  "phone": "11955554444",
  "email": "alberto.novo@email.com"
}
```

Resposta `200`:

```json
{
  "publicId": "Ab3nQ7xR2mT9sV5w",
  "cpf": "52998224725",
  "name": "Alberto Pereira",
  "birthDate": "1985-08-20",
  "motherName": "Joana Pereira",
  "phone": "11955554444",
  "email": "alberto.novo@email.com",
  "status": "ACTIVE",
  "createdDate": "2025-01-10T14:31:00Z",
  "lastModifiedDate": "2025-09-01T10:15:00Z"
}
```

## Erros

| Código | `errorCode`                      | Situação                                                                                                                                                                                                                                                                                   |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | —                                | Payload inválido (`properties.errors`): CPF ausente/inválido, `name` fora do tamanho, e-mail inválido, limites da trilha embutida, `signedDocumentBase64` acima do tamanho máximo. `trail` **e** `signedDocumentBase64` juntos aparecem na chave `authorization.atMostOneStrategyProvided` |
| 400    | —                                | JSON malformado, enum ou data inválidos (`type: about:blank`)                                                                                                                                                                                                                              |
| 400    | `SIGNED_DOCUMENT_REQUIRED`       | `authorization.signedDocumentBase64` vazio ou só com espaços                                                                                                                                                                                                                               |
| 400    | `SIGNED_DOCUMENT_INVALID_BASE64` | `signedDocumentBase64` não é Base64 válido                                                                                                                                                                                                                                                 |
| 403    | `ORIGINATOR_OPT_IN_NOT_ENABLED`  | `authorization` enviado por originador fora de `ORIGINATOR_MANAGED` (trilha ou PDF)                                                                                                                                                                                                        |
| 409    | `EMPLOYEE_INACTIVE`              | CPF já cadastrado e desativado                                                                                                                                                                                                                                                             |
| 422    | `CPF_MISMATCH`                   | CPF da trilha diferente do CPF do employee. O cadastro é revertido                                                                                                                                                                                                                         |
| 422    | `SIGNED_DOCUMENT_NOT_PDF`        | `signedDocumentBase64` não é PDF. O cadastro é revertido                                                                                                                                                                                                                                   |
| 423    | `DATAPREV_SUSPENSION_WINDOW`     | Janela de suspensão da Dataprev. Reenvie com chave nova após o `Retry-After`                                                                                                                                                                                                               |
| 429    | —                                | Mais de 100 requisições por segundo                                                                                                                                                                                                                                                        |
| 502    | —                                | Falha ao armazenar o PDF da autorização. O cadastro é revertido; 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).

## Próximo passo

Sem `authorization` no cadastro, inicie a autorização por um dos caminhos:

* [Enviar Termo Assinado (envio direto)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/enviar-termo-assinado-direto.md) — o termo em PDF é seu.
* [Termo Gerado pela Giro](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-pdf/termo-gerado-pela-giro.md) — `POST /api/v1/originator/employees/{publicId}/authorization-documents`, depois download, assinatura e upload.
* [Termo em Trilha Opt-In](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/autorizacao/termo-em-trilha-opt-in.md) — sem PDF.

## Criar ou reusar Employee (idempotente por CPF)

> Cria ou reaproveita o cadastro de um trabalhador (employee) vinculado ao originator autenticado.\
> Os dados enviados são usados nas validações de elegibilidade, simulação, proposta e formalização.\
> \
> \*\*Idempotente por CPF.\*\* O mesmo endpoint pode ser chamado repetidamente com o mesmo CPF:\
> \- \*\*CPF novo\*\* → cria o employee e retorna \`201\`.\
> \- \*\*CPF já existente e ativo\*\* → \*\*reusa\*\* o mesmo employee (mesmo \`publicId\`) e retorna \`200\`.\
> \- \*\*CPF existente inativo\*\* (\`status != ACTIVE\`) → \`409\` (\`EMPLOYEE\_INACTIVE\`); reative antes de prosseguir.\
> \
> \*\*Atualização parcial no reuso.\*\* Os campos enviados atualizam o cadastro; campos \*\*nulos ou ausentes\
> mantêm o valor atual\*\* no banco (ex.: omitir \`motherName\` preserva o já cadastrado). \`cpf\` e \`name\`\
> permanecem obrigatórios em toda chamada (validação de entrada). Para uma substituição completa e\
> determinística de todos os campos, use o \`PUT /{publicId}\`.\
> \
> \*\*Termo de autorização (\`authorization\`) é opcional e, quando presente, sempre reprocessa.\*\* Cada envio\
> gera um novo NSU — mesmo que já exista um termo válido vigente — e dispara uma \*\*consulta de margem nova\*\*. Isso tem \*\*custo real na Dataprev\*\* a cada chamada. Para apenas garantir/atualizar o\
> cadastro sem reautorizar, \*\*omita\*\* o objeto \`authorization\`.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Employees","description":"Gerenciamento de employees (trabalhadores)"}],"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":{"post":{"summary":"Criar ou reusar Employee (idempotente por CPF)","description":"Cria ou reaproveita o cadastro de um trabalhador (employee) vinculado ao originator autenticado.\nOs dados enviados são usados nas validações de elegibilidade, simulação, proposta e formalização.\n\n**Idempotente por CPF.** O mesmo endpoint pode ser chamado repetidamente com o mesmo CPF:\n- **CPF novo** → cria o employee e retorna `201`.\n- **CPF já existente e ativo** → **reusa** o mesmo employee (mesmo `publicId`) e retorna `200`.\n- **CPF existente inativo** (`status != ACTIVE`) → `409` (`EMPLOYEE_INACTIVE`); reative antes de prosseguir.\n\n**Atualização parcial no reuso.** Os campos enviados atualizam o cadastro; campos **nulos ou ausentes\nmantêm o valor atual** no banco (ex.: omitir `motherName` preserva o já cadastrado). `cpf` e `name`\npermanecem obrigatórios em toda chamada (validação de entrada). Para uma substituição completa e\ndeterminística de todos os campos, use o `PUT /{publicId}`.\n\n**Termo de autorização (`authorization`) é opcional e, quando presente, sempre reprocessa.** Cada envio\ngera um novo NSU — mesmo que já exista um termo válido vigente — e dispara uma **consulta de margem nova**. Isso tem **custo real na Dataprev** a cada chamada. Para apenas garantir/atualizar o\ncadastro sem reautorizar, **omita** o objeto `authorization`.\n","tags":["Employees"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Chave de idempotência para evitar duplicação em retentativas.\nSe fornecida, o servidor retornará a mesma resposta para chamadas\ncom a mesma chave do mesmo originador.\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"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf","name"],"properties":{"cpf":{"type":"string","pattern":"^\\d{11}$","minLength":11,"maxLength":11,"description":"CPF do trabalhador contendo 11 dígitos numéricos, sem pontos ou traços."},"name":{"type":"string","maxLength":100,"description":"Nome civil completo do trabalhador conforme documento oficial."},"birthDate":{"type":"string","format":"date","description":"Data de nascimento no formato ISO (yyyy-MM-dd)."},"motherName":{"type":"string","maxLength":100,"description":"Nome completo da mãe, utilizado para validação cadastral."},"gender":{"type":"string","enum":["MALE","FEMALE","NOT_INFORMED"],"description":"Gênero declarado pelo trabalhador. A consulta de vínculo na Dataprev sobrescreve este valor com o\nsexo que ela devolver (masculino/feminino); \"não informado\" pela Dataprev não altera o valor atual.\n| Valor | Significado |\n|-------|-------------|\n| MALE | Masculino |\n| FEMALE | Feminino |\n| NOT_INFORMED | Não informado |\n"},"idDocumentType":{"type":"string","enum":["MARITIME_CARD","RESERVIST_CERTIFICATE","DRIVERS_LICENSE","WORK_CARD","PASSPORT","GENERAL_REGISTRY","PROFESSIONAL_ID_CARD","INDIGENOUS_BIRTH_REGISTRY","ELECTRONIC_DRIVERS_LICENSE","NATIONAL_ID","PROVISIONAL_MIGRATION_REGISTRY","MILITARY_ID_CARD","FOREIGNER_REGISTRY"],"description":"Tipo do documento de identificação (código retornado pela API).\n| Valor | Significado |\n|-------|-------------|\n| MARITIME_CARD | Carteira de Marítimo |\n| RESERVIST_CERTIFICATE | Certidão de Reservista |\n| DRIVERS_LICENSE | CNH |\n| WORK_CARD | CTPS |\n| PASSPORT | Passaporte |\n| GENERAL_REGISTRY | RG |\n| PROFESSIONAL_ID_CARD | CIP |\n| INDIGENOUS_BIRTH_REGISTRY | RANI |\n| ELECTRONIC_DRIVERS_LICENSE | CNH-e |\n| NATIONAL_ID | DNI |\n| PROVISIONAL_MIGRATION_REGISTRY | DPRNM |\n| MILITARY_ID_CARD | CIM |\n| FOREIGNER_REGISTRY | RNE/CIE |\n"},"idDocumentNumber":{"type":"string","maxLength":50,"description":"Número do documento de identificação correspondente ao `idDocumentType`."},"isPoliticallyExposed":{"type":"boolean","description":"Indica se o trabalhador é Pessoa Politicamente Exposta (PPE/PEP)."},"phone":{"type":"string","maxLength":20,"description":"Telefone de contato do trabalhador, preferencialmente com DDD."},"email":{"type":"string","format":"email","maxLength":100,"description":"E-mail válido para comunicações operacionais e notificações."},"partnerName":{"type":"string","maxLength":100,"description":"Nome do cônjuge ou parceiro, quando aplicável."},"authorization":{"type":"object","description":"Autorização opcional enviada junto ao cadastro. Dispara o fluxo de autorização Dataprev de forma\n**atômica** com o cadastro: se a autorização falhar, todo o cadastro é revertido (nenhum employee é\ncriado) e a resposta é um erro. O objeto `authorization` é opcional; um objeto vazio (sem `trail`\nnem `signedDocumentBase64`) não dispara nada. Deve conter **no máximo um** dos caminhos\n(`trail` **ou** `signedDocumentBase64`) — enviar ambos resulta em `400`.\n\n- `trail`: valem os campos obrigatórios de `CreateAuthorizationOptInTrailRequest`. O\n  `documentNumber` é **opcional**: quando ausente, é auto-preenchido com o CPF do employee; quando\n  informado e divergente do CPF, a requisição falha com `422` (e o cadastro é revertido), sem\n  sobrescrever a evidência.\n- `signedDocumentBase64`: PDF do termo já assinado. É decodificado, validado (precisa ser um PDF)\n  e armazenado; um documento SIGNED é criado e a autorização é enfileirada. Base64 inválido → `400`,\n  conteúdo que não é PDF → `422` — e, por ser atômico, o cadastro é revertido nesses casos.\n","properties":{"trail":{"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."}}}}}}}}],"description":"Trilha de opt-in (lastro forense) que comprova o aceite do trabalhador. Reaproveita o\npipeline de `POST /employees/{publicId}/authorization-trails`.\n"},"signedDocumentBase64":{"type":"string","format":"byte","description":"PDF do termo de autorização já assinado, codificado em Base64 (estratégia ORIGINATOR_MANAGED).\nMutuamente exclusivo com `trail`.\n"}},"not":{"type":"object","required":["trail","signedDocumentBase64"]}}}}}}},"responses":{"200":{"description":"Employee **já existente** para o originator (mesmo CPF) — **reusado** (mesmo `publicId` do cadastro\noriginal). Os campos enviados atualizam parcialmente o cadastro: campos nulos ou ausentes mantêm o\nvalor atual (a substituição completa continua sendo o `PUT /{publicId}`). Quando o request trouxe\n`authorization`, o termo é reprocessado (novo NSU + margem nova) e o bloco `authorization` vem\nno corpo, igual ao `201`.\n","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","description":"Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v"},"cpf":{"type":"string","description":"CPF do trabalhador cadastrado."},"name":{"type":"string","description":"Nome civil completo do trabalhador."},"birthDate":{"type":"string","format":"date","description":"Data de nascimento registrada."},"motherName":{"type":"string","description":"Nome completo da mãe registrado."},"gender":{"type":"string","enum":["MALE","FEMALE","NOT_INFORMED"],"description":"Gênero no cadastro — o sexo devolvido pela Dataprev na consulta de vínculo, ou o último informado\npelo originador.\n| Valor | Significado |\n|-------|-------------|\n| MALE | Masculino |\n| FEMALE | Feminino |\n| NOT_INFORMED | Não informado |\n"},"idDocumentType":{"type":"string","enum":["MARITIME_CARD","RESERVIST_CERTIFICATE","DRIVERS_LICENSE","WORK_CARD","PASSPORT","GENERAL_REGISTRY","PROFESSIONAL_ID_CARD","INDIGENOUS_BIRTH_REGISTRY","ELECTRONIC_DRIVERS_LICENSE","NATIONAL_ID","PROVISIONAL_MIGRATION_REGISTRY","MILITARY_ID_CARD","FOREIGNER_REGISTRY"],"description":"Mesmos valores de CreateEmployeeRequest.idDocumentType (ver tabela)."},"idDocumentNumber":{"type":"string","description":"Número do documento de identificação registrado."},"isPoliticallyExposed":{"type":"boolean","description":"Indicador de Pessoa Politicamente Exposta no cadastro do trabalhador."},"phone":{"type":"string","description":"Telefone de contato registrado."},"email":{"type":"string","description":"E-mail registrado para contato."},"partnerName":{"type":"string","description":"Nome do cônjuge/parceiro registrado."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","REVOKED"],"description":"Situação cadastral do trabalhador.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Cadastro ativo, pode operar |\n| INACTIVE | Cadastro inativo (ex.: desligado) |\n| REVOKED | Acesso revogado pelo originator |\n"},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do cadastro no sistema (UTC)."},"lastModifiedDate":{"type":"string","format":"date-time","description":"Data e hora da última atualização do cadastro (UTC)."},"employmentRelationships":{"type":"array","description":"Vínculos empregatícios do trabalhador (incluído quando disponível).","items":{"type":"object","properties":{"publicId":{"type":"string","format":"uuid","description":"Identificador público opaco do vínculo empregatício."},"registrationNumber":{"type":"string","description":"Matrícula do trabalhador no empregador."},"employerTaxId":{"type":"string","description":"CNPJ ou CPF do empregador."},"employerTaxIdType":{"type":"string","description":"Tipo do documento fiscal do empregador.\n| Valor | Significado |\n|-------|-------------|\n| CPF | Pessoa física |\n| CNPJ | Pessoa jurídica |\n"},"employerName":{"type":"string","description":"Razão social ou nome do empregador."},"workerName":{"type":"string","maxLength":200,"nullable":true,"description":"Nome do trabalhador conforme retornado pela Dataprev na consulta de vínculo.\nÉ a fonte de verdade para a averbação. Pode ser `null` em vínculos legados\ncujo dado da Dataprev ainda não foi atualizado.\n"},"birthDate":{"type":"string","format":"date","nullable":true,"description":"Data de nascimento do trabalhador (employee). Preenchida a partir do cadastro\nlocal, preenchida pela consulta à Dataprev.\nPode ser `null` se ainda não disponível.\n"},"admissionDate":{"type":"string","format":"date","description":"Data de admissão do trabalhador."},"terminationDate":{"type":"string","format":"date","description":"Data de desligamento (nulo se vínculo ativo)."},"terminationReason":{"type":"string","description":"Motivo do desligamento (nulo se vínculo ativo)."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED","TERMINATED"],"description":"Situação do vínculo empregatício.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Vínculo ativo |\n| INACTIVE | Vínculo inativo |\n| SUSPENDED | Vínculo suspenso |\n| TERMINATED | Vínculo encerrado |\n"},"workerCategory":{"type":"string","description":"Categoria do trabalhador conforme eSocial."},"workerCboCode":{"type":"string","description":"Código CBO da ocupação do trabalhador."},"workerCboDescription":{"type":"string","description":"Descrição da ocupação (CBO)."},"totalEarnings":{"type":"number","format":"decimal","description":"Remuneração total do trabalhador."},"marginBase":{"type":"number","format":"decimal","description":"Base de cálculo da margem consignável."},"availableMargin":{"type":"number","format":"decimal","description":"Margem consignável disponível."},"usableMargin":{"type":"number","format":"decimal","description":"Margem utilizável para novas consignações."},"isEligible":{"type":"boolean","description":"Indica se o vínculo é elegível para consignação."},"ineligibilityReason":{"type":"string","description":"Motivo da inelegibilidade (nulo se elegível)."},"dataprevExpiresAt":{"type":"string","format":"date-time","description":"Validade da margem retornada. Após esse instante os dados de margem estão vencidos e\numa nova consulta de margem deve ser disparada para revalidar.\n"},"employerCnae":{"type":"string","description":"Código CNAE do empregador."},"employerCnaeDescription":{"type":"string","description":"Descrição da atividade econômica (CNAE)."},"employerActivityStartDate":{"type":"string","format":"date","description":"Data de início da atividade do empregador."},"activeConsignmentsCount":{"type":"integer","description":"Quantidade de consignações ativas no vínculo."},"nationalityCode":{"type":"integer","description":"Código da nacionalidade do trabalhador."},"nationalityDescription":{"type":"string","description":"Descrição da nacionalidade."},"blockingTypeCode":{"type":"integer","description":"Código do tipo de bloqueio (se houver)."},"blockingTypeDescription":{"type":"string","description":"Descrição do tipo de bloqueio."},"politicallyExposedPerson":{"type":"string","description":"Indicador de pessoa politicamente exposta."}}}},"authorization":{"type":"object","description":"Resultado do disparo automático de autorização feito durante o cadastro. Presente **apenas**\nquando o request trouxe o objeto `authorization` e o cadastro foi bem-sucedido (o disparo é atômico\ncom a criação; uma falha reverte tudo e retorna erro, então este bloco só aparece em caso de\nsucesso).\n","properties":{"status":{"type":"string","enum":["PROCESSING"],"description":"Sempre `PROCESSING` (reusa `SendAuthorizationStatus`). O termo embutido **sempre**\nreautoriza, mesmo com autorização válida vigente.\n"},"nsu":{"type":"string","description":"NSU do `AuthorizationDocument` gerado."},"dataprevAuthorizationStatus":{"type":"string","enum":["NOT_STARTED","PENDING_SIGNATURE","PENDING_SUBMISSION","AUTHORIZED","EXPIRED"],"description":"Situação da autorização Dataprev associada (enum `DataprevAuthorizationStatus`)."}}}}}}}},"201":{"description":"Employee **criado** com sucesso (CPF novo para o originator). Idempotente por CPF: CPF já\nexistente retorna `200` (reuso), não `201`. Quando o request trouxe `authorization`, o corpo\ninclui o bloco `authorization` com o resultado do disparo. O disparo é **atômico**: se a\nautorização falhar, nada é criado e a resposta é um erro (`403`/`422`/`400`), não `201`.\n\nEnviar `authorization` **sempre** reprocessa o termo (novo NSU, mesmo que já exista um termo\nválido) e dispara uma **consulta de margem nova** — isso tem custo real na\nDataprev. Quem quer apenas garantir o cadastro deve **omitir** o objeto `authorization`.\n","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","description":"Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v"},"cpf":{"type":"string","description":"CPF do trabalhador cadastrado."},"name":{"type":"string","description":"Nome civil completo do trabalhador."},"birthDate":{"type":"string","format":"date","description":"Data de nascimento registrada."},"motherName":{"type":"string","description":"Nome completo da mãe registrado."},"gender":{"type":"string","enum":["MALE","FEMALE","NOT_INFORMED"],"description":"Gênero no cadastro — o sexo devolvido pela Dataprev na consulta de vínculo, ou o último informado\npelo originador.\n| Valor | Significado |\n|-------|-------------|\n| MALE | Masculino |\n| FEMALE | Feminino |\n| NOT_INFORMED | Não informado |\n"},"idDocumentType":{"type":"string","enum":["MARITIME_CARD","RESERVIST_CERTIFICATE","DRIVERS_LICENSE","WORK_CARD","PASSPORT","GENERAL_REGISTRY","PROFESSIONAL_ID_CARD","INDIGENOUS_BIRTH_REGISTRY","ELECTRONIC_DRIVERS_LICENSE","NATIONAL_ID","PROVISIONAL_MIGRATION_REGISTRY","MILITARY_ID_CARD","FOREIGNER_REGISTRY"],"description":"Mesmos valores de CreateEmployeeRequest.idDocumentType (ver tabela)."},"idDocumentNumber":{"type":"string","description":"Número do documento de identificação registrado."},"isPoliticallyExposed":{"type":"boolean","description":"Indicador de Pessoa Politicamente Exposta no cadastro do trabalhador."},"phone":{"type":"string","description":"Telefone de contato registrado."},"email":{"type":"string","description":"E-mail registrado para contato."},"partnerName":{"type":"string","description":"Nome do cônjuge/parceiro registrado."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","REVOKED"],"description":"Situação cadastral do trabalhador.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Cadastro ativo, pode operar |\n| INACTIVE | Cadastro inativo (ex.: desligado) |\n| REVOKED | Acesso revogado pelo originator |\n"},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do cadastro no sistema (UTC)."},"lastModifiedDate":{"type":"string","format":"date-time","description":"Data e hora da última atualização do cadastro (UTC)."},"employmentRelationships":{"type":"array","description":"Vínculos empregatícios do trabalhador (incluído quando disponível).","items":{"type":"object","properties":{"publicId":{"type":"string","format":"uuid","description":"Identificador público opaco do vínculo empregatício."},"registrationNumber":{"type":"string","description":"Matrícula do trabalhador no empregador."},"employerTaxId":{"type":"string","description":"CNPJ ou CPF do empregador."},"employerTaxIdType":{"type":"string","description":"Tipo do documento fiscal do empregador.\n| Valor | Significado |\n|-------|-------------|\n| CPF | Pessoa física |\n| CNPJ | Pessoa jurídica |\n"},"employerName":{"type":"string","description":"Razão social ou nome do empregador."},"workerName":{"type":"string","maxLength":200,"nullable":true,"description":"Nome do trabalhador conforme retornado pela Dataprev na consulta de vínculo.\nÉ a fonte de verdade para a averbação. Pode ser `null` em vínculos legados\ncujo dado da Dataprev ainda não foi atualizado.\n"},"birthDate":{"type":"string","format":"date","nullable":true,"description":"Data de nascimento do trabalhador (employee). Preenchida a partir do cadastro\nlocal, preenchida pela consulta à Dataprev.\nPode ser `null` se ainda não disponível.\n"},"admissionDate":{"type":"string","format":"date","description":"Data de admissão do trabalhador."},"terminationDate":{"type":"string","format":"date","description":"Data de desligamento (nulo se vínculo ativo)."},"terminationReason":{"type":"string","description":"Motivo do desligamento (nulo se vínculo ativo)."},"status":{"type":"string","enum":["ACTIVE","INACTIVE","SUSPENDED","TERMINATED"],"description":"Situação do vínculo empregatício.\n| Valor | Significado |\n|-------|-------------|\n| ACTIVE | Vínculo ativo |\n| INACTIVE | Vínculo inativo |\n| SUSPENDED | Vínculo suspenso |\n| TERMINATED | Vínculo encerrado |\n"},"workerCategory":{"type":"string","description":"Categoria do trabalhador conforme eSocial."},"workerCboCode":{"type":"string","description":"Código CBO da ocupação do trabalhador."},"workerCboDescription":{"type":"string","description":"Descrição da ocupação (CBO)."},"totalEarnings":{"type":"number","format":"decimal","description":"Remuneração total do trabalhador."},"marginBase":{"type":"number","format":"decimal","description":"Base de cálculo da margem consignável."},"availableMargin":{"type":"number","format":"decimal","description":"Margem consignável disponível."},"usableMargin":{"type":"number","format":"decimal","description":"Margem utilizável para novas consignações."},"isEligible":{"type":"boolean","description":"Indica se o vínculo é elegível para consignação."},"ineligibilityReason":{"type":"string","description":"Motivo da inelegibilidade (nulo se elegível)."},"dataprevExpiresAt":{"type":"string","format":"date-time","description":"Validade da margem retornada. Após esse instante os dados de margem estão vencidos e\numa nova consulta de margem deve ser disparada para revalidar.\n"},"employerCnae":{"type":"string","description":"Código CNAE do empregador."},"employerCnaeDescription":{"type":"string","description":"Descrição da atividade econômica (CNAE)."},"employerActivityStartDate":{"type":"string","format":"date","description":"Data de início da atividade do empregador."},"activeConsignmentsCount":{"type":"integer","description":"Quantidade de consignações ativas no vínculo."},"nationalityCode":{"type":"integer","description":"Código da nacionalidade do trabalhador."},"nationalityDescription":{"type":"string","description":"Descrição da nacionalidade."},"blockingTypeCode":{"type":"integer","description":"Código do tipo de bloqueio (se houver)."},"blockingTypeDescription":{"type":"string","description":"Descrição do tipo de bloqueio."},"politicallyExposedPerson":{"type":"string","description":"Indicador de pessoa politicamente exposta."}}}},"authorization":{"type":"object","description":"Resultado do disparo automático de autorização feito durante o cadastro. Presente **apenas**\nquando o request trouxe o objeto `authorization` e o cadastro foi bem-sucedido (o disparo é atômico\ncom a criação; uma falha reverte tudo e retorna erro, então este bloco só aparece em caso de\nsucesso).\n","properties":{"status":{"type":"string","enum":["PROCESSING"],"description":"Sempre `PROCESSING` (reusa `SendAuthorizationStatus`). O termo embutido **sempre**\nreautoriza, mesmo com autorização válida vigente.\n"},"nsu":{"type":"string","description":"NSU do `AuthorizationDocument` gerado."},"dataprevAuthorizationStatus":{"type":"string","enum":["NOT_STARTED","PENDING_SIGNATURE","PENDING_SUBMISSION","AUTHORIZED","EXPIRED"],"description":"Situação da autorização Dataprev associada (enum `DataprevAuthorizationStatus`)."}}}}}}}},"400":{"description":"Dados inválidos, corpo ilegível ou documento de autorização 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` enviou `authorization` (trilha ou PDF).","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":"Originator não encontrado (token válido mas originator inexistente no sistema)","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":"Employee do CPF está inativo, ou mesma `Idempotency-Key` ainda em processamento.","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":"Autorização inválida. O cadastro é revertido — nenhum employee é criado.","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 100 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 PDF da autorização. O cadastro é revertido; 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**."}}}}}}}}}}}}}
```

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