> 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/cadastrar-vinculo.md).

# Cadastrar Vínculo Empregatício

Cadastra um vínculo empregatício com a margem que você obteve **em outro provedor**, sem consumir consulta de margem da plataforma. O `publicId` devolvido vai em `employmentRelationshipPublicId` na [proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md), e é este vínculo que é averbado na Dataprev.

{% hint style="warning" %}
Substitui a **consulta de margem**, não a **autorização**. O trabalhador continua precisando autorizar a Giro na Dataprev: autorização dada a outro provedor não vale aqui. Sem ela, não há averbação.
{% endhint %}

## Request

`POST /api/v1/originator/employees/{publicId}/employment-relationships`

Autenticação: `Authorization: Bearer {originatorToken}`.

### Path

| Parâmetro  | Tipo     | Descrição                                          |
| ---------- | -------- | -------------------------------------------------- |
| `publicId` | `string` | Identificador público do employee dono do vínculo. |

### Corpo

| Campo                     | Tipo               | Obrigatório | Descrição                                                                                                                                                        |
| ------------------------- | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registrationNumber`      | `string` (max 30)  | Sim         | Matrícula do trabalhador no empregador, enviada na averbação.                                                                                                    |
| `employerTaxId`           | `string` (max 18)  | Sim         | CNPJ ou CPF do empregador, enviado na averbação. Ver [Documento do empregador](#documento-do-empregador).                                                        |
| `employerTaxIdType`       | `string` (enum)    | Sim         | `CNPJ` ou `CPF`.                                                                                                                                                 |
| `availableMargin`         | `number`           | Sim         | Margem consignável livre. Ver [Margem](#margem).                                                                                                                 |
| `workerName`              | `string` (max 200) | Não         | Nome do trabalhador. Normalizado para ASCII maiúsculo. Ausente, usa o nome cadastrado do employee.                                                               |
| `admissionDate`           | `string` (date)    | Não         | Data de admissão (`yyyy-MM-dd`). Não pode ser futura.                                                                                                            |
| `employerName`            | `string` (max 200) | Não         | Razão social ou nome do empregador.                                                                                                                              |
| `totalEarnings`           | `number`           | Não         | Remuneração total apurada na competência.                                                                                                                        |
| `marginBase`              | `number`           | Não         | Base de cálculo da margem.                                                                                                                                       |
| `workerCategory`          | `string` (enum)    | Não         | Categoria do trabalhador no eSocial — ver [Categoria do Trabalhador](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/enums/categoria-trabalhador.md). |
| `activeConsignmentsCount` | `integer`          | Não         | Quantidade de consignações ativas do vínculo.                                                                                                                    |

`usableMargin` não é campo de entrada: é calculada a partir de `availableMargin`, como no fluxo de margem da plataforma, e volta na resposta.

## Documento do empregador <a href="#documento-do-empregador" id="documento-do-empregador"></a>

Formas aceitas em `employerTaxId`:

| Forma enviada                                            | Exemplo              | O que a plataforma faz                                |
| -------------------------------------------------------- | -------------------- | ----------------------------------------------------- |
| Completa                                                 | `12345678000195`     | usa como está                                         |
| Com máscara                                              | `12.345.678/0001-95` | remove a pontuação                                    |
| Raiz de 8 dígitos                                        | `12345678`           | completa como matriz (`0001` + dígitos verificadores) |
| Raiz alfanumérica de 8 caracteres (CNPJ novo da Receita) | `12ABC345`           | completa como matriz: `12ABC345000188`                |
| Zeros à esquerda truncados                               | `1234567000195`      | completa para `01234567000195`                        |

O documento completo identifica o vínculo; a forma recebida é a enviada à Dataprev na averbação. Documento que não resolva para CNPJ ou CPF válido é recusado com `400`.

## Margem <a href="#margem" id="margem"></a>

`availableMargin` é comparada com a parcela **antes** da averbação. Contrato com parcela acima dela é recusado de forma definitiva, sem nova tentativa: informe a margem real do trabalhador.

## Comportamento

* **Idempotente por `registrationNumber` + `employerTaxId`**: o mesmo par para o mesmo employee atualiza o vínculo (`200`) em vez de criar outro (`201`), mesmo em formas diferentes do documento (raiz e depois CNPJ completo).
* Campos opcionais omitidos não apagam o que uma consulta de margem anterior gravou (categoria, nome do empregador, data de admissão).
* Vínculo encerrado não é reativado: `409` (`EMPLOYMENT_RELATIONSHIP_NOT_ACTIVE`).
* Vínculo cadastrado ou atualizado por aqui **não é elegível a renegociação**, que exige consulta de margem recente pela plataforma. Uma nova consulta de margem pela plataforma restabelece.

## Exemplo

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

{
  "registrationNumber": "0000123456",
  "employerTaxId": "12.345.678/0001-95",
  "employerTaxIdType": "CNPJ",
  "employerName": "EMPRESA EXEMPLO LTDA",
  "workerName": "Alberto Pereira",
  "admissionDate": "2020-01-15",
  "availableMargin": 900.00,
  "totalEarnings": 5000.00,
  "marginBase": 4000.00,
  "workerCategory": "GENERAL_EMPLOYEE",
  "activeConsignmentsCount": 1
}
```

