> 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/contratos/criar-contrato.md).

# Criar Contrato

Cria o contrato (CCB) a partir de uma proposta. O contrato nasce com status `CREATED`.

## Request

`POST /api/v1/originator/proposals/{proposalPublicId}/contracts`

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

### Parâmetros

| Parâmetro          | Local  | Tipo            | Obrigatório | Descrição                                                                                                                                           |
| ------------------ | ------ | --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proposalPublicId` | path   | `string (uuid)` | Sim         | Identificador público da proposta que originará o contrato                                                                                          |
| `Idempotency-Key`  | header | `string`        | Não         | Evita contrato duplicado em retentativas (máx. 255). Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md) |

O número de parcelas vem da proposta.

### Corpo

| Campo                     | Tipo              | Obrigatório | Descrição                                                                                                                                               |
| ------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractAmount`          | `number`          | Sim         | Valor principal do contrato em reais (mínimo `0.01`)                                                                                                    |
| `contractDate`            | `string` (`date`) | Sim         | Data do contrato (`yyyy-MM-dd`). Não pode ser no passado                                                                                                |
| `contractNumber`          | `string`          | Não         | Número do contrato informado pelo originador. Obrigatório quando a estratégia é `ORIGINATOR_PROVIDED`. Exatamente 8 dígitos numéricos (pattern `\d{8}`) |
| `firstInstallmentDueDate` | `string` (`date`) | Não         | Data do primeiro vencimento. Não pode ser no passado                                                                                                    |
| `lastInstallmentDueDate`  | `string` (`date`) | Não         | Data do último vencimento. Não pode ser no passado                                                                                                      |
| `pix`                     | `object`          | Condicional | Conta de desembolso via Pix. Informe `pix` **ou** `bankAccount`                                                                                         |
| `bankAccount`             | `object`          | Condicional | Conta de desembolso via conta bancária. Informe `bankAccount` **ou** `pix`                                                                              |
| `address`                 | `object`          | Sim         | Endereço residencial do trabalhador — ver objeto `address`                                                                                              |
| `redirectUrl`             | `string`          | Não         | URL de redirecionamento após a assinatura digital (máx. 1000; apenas scheme `http`/`https`)                                                             |
| `suppressNotification`    | `boolean`         | Não         | Estratégia **GIRO**: `true` não envia o WhatsApp ao trabalhador; o link de assinatura chega só no webhook `CONTRACT_DOCUMENT_READY`                     |
| `signatureExpirationDate` | `string` (`date`) | Não         | Data limite para assinar (`yyyy-MM-dd`). Padrão: 7 dias. Ver [Prazo de assinatura](#prazo-de-assinatura)                                                |
| `attendantName`           | `string`          | Não         | Nome do atendente ou vendedor responsável pela venda (máx. 150)                                                                                         |
| `attendantCpf`            | `string`          | Não         | CPF do atendente ou vendedor responsável (máx. 14)                                                                                                      |
| `contractInfo`            | `object`          | Não         | Dados complementares impressos na CCB                                                                                                                   |
| `eligibilityAttributes`   | `object`          | Não         | Dados repassados ao Fundo que compra o recebível                                                                                                        |

#### Objeto `pix`

| Campo     | Tipo            | Obrigatório | Descrição                                                     |
| --------- | --------------- | ----------- | ------------------------------------------------------------- |
| `keyType` | `string` (enum) | Sim         | Tipo da chave Pix (`CPF`, `CNPJ`, `EMAIL`, `PHONE`, `RANDOM`) |
| `key`     | `string`        | Sim         | Valor da chave Pix conforme o tipo informado (máx. 255)       |

#### Objeto `bankAccount`

| Campo           | Tipo            | Obrigatório | Descrição                                      |
| --------------- | --------------- | ----------- | ---------------------------------------------- |
| `bankCode`      | `string`        | Sim         | Código COMPE/ISPB do banco de destino (máx. 3) |
| `branchNumber`  | `string`        | Sim         | Número da agência bancária de destino (máx. 4) |
| `branchDigit`   | `string`        | Não         | Dígito verificador da agência (máx. 2)         |
| `accountNumber` | `string`        | Sim         | Número da conta para crédito (máx. 10)         |
| `accountDigit`  | `string`        | Não         | Dígito verificador da conta (máx. 2)           |
| `accountType`   | `string` (enum) | Sim         | Tipo da conta (`CHECKING`, `SAVINGS`)          |

#### Objeto `address`

| Campo          | Tipo     | Obrigatório | Descrição                                     |
| -------------- | -------- | ----------- | --------------------------------------------- |
| `street`       | `string` | Sim         | Logradouro do endereço residencial (máx. 200) |
| `number`       | `string` | Não         | Número do imóvel (máx. 20)                    |
| `complement`   | `string` | Não         | Complemento do endereço (máx. 100)            |
| `neighborhood` | `string` | Sim         | Bairro (máx. 100)                             |
| `city`         | `string` | Sim         | Município (máx. 100)                          |
| `state`        | `string` | Sim         | Unidade federativa (UF) com 2 letras          |
| `zipCode`      | `string` | Sim         | CEP (máx. 10)                                 |

#### Objeto `contractInfo`

Todos os campos são opcionais.

| Campo                      | Tipo     | Descrição                                                                                                                                |
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `penaltyFee`               | `number` | Percentual ou valor da multa por atraso                                                                                                  |
| `remuneratoryInterestRate` | `number` | Taxa de juros remuneratórios                                                                                                             |
| `guarantees`               | `string` | Descrição das garantias (máx. 500)                                                                                                       |
| `bankFee`                  | `number` | Tarifa bancária                                                                                                                          |
| `insurancePolicyNumber`    | `string` | Número da apólice de seguro (máx. 50)                                                                                                    |
| `insurerName`              | `string` | Nome da seguradora (máx. 100)                                                                                                            |
| `insurancePremiumAmount`   | `number` | Valor do prêmio de seguro (≥ 0, até 2 casas decimais). Quando informado, tem de ser igual ao `insuranceAmount` da simulação — ver abaixo |
| `documentObservation`      | `string` | Observações gerais no documento (máx. 2048)                                                                                              |

`insurancePremiumAmount` sai na CCB como "Valor do Prêmio" e tem de ser igual ao `insuranceAmount` da simulação; diferente, o contrato é recusado (`422 INSURANCE_PREMIUM_MISMATCH`). Sem ele, a CCB mostra o seguro financiado.

#### Objeto `eligibilityAttributes`

Opcional. A Giro não usa esses dados: repassa ao Fundo que compra o recebível.

| Campo       | Tipo     | Obrigatório | Descrição                       |
| ----------- | -------- | ----------- | ------------------------------- |
| `employer`  | `object` | Não         | Dados do empregador — 8 campos  |
| `worker`    | `object` | Não         | Dados do trabalhador — 8 campos |
| `operation` | `object` | Não         | Dados da operação — 4 campos    |

Todos os campos dos três grupos são opcionais. Lista completa e valores aceitos em [Atributos de Elegibilidade para Cessão](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/atributos-de-cessao.md).

### Prazo de assinatura

Vale para a estratégia **GIRO**. Na [assinatura pelo originador](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador.md), o prazo do link é seu.

* A data não pode estar no passado na criação (`400`).
* Se ela vencer antes de o link ser gerado, o prazo passa a ser o fim do dia da geração.
* Vencido o prazo, o contrato é cancelado (`documentStatus` = `EXPIRED`, `status` = `CANCELLED`) e você recebe o webhook de falha de assinatura. Pode levar alguns minutos.
* [Reenviar o link](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-giro/reenviar-link-assinatura.md) não estende o prazo.

## Response

`201 Created` com o contrato no mesmo formato de [Buscar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md#response). Em `CREATED`, `rejectionReason` e `cancelReason` são `null`.

Próximo passo, conforme a [estratégia de assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md):

* **GIRO**: a Giro gera a CCB e envia o link de assinatura ao trabalhador por WhatsApp.
* **ORIGINATOR\_MANAGED**: você coleta a assinatura e envia a CCB assinada por [Upload do Contrato Assinado](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/assinatura-originador/upload-contrato-assinado.md).

Com a CCB assinada, o contrato segue para averbação na Dataprev.

## Exemplo

```http
POST /api/v1/originator/proposals/0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b10/contracts HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json
Idempotency-Key: 7d9f3a1c-5b2e-4c8a-9f1d-2e6b8c0a4d31

{
  "contractAmount": 5000,
  "contractDate": "2026-10-15",
  "firstInstallmentDueDate": "2027-01-25",
  "lastInstallmentDueDate": "2027-12-25",
  "attendantName": "Maria Atendente",
  "attendantCpf": "98765432100",
  "suppressNotification": false,
  "signatureExpirationDate": "2026-10-18",
  "pix": {
    "keyType": "CPF",
    "key": "12345678901"
  },
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 101",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234567"
  },
  "eligibilityAttributes": {
    "employer": {
      "taxId": "11222333000181",
      "legalNature": "LTDA",
      "companySize": "MICRO"
    },
    "worker": {
      "birthDate": "1979-11-03",
      "gender": "FEMALE",
      "workerStatus": "EMPLOYEE_CLT"
    },
    "operation": {
      "hasCreditInsurance": false,
      "deductibleType": "PAYROLL_LOAN"
    }
  }
}
```

Resposta `201`:

```json
{
  "requestNumber": "GTAB12CD34EF",
  "contractNumber": "00345678",
  "employeePublicId": "Kj8mP2xQ9nR4sT6v",
  "proposal": {
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "employeePublicId": "Kj8mP2xQ9nR4sT6v",
    "simulationPublicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b05",
    "loanAmount": 5750,
    "financedAmount": 5935.64,
    "totalInterestAmount": 1189.72,
    "debitAmount": 7125.36,
    "monthlyInterestRate": 1.97,
    "monthlyEffectiveCost": 2.43,
    "annualEffectiveCost": 33.18,
    "disbursementAmount": 5627.78,
    "insuranceAmount": 87.3,
    "iofAmount": 63.42,
    "tacAmount": 0,
    "installmentCount": 12,
    "dueDate": "2027-01-25",
    "status": "CONVERTED_TO_CONTRACT",
    "createdDate": "2026-10-15T10:00:00Z"
  },
  "status": "CREATED",
  "endorsementStatus": "PENDING",
  "contractAmount": 5000,
  "installments": 12,
  "contractDate": "2026-10-15",
  "firstInstallmentDueDate": "2027-01-25",
  "lastInstallmentDueDate": "2027-12-25",
  "totalInterestAmount": 1250,
  "debitAmount": 7125.36,
  "monthlyInterestRate": 1.99,
  "monthlyEffectiveCost": 2.15,
  "annualEffectiveCost": 28.97,
  "disbursementAmount": 4800,
  "insuranceAmount": 87.3,
  "iofAmount": 45.2,
  "tacAmount": 0,
  "attendantName": "Maria Atendente",
  "attendantCpf": "98765432100",
  "bankInfo": {
    "type": "PIX",
    "pix": {
      "keyType": "CPF",
      "key": "12345678901"
    }
  },
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 101",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234567"
  },
  "documentStatus": "PENDING",
  "nsu": "1234567890123456789",
  "suppressNotification": false,
  "signatureExpirationDate": "2026-10-18",
  "rejectionReason": null,
  "cancelReason": null,
  "createdDate": "2026-10-15T10:00:00Z"
}
```

## Erros

| Código | `errorCode`                      | Situação                                                                                                                                                                                                                                                                                                                                                                       |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | —                                | Payload inválido (`properties.errors`): campo obrigatório ausente/inválido, `pix` e `bankAccount` ambos ou nenhum (chave `paymentInfoValid`), data no passado, `insurancePremiumAmount` negativo ou com mais de 2 casas, `address.number` fora do formato, `redirectUrl` inválida                                                                                              |
| 400    | —                                | Enum (`pix.keyType`, `accountType`) ou data inválidos (`type: about:blank`). Para chave Pix aleatória, use `RANDOM`                                                                                                                                                                                                                                                            |
| 400    | —                                | Assinatura pela Giro com cadastro do employee incompleto (CPF, data de nascimento, telefone); datas de parcela ausentes; primeiro vencimento a menos de 30 dias do contrato; `contractNumber` obrigatório ou inválido para a estratégia do originador (ver [regras sem `errorCode`](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md#regras-sem-errorcode)) |
| 400    | —                                | CET acima do teto: `title: Elegibility Violation`, `properties.violations[].code` = `MAX_EFFECTIVE_COST_EXCEEDED`                                                                                                                                                                                                                                                              |
| 403    | `AUCTION_PARTICIPATION_DISABLED` | Proposta de leilão (criada com `proposalNumber`) e originador sem participação no leilão habilitada, inclusive quando a habilitação foi retirada depois da proposta. Avaliado depois do `409` de proposta já convertida; nada é gravado                                                                                                                                        |
| 404    | —                                | Proposta não encontrada ou de outro originador                                                                                                                                                                                                                                                                                                                                 |
| 409    | `CONTRACT_NUMBER_ALREADY_USED`   | `contractNumber` já usado pelo originador                                                                                                                                                                                                                                                                                                                                      |
| 409    | —                                | `Proposta já convertida em contrato` ou `Proposta em status inválido para criação de contrato`                                                                                                                                                                                                                                                                                 |
| 422    | `INSURANCE_PREMIUM_MISMATCH`     | `contractInfo.insurancePremiumAmount` difere do `insuranceAmount` da simulação                                                                                                                                                                                                                                                                                                 |
| 422    | `EMPLOYEE_GENDER_REQUIRED`       | O originador exige gênero e o employee não tem                                                                                                                                                                                                                                                                                                                                 |
| 422    | `POS_ALIAS_NOT_FOUND`            | `pointOfSaleAlias` não cadastrado                                                                                                                                                                                                                                                                                                                                              |
| 423    | `DATAPREV_SUSPENSION_WINDOW`     | Janela de suspensão da Dataprev. Recusada antes da validação do corpo                                                                                                                                                                                                                                                                                                          |
| 429    | —                                | Mais de 75 requisições por segundo                                                                                                                                                                                                                                                                                                                                             |

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

## Criar Contrato

> Inicia a formalização contratual a partir de uma proposta previamente criada.\
> O payload define dados financeiros, forma de desembolso, endereço e informações complementares necessárias para assinatura e integração.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Contracts","description":"Contratos de empréstimo"}],"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/proposals/{proposalPublicId}/contracts":{"post":{"summary":"Criar Contrato","description":"Inicia a formalização contratual a partir de uma proposta previamente criada.\nO payload define dados financeiros, forma de desembolso, endereço e informações complementares necessárias para assinatura e integração.\n","tags":["Contracts"],"parameters":[{"name":"proposalPublicId","in":"path","required":true,"description":"Identificador público da proposta","schema":{"type":"string","maxLength":36}},{"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","description":"Corpo do contrato. Informe **pix** ou **bankAccount** (exatamente um) para desembolso.\n","required":["contractAmount","contractDate","address"],"properties":{"contractAmount":{"type":"number","format":"decimal","minimum":0.01,"description":"Valor principal do contrato em reais (decimal com 2 casas decimais)."},"contractDate":{"type":"string","format":"date","description":"Data da contratação da operação (yyyy-MM-dd). Não pode ser no passado.\n"},"contractNumber":{"type":"string","minLength":8,"maxLength":8,"pattern":"^\\d{8}$","description":"Número do contrato informado pelo originador. Obrigatório quando o originador está configurado com estratégia\nORIGINATOR_PROVIDED (contractNumberStrategy). Deve ter exatamente 8 dígitos numéricos. Ignorado quando a estratégia é SYSTEM_GENERATED.\n"},"firstInstallmentDueDate":{"type":"string","format":"date","description":"Data do primeiro vencimento. Deve respeitar as regras de carência e calendário da operação. Não pode ser no passado.\n"},"lastInstallmentDueDate":{"type":"string","format":"date","description":"Data prevista para vencimento da última parcela. Não pode ser no passado.\n"},"pix":{"description":"Dados para desembolso por chave Pix. Informe `pix` ou `bankAccount`, nunca ambos.","type":"object","required":["keyType","key"],"properties":{"keyType":{"type":"string","enum":["CPF","CNPJ","EMAIL","PHONE","RANDOM"],"description":"Tipo da chave Pix.\n| Valor | Significado |\n|-------|-------------|\n| CPF | Chave CPF (11 dígitos) |\n| CNPJ | Chave CNPJ |\n| EMAIL | Chave e-mail |\n| PHONE | Chave telefone |\n| RANDOM | Chave aleatória (EVP) |\n"},"key":{"type":"string","maxLength":255,"description":"Valor da chave Pix conforme o tipo informado."}}},"bankAccount":{"description":"Dados para desembolso em conta bancária. Informe `bankAccount` ou `pix`, nunca ambos.","type":"object","required":["bankCode","branchNumber","accountNumber","accountType"],"properties":{"bankCode":{"type":"string","maxLength":3,"description":"Código COMPE/ISPB do banco de destino."},"branchNumber":{"type":"string","maxLength":4,"description":"Número da agência bancária de destino."},"branchDigit":{"type":"string","maxLength":2,"description":"Dígito verificador da agência, quando existente."},"accountNumber":{"type":"string","maxLength":10,"description":"Número da conta para crédito."},"accountDigit":{"type":"string","maxLength":2,"description":"Dígito verificador da conta, quando existente."},"accountType":{"type":"string","enum":["CHECKING","SAVINGS"],"description":"Tipo da conta.\n| Valor | Significado |\n|-------|-------------|\n| CHECKING | Conta corrente |\n| SAVINGS | Conta poupança |\n"}}},"address":{"description":"Endereço residencial do trabalhador para composição contratual.","type":"object","required":["street","neighborhood","city","state","zipCode"],"properties":{"street":{"type":"string","maxLength":200,"description":"Logradouro do endereço residencial."},"number":{"type":"string","maxLength":20,"description":"Número do imóvel."},"complement":{"type":"string","maxLength":100,"description":"Complemento do endereço (apto, bloco, etc.), se houver."},"neighborhood":{"type":"string","maxLength":100,"description":"Bairro do endereço residencial."},"city":{"type":"string","maxLength":100,"description":"Município do endereço."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"Unidade federativa (UF) com duas letras."},"zipCode":{"type":"string","maxLength":10,"description":"CEP do endereço residencial."}}},"redirectUrl":{"type":"string","maxLength":1000,"pattern":"^$|^https?://.*","description":"URL de redirecionamento após o fluxo de assinatura digital. Apenas scheme http/https aceito."},"suppressNotification":{"type":"boolean","description":"Quando `true`, a plataforma não envia notificação WhatsApp ao assinador.\nA URL de assinatura é entregue via webhook `CONTRACT_DOCUMENT_READY` para o originador gerenciar.\nQuando ausente ou `false`, o comportamento padrão (envio de notificação) é mantido.\n"},"signatureExpirationDate":{"type":"string","format":"date","description":"Data limite para assinatura do contrato (`yyyy-MM-dd`). Não pode ser no passado.\nOmitido, vale o padrão de 7 dias.\n\nO prazo é repassado ao provedor de assinatura, que é quem faz o link expirar ao fim desse\ndia. Ele conta da geração do link, não da criação do contrato — este `201` ainda não\nconfirma o prazo.\n\nVencido o prazo, a plataforma leva o `documentStatus` a `EXPIRED`, cancela o contrato\n(`status` = `CANCELLED`) e entrega o webhook `CONTRACT_SIGNING_FAILED` com `errorCode`\n`SIGNATURE_EXPIRED` — o mesmo desfecho das demais falhas de assinatura. A verificação é\nperiódica, então há defasagem de alguns minutos entre o vencimento e a mudança de status.\n\nNa assinatura gerenciada pelo originador o campo é aceito e devolvido, mas quem controla o\nprazo do link é o próprio originador.\n\nQuando ausente, aplica-se o padrão do provedor — hoje **7 dias**, contados a partir do\nmomento em que o link é gerado, e não da criação do contrato (entre as duas coisas há a\ngeração do PDF). Por isso, se a data informada já tiver passado quando o link for gerado,\nela é encurtada para o fim do dia corrente, nunca estendida para o padrão.\n\nReenviar o link (`POST /contracts/{publicId}/resend`) **não** estende este prazo.\n\nAplica-se apenas à assinatura gerenciada pela Giro. Em contratos com assinatura delegada ao\noriginador, o campo é aceito e registrado, mas quem controla o prazo do link é o próprio\noriginador.\n"},"contractInfo":{"description":"Informações contratuais complementares para formalização.","type":"object","properties":{"penaltyFee":{"type":"number","format":"decimal","description":"Percentual ou valor de multa em reais (decimal com 2 casas decimais)."},"remuneratoryInterestRate":{"type":"number","format":"decimal","description":"Taxa de juros em percentual (decimal com 4 casas decimais)."},"guarantees":{"type":"string","maxLength":500,"description":"Descrição das garantias vinculadas à operação."},"bankFee":{"type":"number","format":"decimal","description":"Tarifa bancária em reais (decimal com 2 casas decimais)."},"insurancePolicyNumber":{"type":"string","maxLength":50,"description":"Número da apólice de seguro associada ao contrato."},"insurerName":{"type":"string","maxLength":100,"description":"Nome da seguradora responsável."},"insurancePremiumAmount":{"type":"number","format":"decimal","minimum":0,"description":"Prêmio de seguro em reais (decimal com 2 casas decimais). Opcional; quando informado, tem de ser\nigual ao `insuranceAmount` da simulação que originou a proposta, senão o contrato é recusado com\n422 `INSURANCE_PREMIUM_MISMATCH`.\n"},"documentObservation":{"type":"string","maxLength":2048,"description":"Observações livres que devem constar no instrumento contratual."}}},"attendantName":{"type":"string","maxLength":150,"description":"Nome do atendente ou vendedor responsável pela venda. Opcional."},"attendantCpf":{"type":"string","maxLength":14,"description":"CPF do atendente ou vendedor responsável. Opcional."},"eligibilityAttributes":{"description":"Atributos que o Fundo usa para avaliar o recebível na cessão. **Opcional** — omiti-lo não\nimpede a originação, e integrações existentes seguem funcionando sem mudança.\n","type":"object","properties":{"employer":{"description":"Dados do empregador do trabalhador.","type":"object","properties":{"taxId":{"type":"string","pattern":"^(\\d{11}|\\d{14})$","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do empregador, somente dígitos."},"name":{"type":"string","maxLength":255,"description":"Razão social ou nome do empregador."},"legalNature":{"type":"string","enum":["EI","LTDA","MEI","SA","SLU"],"description":"Natureza jurídica do empregador. **Não** confundir com porte, que vai em `companySize`.\n| Valor | Significado |\n|-------|-------------|\n| EI | Empresário individual |\n| LTDA | Sociedade limitada |\n| MEI | Microempreendedor individual |\n| SA | Sociedade anônima |\n| SLU | Sociedade limitada unipessoal |\n"},"activityStartDate":{"type":"string","format":"date","description":"Data de início de atividade do empregador (yyyy-MM-dd). Não pode ser no futuro."},"cnae":{"type":"string","pattern":"^\\d{5,10}$","description":"Código CNAE da atividade principal, somente dígitos."},"companySize":{"type":"string","enum":["MICRO","SMALL","MEDIUM","LARGE"],"description":"Porte da empresa. É independente da natureza jurídica."},"employeeCount":{"type":"integer","minimum":0,"description":"Quantidade de funcionários do empregador."},"annualRevenue":{"type":"number","format":"decimal","minimum":0,"description":"Faturamento anual em reais, com até 2 casas decimais."}}},"worker":{"description":"Dados do trabalhador que toma o crédito.","type":"object","properties":{"birthDate":{"type":"string","format":"date","description":"Data de nascimento do trabalhador (yyyy-MM-dd). Não pode ser no futuro."},"gender":{"type":"string","enum":["MALE","FEMALE","NOT_INFORMED"],"description":"Gênero do trabalhador."},"grossSalary":{"type":"number","format":"decimal","minimum":0,"description":"Salário bruto mensal em reais, com até 2 casas decimais."},"netSalary":{"type":"number","format":"decimal","minimum":0,"description":"Salário líquido mensal em reais, com até 2 casas decimais."},"admissionDate":{"type":"string","format":"date","description":"Data de admissão do trabalhador (yyyy-MM-dd). **Aceita data futura**, ao contrário das\noutras datas do bloco: contratação agendada é legítima e o contrato pode ser enviado antes\nda data de início.\n"},"cboCode":{"type":"string","pattern":"^\\d{4,10}$","description":"Código CBO da ocupação, somente dígitos."},"maritalStatus":{"type":"string","enum":["MARRIED","DIVORCED","SEPARATED","SINGLE","STABLE_UNION","WIDOWED"],"description":"Estado civil do trabalhador."},"workerStatus":{"type":"string","enum":["RETIRED","EMPLOYEE_CLT","DISMISSED","PENSIONER","PUBLIC_SERVANT"],"description":"Vínculo do trabalhador.\n| Valor | Significado |\n|-------|-------------|\n| RETIRED | Aposentado |\n| EMPLOYEE_CLT | Empregado CLT |\n| DISMISSED | Desligado |\n| PENSIONER | Pensionista |\n| PUBLIC_SERVANT | Servidor público |\n"}}},"operation":{"description":"Parâmetros da operação de crédito consignado.","type":"object","properties":{"payrollMarginPercentage":{"type":"number","format":"decimal","minimum":0,"description":"Percentual da margem consignável, com até 2 casas decimais."},"maxDeductibleAmount":{"type":"number","format":"decimal","minimum":0,"description":"Valor máximo consignável em reais, com até 2 casas decimais."},"hasCreditInsurance":{"type":"boolean","description":"Indica seguro prestamista na operação. Quando ausente, o Fundo recebe `false` —\n\"não informado\" equivale a \"não tem\".\n"},"deductibleType":{"type":"string","enum":["FGTS_ANTICIPATION","BENEFIT_CARD","PAYROLL_CREDIT_CARD","PAYROLL_LOAN","REFINANCING_OR_PORTABILITY","PAYROLL_CARD_WITHDRAWAL"],"description":"Modalidade da operação consignada.\n| Valor | Significado |\n|-------|-------------|\n| FGTS_ANTICIPATION | Antecipação de FGTS |\n| BENEFIT_CARD | Cartão benefício |\n| PAYROLL_CREDIT_CARD | Cartão de crédito consignado |\n| PAYROLL_LOAN | Empréstimo consignado |\n| REFINANCING_OR_PORTABILITY | Refinanciamento ou portabilidade |\n| PAYROLL_CARD_WITHDRAWAL | Saque do cartão consignado |\n"}}}}}}}}}},"responses":{"201":{"description":"Contrato criado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","maxLength":36,"description":"Identificador público do contrato. Pode vir omitido (ausente no JSON) em contratos antigos."},"requestNumber":{"type":"string","maxLength":36,"description":"Número da requisição do contrato. Contratos criados a partir da adoção do `publicId` nascem com o mesmo valor dele (UUID de 36 caracteres); anteriores mantêm o formato legado GT + 10 alfanuméricos maiúsculos. Ex. GTAB12CD34EF"},"contractNumber":{"type":"string","description":"Número do contrato (8 dígitos com zero à esquerda).\nPor padrão (estratégia GIRO), o número é gerado automaticamente pela plataforma.\nNa estratégia ORIGINATOR_MANAGED, o originador pode informar o número no momento da criação do contrato.\n"},"dataprevContractNumber":{"type":"string","nullable":true,"maxLength":30,"description":"Identificador do contrato perante o Dataprev — corresponde ao campo `numeroContrato`\ntrocado com o Dataprev em averbação, alteração, suspensão, reativação e exclusão.\nUse este valor para correlacionar o contrato na GTPayroll com os registros do Dataprev.\n\nTrate como **string opaca**: o formato não faz parte do contrato e pode mudar sem\naviso. Não derive nem reconstrua o valor a partir de outros campos.\n\nPode vir `null` em contratos legados criados antes da introdução do campo.\n"},"employeePublicId":{"type":"string","description":"Identificador público do trabalhador (16 caracteres Base64 URL-safe)."},"proposal":{"type":"object","properties":{"publicId":{"type":"string","description":"Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v"},"employeePublicId":{"type":"string","description":"Identificador público opaco do employee (16 caracteres Base64 URL-safe). Pode vir ausente em registros antigos.","nullable":true},"simulationPublicId":{"type":"string","format":"uuid","nullable":true,"description":"Identificador público opaco da simulação de referência, quando houver."},"loanAmount":{"type":"number","format":"decimal","description":"Valor do empréstimo em reais (decimal com 2 casas decimais)."},"financedAmount":{"type":"number","format":"decimal","description":"Valor financiado em reais (decimal com 2 casas decimais)."},"totalInterestAmount":{"type":"number","format":"decimal","description":"Juros totais em reais (decimal com 2 casas decimais)."},"debitAmount":{"type":"number","format":"decimal","minimum":0,"description":"Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places)."},"monthlyInterestRate":{"type":"number","format":"decimal","description":"Taxa mensal em percentual (decimal com 4 casas decimais)."},"annualInterestRate":{"type":"number","format":"decimal","description":"Taxa de juros anual em percentual (snapshot da proposta)."},"monthlyEffectiveCost":{"type":"number","format":"decimal","description":"CET mensal em percentual (decimal com 4 casas decimais)."},"annualEffectiveCost":{"type":"number","format":"decimal","description":"CET anual em percentual (decimal com 4 casas decimais)."},"disbursementAmount":{"type":"number","format":"decimal","description":"Valor a desembolsar em reais (decimal com 2 casas decimais)."},"insuranceAmount":{"type":"number","format":"decimal","description":"Seguro em reais (decimal com 2 casas decimais)."},"iofAmount":{"type":"number","format":"decimal","description":"IOF em reais (decimal com 2 casas decimais)."},"tacAmount":{"type":"number","format":"decimal","description":"TAC em reais. Sempre `0`; valor diferente responde `400 TAC_NOT_ALLOWED`."},"outstandingBalance":{"type":"number","format":"decimal","description":"Saldo devedor em reais (decimal com 2 casas decimais)."},"installmentCount":{"type":"integer"},"dueDate":{"type":"string","format":"date"},"status":{"type":"string","enum":["PENDING","ACCEPTED","REJECTED","EXPIRED","CONVERTED_TO_CONTRACT"],"description":"Status da proposta.\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando aceite do trabalhador |\n| ACCEPTED | Aceita pelo trabalhador |\n| REJECTED | Rejeitada pelo trabalhador |\n| EXPIRED | Expirada (prazo de aceite) |\n| CONVERTED_TO_CONTRACT | Convertida em contrato |\n"},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time"},"installments":{"type":"array","items":{"type":"object","properties":{"installmentNumber":{"type":"integer","description":"Número da parcela (1-based)."},"dueDate":{"type":"string","format":"date","description":"Data de vencimento da parcela."},"installmentAmount":{"type":"number","format":"decimal","description":"Valor da parcela (desconto em folha) em reais."},"amortizationAmount":{"type":"number","format":"decimal","description":"Amortização (principal) da parcela em reais."},"interestAmount":{"type":"number","format":"decimal","description":"Juros da parcela em reais."},"iofAmount":{"type":"number","format":"decimal","description":"IOF da parcela em reais."},"feesAmount":{"type":"number","format":"decimal","description":"Taxas da parcela em reais."},"outstandingBalance":{"type":"number","format":"decimal","description":"Saldo devedor após a parcela em reais."},"daysToCompensate":{"type":"integer","description":"Dias para compensação."},"documentNumber":{"type":"string","maxLength":10,"description":"Número identificador do vencimento informado na criação da proposta. Vazio quando o originador não enviou; nesse caso a CCB vai ao banco emissor com o número da CCB seguido da parcela em dois dígitos (`0000000101`)."},"ourNumber":{"type":"string","maxLength":32,"description":"Nosso número do documento no banco emissor."},"ourNumberBankCode":{"type":"string","maxLength":3,"description":"Código do banco do nosso número do documento."},"participantControl":{"type":"string","maxLength":25,"description":"Controle do participante informado na criação da proposta. Vazio quando o originador não enviou; nesse caso a CCB vai ao banco emissor com o número da CCB, hífen e a parcela em dois dígitos (`00000001-01`)."}}}},"createdDate":{"type":"string","format":"date-time"}},"description":"Proposta completa que originou o contrato, incluindo a lista de parcelas (installments)."},"status":{"type":"string","enum":["CREATED","SIGNED","ENDORSED","FORMALIZED","COMPLETED","CANCELLED"],"description":"Ciclo de vida do contrato.\n| Valor | Significado |\n|-------|-------------|\n| CREATED | Contrato criado, aguardando assinatura |\n| SIGNED | Assinado pelo trabalhador |\n| ENDORSED | Averbação consignada confirmada |\n| FORMALIZED | Formalizado no sistema de pagamento |\n| COMPLETED | Operação concluída (desembolsado) |\n| CANCELLED | Cancelado |\n"},"endorsementStatus":{"type":"string","enum":["PENDING","PROCESSING","ENDORSED","FAILED","RETRYING","EXCLUDING","EXCLUDED"],"description":"Situação da averbação no convênio.\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando averbação |\n| PROCESSING | Em processamento no convênio |\n| ENDORSED | Averbação confirmada |\n| FAILED | Falha na averbação |\n| RETRYING | Nova tentativa em andamento |\n"},"endorsementProtocol":{"type":"string","description":"Protocolo retornado pelo provedor de averbação, quando disponível."},"contractAmount":{"type":"number","format":"decimal","description":"Valor principal do contrato em reais (decimal com 2 casas decimais)."},"installments":{"type":"integer","description":"Quantidade de parcelas definida no contrato."},"contractDate":{"type":"string","format":"date","description":"Data de contratação (yyyy-MM-dd)."},"firstInstallmentDueDate":{"type":"string","format":"date","description":"Data de vencimento da primeira parcela."},"lastInstallmentDueDate":{"type":"string","format":"date","description":"Data de vencimento da última parcela."},"signedAt":{"type":"string","format":"date-time","description":"Data e hora em que o contrato foi assinado (UTC)."},"formalizedAt":{"type":"string","format":"date-time","description":"Data e hora em que a formalização foi concluída (UTC)."},"paidAt":{"type":"string","format":"date-time","description":"Data e hora de liquidação/desembolso do contrato (UTC)."},"paymentReceiptUrl":{"type":"string","format":"uri","nullable":true,"maxLength":512,"description":"URL do comprovante de pagamento emitido pela instituição de pagamento no desembolso. Presente após o pagamento, inclusive desembolso após cancelamento (contrato CANCELLED); permanente; não exige autenticação — trate como dado sensível."},"endorsedAt":{"type":"string","format":"date-time","description":"Data e hora de confirmação da averbação (UTC)."},"totalInterestAmount":{"type":"number","format":"decimal","description":"Valor total de juros da operação em reais (decimal com 2 casas decimais)."},"debitAmount":{"type":"number","format":"decimal","minimum":0,"description":"Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places)."},"monthlyInterestRate":{"type":"number","format":"decimal","description":"Taxa de juros mensal em percentual (decimal com 4 casas decimais)."},"monthlyEffectiveCost":{"type":"number","format":"decimal","description":"Custo efetivo mensal (CET mensal) em percentual (decimal com 4 casas decimais)."},"annualEffectiveCost":{"type":"number","format":"decimal","description":"Custo efetivo anual (CET anual) em percentual (decimal com 4 casas decimais)."},"disbursementAmount":{"type":"number","format":"decimal","description":"Valor líquido desembolsado ao trabalhador em reais (decimal com 2 casas decimais)."},"insuranceAmount":{"type":"number","format":"decimal","description":"Valor do seguro prestamista em reais (decimal com 2 casas decimais)."},"iofAmount":{"type":"number","format":"decimal","description":"Valor do IOF incidente na operação em reais (decimal com 2 casas decimais)."},"tacAmount":{"type":"number","format":"decimal","description":"Valor da TAC (Taxa de Abertura de Crédito) em reais (decimal com 2 casas decimais)."},"attendantName":{"type":"string","maxLength":150,"description":"Nome do atendente ou vendedor responsável pela venda."},"attendantCpf":{"type":"string","maxLength":14,"description":"CPF do atendente ou vendedor responsável."},"bankInfo":{"description":"Informações de destino financeiro para pagamento/desembolso.","type":"object","properties":{"type":{"type":"string","description":"Modalidade de destino financeiro utilizada (PIX ou BANK_ACCOUNT)."},"pix":{"description":"Dados de chave Pix utilizados, quando aplicável.","type":"object","properties":{"keyType":{"type":"string","description":"Tipo da chave Pix registrada no contrato."},"key":{"type":"string","description":"Valor da chave Pix registrada."}}},"bankAccount":{"description":"Dados bancários utilizados, quando aplicável.","type":"object","properties":{"bankCode":{"type":"string","description":"Código do banco registrado no contrato."},"branchNumber":{"type":"string","description":"Agência bancária registrada."},"branchDigit":{"type":"string","description":"Dígito da agência registrado."},"accountNumber":{"type":"string","description":"Número da conta registrada."},"accountDigit":{"type":"string","description":"Dígito da conta registrado."},"accountType":{"type":"string","description":"Tipo da conta registrada para desembolso."}}}}},"address":{"description":"Endereço associado ao contrato.","type":"object","properties":{"street":{"type":"string","description":"Logradouro registrado no contrato."},"number":{"type":"string","description":"Número do imóvel registrado."},"complement":{"type":"string","description":"Complemento do endereço registrado."},"neighborhood":{"type":"string","description":"Bairro registrado."},"city":{"type":"string","description":"Cidade registrada."},"state":{"type":"string","description":"UF registrada."},"zipCode":{"type":"string","description":"CEP registrado."}}},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do contrato no sistema (UTC)."},"nsu":{"type":"string","maxLength":19,"description":"NSU (Número Sequencial Único) do documento do contrato.\nUsado para rastreamento em ambas as estratégias (GIRO e ORIGINATOR_MANAGED); na ORIGINATOR_MANAGED também para referência no upload do documento assinado.\n"},"documentStatus":{"type":"string","enum":["PENDING","GENERATED","PENDING_SIGNATURE","SIGNATURE_PENDING_RETRY","SIGNED","REJECTED","EXPIRED","CANCELLED","FAILED","PROCESSED"],"description":"Status do documento do contrato (DocumentStatus).\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando geração do PDF |\n| GENERATED | PDF gerado, aguardando assinatura/upload |\n| PENDING_SIGNATURE | Aguardando assinatura |\n| SIGNATURE_PENDING_RETRY | Reenvio de link de assinatura em andamento |\n| SIGNED | Documento assinado recebido |\n| REJECTED | Documento rejeitado |\n| EXPIRED | Documento/link expirado |\n| CANCELLED | Documento cancelado |\n| FAILED | Falha na geração do documento |\n| PROCESSED | Documento processado |\n"},"rejectionReason":{"type":"string","nullable":true,"description":"Motivo da pendência de **desembolso**, em texto livre destinado a leitura humana.\n\nPreenchido por dois eventos do GTBanker, e apenas por eles:\n| Evento GTBanker | Webhook correspondente | Conteúdo |\n|-----------------|------------------------|----------|\n| `REVISAO_DESEMBOLSO` | `PAYMENT_REVISION` | `Revisão de conta de desembolso necessária - Ticket: <ticket>` |\n| `FALHA_DESEMBOLSO` | `PAYMENT_FAILURE` | `Falha no pagamento - Código: <codigo> - <mensagem>` |\n\nNesses dois casos o contrato permanece em `FORMALIZED` — o status não muda.\n\nO contrato também registra internamente falhas de formalização e de geração de documento,\nmas essas **não são expostas** neste campo: são diagnóstico de plataforma e chegam como\n`null` aqui. Um contrato `CANCELLED` por falha de geração de documento, portanto, tem\n`rejectionReason` nulo — para cancelamento, veja `cancelReason`.\n\nO campo é **limpo** quando o desembolso é concluído com sucesso (`PAYMENT_SUCCESS`), então\num contrato `COMPLETED` não carrega pendência antiga.\n\nTrate como **texto opaco para exibição**: o formato não faz parte do contrato e pode mudar\nsem aviso. Para lógica de negócio, use o payload do webhook, que traz `ticket`, `codigo` e\n`mensagem` em campos separados.\n\n`null` enquanto não houver pendência de desembolso.\n"},"cancelReason":{"type":"string","nullable":true,"description":"Motivo do cancelamento do contrato, em texto livre destinado a leitura humana.\n\nPreenchido quando o contrato vai a `CANCELLED` por cancelamento do trabalhador\n(`Cancelado pelo funcionário`) ou por exclusão da averbação, caso em que traz o motivo da\ndesaverbação. Complementa `rejectionReason`, que cobre apenas pendência de desembolso.\n\nTrate como **texto opaco para exibição**. `null` enquanto o contrato não for cancelado.\n"},"suppressNotification":{"type":"boolean","description":"Indica se a notificação WhatsApp ao assinador foi suprimida (URL entregue via webhook ao originador)."},"signatureExpirationDate":{"type":"string","format":"date","nullable":true,"description":"Data limite de assinatura informada na criação do contrato. `null` quando o originador não\ninformou — nesse caso vale o padrão do provedor de assinatura. Devolve o que foi pedido, não\no prazo efetivo, que só é resolvido quando o link é gerado.\n"},"currentBond":{"description":"Vínculo em que o contrato está agora: o destino da migração automática mais recente ou, sem\nmigração, o vínculo em que o contrato foi averbado. `null` quando a proposta não tem vínculo.\n","type":"object","properties":{"registrationNumber":{"type":"string","maxLength":100,"description":"Matrícula do trabalhador no empregador."},"employerRegistrationTypeCode":{"type":"integer","description":"Tipo de inscrição do empregador (1 = CNPJ, 2 = CPF)."},"employerRegistrationNumber":{"type":"string","maxLength":20,"description":"Inscrição do empregador como a Dataprev a identifica: raiz do CNPJ com 8 dígitos ou CPF com\n11. Para o documento completo use `employerTaxId`.\n"},"employerTaxId":{"type":"string","description":"Documento completo do empregador, sem máscara: CPF com 11 dígitos ou CNPJ com 14. Quando só\nse tem a raiz do CNPJ, o valor é o da **matriz** (raiz + filial `0001` + dígitos\nverificadores), que pode não ser o estabelecimento onde o trabalhador está lotado. Ausente\nquando não é possível afirmar um documento válido.\n"},"employerName":{"type":"string","maxLength":200}}}}}}}},"400":{"description":"Dados inválidos, corpo ilegível, regra de negócio ou CET acima do teto.","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":"Proposta não encontrada 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":"Número de contrato repetido, proposta já convertida, ou `Idempotency-Key` 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":"Regra de negócio sobre o contrato.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}},"429":{"description":"Mais de 75 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

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