Resposta `200`:

```json
{
  "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "registrationNumber": "0000123456",
  "employerTaxId": "12345678000195",
  "employerTaxIdType": "CNPJ",
  "employerName": "EMPRESA EXEMPLO LTDA",
  "workerName": "ALBERTO PEREIRA",
  "admissionDate": "2020-01-15",
  "status": "ACTIVE",
  "workerCategory": "GENERAL_EMPLOYEE",
  "totalEarnings": 5000.00,
  "marginBase": 4000.00,
  "availableMargin": 900.00,
  "usableMargin": 315.00,
  "activeConsignmentsCount": 1
}
```

## Erros

| Código | `errorCode`                          | Situação                                                                                                                                                                        |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | —                                    | Payload inválido (`properties.errors`): campo obrigatório ausente (inclui `activeConsignmentsCount`), margem negativa, data de admissão futura, `employerTaxId` fora do formato |
| 400    | —                                    | Enum ou data inválidos (`type: about:blank`)                                                                                                                                    |
| 400    | —                                    | `Documento do empregador inválido: <documento>` — `employerTaxId` não é CNPJ/CPF válido                                                                                         |
| 404    | —                                    | Employee não encontrado ou de outro originador                                                                                                                                  |
| 409    | `EMPLOYMENT_RELATIONSHIP_TERMINATED` | Vínculo com data de desligamento na Dataprev                                                                                                                                    |
| 423    | `DATAPREV_SUSPENSION_WINDOW`         | Janela de suspensão da Dataprev                                                                                                                                                 |
| 429    | —                                    | Mais de 75 requisições **por minuto**                                                                                                                                           |

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

Com o `publicId` do vínculo, siga para a [simulação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/simulacoes.md) e a [proposta](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/propostas/criar-proposta.md), informando `employmentRelationshipPublicId`.

## Cadastrar Vínculo Empregatício

> Cadastra um vínculo empregatício a partir de dados de margem obtidos pelo originador em\
> outro provedor, sem consumir uma consulta de margem da plataforma.\
> \
> O vínculo criado é referenciado por \`employmentRelationshipPublicId\` na criação da proposta e\
> é o que alimenta a averbação na Dataprev. A operação é idempotente pela chave\
> \`(employee, registrationNumber, employerTaxId)\`: reenviar o mesmo par atualiza margem e\
> status do vínculo existente em vez de duplicá-lo.\
> \
> A autorização do trabalhador na Dataprev continua sendo obrigatória e não é substituída por\
> este cadastro — ela é concedida ao código solicitante da plataforma.\
> \
> Vínculo cadastrado por aqui fica com \`dataprevSyncedAt\` nulo (e o cadastro \*\*limpa\*\* esse\
> carimbo quando sobrescreve um vínculo antes sincronizado, porque a margem passa a ser asserção\
> do originador). Consequência prática: enquanto não houver uma consulta de margem da plataforma,\
> o vínculo não é elegível a \*\*renegociação\*\*, que exige snapshot de margem fresco.<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/{publicId}/employment-relationships":{"post":{"summary":"Cadastrar Vínculo Empregatício","description":"Cadastra um vínculo empregatício a partir de dados de margem obtidos pelo originador em\noutro provedor, sem consumir uma consulta de margem da plataforma.\n\nO vínculo criado é referenciado por `employmentRelationshipPublicId` na criação da proposta e\né o que alimenta a averbação na Dataprev. A operação é idempotente pela chave\n`(employee, registrationNumber, employerTaxId)`: reenviar o mesmo par atualiza margem e\nstatus do vínculo existente em vez de duplicá-lo.\n\nA autorização do trabalhador na Dataprev continua sendo obrigatória e não é substituída por\neste cadastro — ela é concedida ao código solicitante da plataforma.\n\nVínculo cadastrado por aqui fica com `dataprevSyncedAt` nulo (e o cadastro **limpa** esse\ncarimbo quando sobrescreve um vínculo antes sincronizado, porque a margem passa a ser asserção\ndo originador). Consequência prática: enquanto não houver uma consulta de margem da plataforma,\no vínculo não é elegível a **renegociação**, que exige snapshot de margem fresco.\n","tags":["Employees"],"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,"schema":{"type":"string","maxLength":255},"description":"Chave de idempotência, aceita em todo `POST`\nsob `/api/v1/originator/`. Reenvio com a mesma chave devolve a resposta original; chave\nem processamento concorrente responde `409`.\n\nNão confundir com a idempotência de negócio deste endpoint (chave `registrationNumber` +\n`employerTaxId`), que vale mesmo sem o header.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Cadastro de vínculo empregatício pelo originador que consultou a margem em outro provedor.\nCarrega os campos que a averbação na Dataprev consome, mais a margem disponível — sem ela o\ncontrato é rejeitado na pré-averbação.\n\nO vínculo é idempotente pela chave `(employee, registrationNumber, employerTaxId normalizado)`:\nreenviar o mesmo par atualiza a margem (`200`) em vez de criar um vínculo novo (`201`). Campos\nopcionais omitidos não apagam dado que uma consulta de margem anterior já tenha gravado.\n\n`usableMargin` **não** é campo de entrada: ela é derivada de `availableMargin` pelo percentual\nconfigurado por originador, do mesmo jeito que no fluxo de margem da Dataprev.\n\nCadastro externo **não sobrescreve vínculo desligado**: se o vínculo persistido tiver\n`terminationDate`, a chamada é recusada com `409`.\n","required":["registrationNumber","employerTaxId","employerTaxIdType","availableMargin","activeConsignmentsCount"],"properties":{"registrationNumber":{"type":"string","minLength":1,"maxLength":30,"description":"Matrícula do trabalhador no empregador (`matricula` da averbação)."},"employerTaxId":{"type":"string","minLength":1,"maxLength":18,"pattern":"^[A-Za-z0-9./-]+$","description":"CNPJ ou CPF do empregador (`numeroInscricaoEmpregador` da averbação). Aceita a forma\nparcial — raiz de 8 dígitos, ou documento cujos zeros à esquerda foram truncados por\nserialização numérica. A plataforma persiste o documento completo para identidade do\nvínculo e preserva a forma recebida para enviar à Dataprev. Máscara é aceita e removida\n(daí `maxLength: 18`, que acomoda `12.345.678/0001-95`).\n\nDocumento que não resolve para um CNPJ/CPF completo e válido é recusado com `400` — o\noriginador tem o documento em mãos, então não há o truque de truncamento que justifica\naceitar forma inválida vinda da Dataprev.\n"},"employerTaxIdType":{"type":"string","enum":["CNPJ","CPF"],"description":"Tipo do documento do empregador. Define `codigoInscricaoEmpregador` na averbação — a\ninferência por tamanho não funciona sobre documento parcial, por isso é obrigatório.\n"},"workerName":{"type":"string","maxLength":200,"description":"Nome do trabalhador (`nomeTrabalhador` da averbação). Normalizado para ASCII maiúsculo.\nQuando ausente, cai no nome cadastrado do employee.\n"},"availableMargin":{"type":"number","format":"double","minimum":0,"description":"Margem consignável livre. Comparada com o valor da parcela antes da averbação; contrato\ncuja parcela excede este valor é recusado como falha permanente.\n"},"admissionDate":{"type":"string","format":"date","description":"Data de admissão no vínculo."},"employerName":{"type":"string","maxLength":200,"description":"Razão social ou nome do empregador."},"totalEarnings":{"type":"number","format":"double","minimum":0,"description":"Remuneração total apurada na competência."},"marginBase":{"type":"number","format":"double","minimum":0,"description":"Base de cálculo da margem."},"workerCategory":{"type":"string","description":"Categoria do trabalhador no eSocial."},"activeConsignmentsCount":{"type":"integer","minimum":0,"description":"Quantidade de consignações ativas do vínculo. É o número que o teto de empréstimos por\nvínculo compara na renegociação, por isso é obrigatório: um vínculo sem essa informação\npassaria pelo teto sem ser conferido.\n"}}}}}},"responses":{"200":{"description":"Vínculo já existente atualizado (mesma chave `registrationNumber` + `employerTaxId`)","content":{"application/json":{"schema":{"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."}}}}}},"201":{"description":"Vínculo cadastrado","content":{"application/json":{"schema":{"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."}}}}}},"400":{"description":"Dados inválidos, corpo ilegível ou documento do empregador 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":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"Employee não encontrado ou de outro originador.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"409":{"description":"Vínculo desligado na Dataprev, 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**."}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}},"429":{"description":"Mais de 75 requisições por minuto. 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**."}}}}}}}}}}}}}
```

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