> 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/buscar-contrato-por-request-number.md).

# Buscar Contrato por Request Number ou Número da CCB

Retorna o contrato pelo `requestNumber` ou pelo número da CCB (`ccbNumber`, o `contractNumber` da resposta). Os dois endpoints devolvem o mesmo corpo e os mesmos erros.

## Request

`GET /api/v1/originator/contracts/by-request-number/{requestNumber}`

`GET /api/v1/originator/contracts/ccb/{ccbNumber}`

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

### Parâmetros

| Endpoint                                          | Parâmetro       | Local | Tipo               | Obrigatório | Descrição                                                      |
| ------------------------------------------------- | --------------- | ----- | ------------------ | ----------- | -------------------------------------------------------------- |
| `.../contracts/by-request-number/{requestNumber}` | `requestNumber` | path  | `string`           | Sim         | Número da requisição do contrato. Ex. `GTAB12CD34EF`           |
| `.../contracts/ccb/{ccbNumber}`                   | `ccbNumber`     | path  | `string` (máx. 50) | Sim         | Número da CCB — o `contractNumber` da resposta. Ex. `00345678` |

## Response

| Campo                     | Tipo                                 | Descrição                                                                                                                                                                                                                                                         |
| ------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicId`                | `string (uuid)`                      | Identificador público do contrato                                                                                                                                                                                                                                 |
| `requestNumber`           | `string`                             | Número da requisição (máx. 36). Contratos novos usam o mesmo valor do `publicId`; antigos, `GT` + 10 alfanuméricos maiúsculos (ex. `GTAB12CD34EF`)                                                                                                                |
| `contractNumber`          | `string`                             | Número da CCB (8 dígitos com zero à esquerda). Gerado pela Giro, ou informado pelo originador na criação quando a numeração é `ORIGINATOR_PROVIDED`                                                                                                               |
| `employeePublicId`        | `string`                             | Identificador público do trabalhador (16 caracteres Base64 URL-safe)                                                                                                                                                                                              |
| `proposal`                | `object`                             | Proposta que originou o contrato, com as parcelas — ver objeto `proposal`                                                                                                                                                                                         |
| `status`                  | `string` (enum)                      | Ciclo de vida do contrato — ver valores abaixo                                                                                                                                                                                                                    |
| `endorsementStatus`       | `string` (enum)                      | Situação da averbação — ver valores abaixo                                                                                                                                                                                                                        |
| `endorsementProtocol`     | `string`                             | Protocolo da averbação, quando disponível                                                                                                                                                                                                                         |
| `contractAmount`          | `number`                             | Valor principal do contrato (R$, 2 casas)                                                                                                                                                                                                                         |
| `installments`            | `integer`                            | Quantidade de parcelas definida no contrato                                                                                                                                                                                                                       |
| `contractDate`            | `string` (`date`)                    | Data de contratação (`yyyy-MM-dd`)                                                                                                                                                                                                                                |
| `firstInstallmentDueDate` | `string` (`date`)                    | Data de vencimento da primeira parcela                                                                                                                                                                                                                            |
| `lastInstallmentDueDate`  | `string` (`date`)                    | Data de vencimento da última parcela                                                                                                                                                                                                                              |
| `signedAt`                | `string` (`date-time`)               | Data e hora em que o contrato foi assinado (UTC)                                                                                                                                                                                                                  |
| `formalizedAt`            | `string` (`date-time`)               | Data e hora em que a formalização foi concluída (UTC)                                                                                                                                                                                                             |
| `paidAt`                  | `string` (`date-time`)               | Data e hora de liquidação/desembolso do contrato (UTC)                                                                                                                                                                                                            |
| `paymentReceiptUrl`       | `string` (`uri`, máx. 512, nullable) | Link do comprovante do desembolso emitido pelo banco liquidante. Aparece depois do pagamento, inclusive quando o desembolso chega após um cancelamento. **É uma credencial:** quem tem o link abre o comprovante sem autenticação — não publique nem grave em log |
| `endorsedAt`              | `string` (`date-time`)               | Data e hora de confirmação da averbação (UTC)                                                                                                                                                                                                                     |
| `totalInterestAmount`     | `number`                             | Valor total de juros da operação (R$, 2 casas)                                                                                                                                                                                                                    |
| `debitAmount`             | `number`                             | Total a pagar (`installmentCount` × `installmentAmount`, R$, 2 casas)                                                                                                                                                                                             |
| `monthlyInterestRate`     | `number`                             | Taxa de juros mensal (%, 4 casas)                                                                                                                                                                                                                                 |
| `monthlyEffectiveCost`    | `number`                             | Custo efetivo mensal (CET mensal) (%, 4 casas)                                                                                                                                                                                                                    |
| `annualEffectiveCost`     | `number`                             | Custo efetivo anual (CET anual) (%, 4 casas)                                                                                                                                                                                                                      |
| `disbursementAmount`      | `number`                             | Valor líquido desembolsado ao trabalhador (R$, 2 casas)                                                                                                                                                                                                           |
| `insuranceAmount`         | `number`                             | Valor do seguro prestamista (R$, 2 casas)                                                                                                                                                                                                                         |
| `iofAmount`               | `number`                             | Valor do IOF incidente na operação (R$, 2 casas)                                                                                                                                                                                                                  |
| `tacAmount`               | `number`                             | Valor da TAC (Taxa de Abertura de Crédito, R$, 2 casas)                                                                                                                                                                                                           |
| `attendantName`           | `string`                             | Nome do atendente ou vendedor responsável pela venda (máx. 150)                                                                                                                                                                                                   |
| `attendantCpf`            | `string`                             | CPF do atendente ou vendedor responsável (máx. 14)                                                                                                                                                                                                                |
| `bankInfo`                | `object`                             | Conta de desembolso — ver objeto `bankInfo`                                                                                                                                                                                                                       |
| `address`                 | `object`                             | Endereço do trabalhador — ver objeto `address`                                                                                                                                                                                                                    |
| `createdDate`             | `string` (`date-time`)               | Data e hora de criação do contrato (UTC)                                                                                                                                                                                                                          |
| `nsu`                     | `string`                             | NSU do documento do contrato (máx. 19), para rastreio                                                                                                                                                                                                             |
| `documentStatus`          | `string` (enum)                      | Status do documento — ver valores abaixo                                                                                                                                                                                                                          |
| `suppressNotification`    | `boolean`                            | `true` quando o WhatsApp ao trabalhador foi suprimido (link só no webhook)                                                                                                                                                                                        |
| `signatureExpirationDate` | `string` (`date`, nullable)          | Data limite de assinatura informada na criação. `null`: vale o padrão de 7 dias. Ver [Prazo de assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/criar-contrato.md#prazo-de-assinatura)                                    |
| `rejectionReason`         | `string` (nullable)                  | Motivo da pendência de desembolso, em texto livre. Preenchido só em `PAYMENT_REVISION` / `PAYMENT_FAILURE` ([eventos](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md)); `null` nos demais casos, inclusive `CANCELLED`       |
| `cancelReason`            | `string` (nullable)                  | Motivo do cancelamento, em texto livre. `null` se o contrato não foi cancelado                                                                                                                                                                                    |

Valores de `status` (contrato):

| Valor        | Significado                            |
| ------------ | -------------------------------------- |
| `CREATED`    | Contrato criado, aguardando assinatura |
| `SIGNED`     | Assinado pelo trabalhador              |
| `ENDORSED`   | Averbação consignada confirmada        |
| `FORMALIZED` | Formalizado no sistema de pagamento    |
| `COMPLETED`  | Operação concluída (desembolsado)      |
| `CANCELLED`  | Cancelado                              |

Valores de `endorsementStatus`:

| Valor        | Significado                                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING`    | Aguardando averbação                                                                                                             |
| `PROCESSING` | Em processamento no convênio                                                                                                     |
| `ENDORSED`   | Averbação confirmada                                                                                                             |
| `FAILED`     | Falha na averbação                                                                                                               |
| `RETRYING`   | Nova tentativa em andamento                                                                                                      |
| `EXCLUDING`  | [Desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desaverbar-contrato.md) em andamento |
| `EXCLUDED`   | Desaverbação concluída                                                                                                           |

Valores de `documentStatus`:

| Valor                     | Significado                                |
| ------------------------- | ------------------------------------------ |
| `PENDING`                 | Aguardando geração do PDF                  |
| `GENERATED`               | PDF gerado, aguardando assinatura/upload   |
| `PENDING_SIGNATURE`       | Aguardando assinatura                      |
| `SIGNATURE_PENDING_RETRY` | Reenvio de link de assinatura em andamento |
| `SIGNED`                  | Documento assinado recebido                |
| `REJECTED`                | Documento rejeitado                        |
| `EXPIRED`                 | Documento/link expirado                    |
| `CANCELLED`               | Documento cancelado                        |
| `FAILED`                  | Falha na geração do documento              |
| `PROCESSED`               | Documento processado                       |

### Objeto `proposal`

| Campo                  | Tipo                   | Descrição                                                                                  |
| ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------ |
| `publicId`             | `string`               | Identificador público da proposta                                                          |
| `employeePublicId`     | `string`               | Identificador público do trabalhador (16 caracteres Base64 URL-safe)                       |
| `simulationPublicId`   | `string (uuid)`        | Identificador da simulação que originou a proposta                                         |
| `loanAmount`           | `number`               | Valor do empréstimo (R$, 2 casas)                                                          |
| `financedAmount`       | `number`               | Valor financiado (R$, 2 casas)                                                             |
| `totalInterestAmount`  | `number`               | Juros totais (R$, 2 casas)                                                                 |
| `debitAmount`          | `number`               | Total a pagar (`installmentCount` × `installmentAmount`, R$, 2 casas)                      |
| `monthlyInterestRate`  | `number`               | Taxa mensal (%, 4 casas)                                                                   |
| `monthlyEffectiveCost` | `number`               | CET mensal (%, 4 casas)                                                                    |
| `annualEffectiveCost`  | `number`               | CET anual (%, 4 casas)                                                                     |
| `disbursementAmount`   | `number`               | Valor a desembolsar (R$, 2 casas)                                                          |
| `insuranceAmount`      | `number`               | Seguro (R$, 2 casas)                                                                       |
| `iofAmount`            | `number`               | IOF (R$, 2 casas)                                                                          |
| `tacAmount`            | `number`               | TAC (R$, 2 casas)                                                                          |
| `outstandingBalance`   | `number`               | Saldo devedor (R$, 2 casas)                                                                |
| `installmentCount`     | `integer`              | Quantidade de parcelas                                                                     |
| `dueDate`              | `string` (`date`)      | Data de vencimento de referência (`yyyy-MM-dd`)                                            |
| `status`               | `string` (enum)        | Status da proposta (`PENDING`, `ACCEPTED`, `REJECTED`, `EXPIRED`, `CONVERTED_TO_CONTRACT`) |
| `expiresAt`            | `string` (`date-time`) | Data e hora de expiração do prazo de aceite (UTC)                                          |
| `acceptedAt`           | `string` (`date-time`) | Data e hora do aceite pelo trabalhador (UTC), quando houver                                |
| `installments`         | `array`                | Parcelas — ver item de `proposal.installments`                                             |
| `createdDate`          | `string` (`date-time`) | Data e hora de criação da proposta (UTC)                                                   |

### Item de `proposal.installments`

| Campo                | Tipo              | Descrição                                     |
| -------------------- | ----------------- | --------------------------------------------- |
| `installmentNumber`  | `integer`         | Número da parcela (1-based)                   |
| `dueDate`            | `string` (`date`) | Data de vencimento da parcela                 |
| `installmentAmount`  | `number`          | Valor da parcela (desconto em folha) em reais |
| `amortizationAmount` | `number`          | Amortização (principal) da parcela em reais   |
| `interestAmount`     | `number`          | Juros da parcela em reais                     |
| `iofAmount`          | `number`          | IOF da parcela em reais                       |
| `feesAmount`         | `number`          | Taxas da parcela em reais                     |
| `outstandingBalance` | `number`          | Saldo devedor após a parcela em reais         |
| `daysToCompensate`   | `integer`         | Dias para compensação                         |

### Objeto `bankInfo`

| Campo         | Tipo     | Descrição                                      |
| ------------- | -------- | ---------------------------------------------- |
| `type`        | `string` | `PIX` ou `BANK_ACCOUNT`                        |
| `pix`         | `object` | Chave Pix, quando `type` = `PIX`               |
| `bankAccount` | `object` | Conta bancária, quando `type` = `BANK_ACCOUNT` |

### Objeto `bankInfo.pix`

| Campo     | Tipo     | Descrição         |
| --------- | -------- | ----------------- |
| `keyType` | `string` | Tipo da chave Pix |
| `key`     | `string` | Chave Pix         |

### Objeto `bankInfo.bankAccount`

| Campo           | Tipo     | Descrição         |
| --------------- | -------- | ----------------- |
| `bankCode`      | `string` | Código do banco   |
| `branchNumber`  | `string` | Agência           |
| `branchDigit`   | `string` | Dígito da agência |
| `accountNumber` | `string` | Número da conta   |
| `accountDigit`  | `string` | Dígito da conta   |
| `accountType`   | `string` | Tipo da conta     |

### Objeto `address`

| Campo          | Tipo     | Descrição   |
| -------------- | -------- | ----------- |
| `street`       | `string` | Logradouro  |
| `number`       | `string` | Número      |
| `complement`   | `string` | Complemento |
| `neighborhood` | `string` | Bairro      |
| `city`         | `string` | Cidade      |
| `state`        | `string` | UF          |
| `zipCode`      | `string` | CEP         |

## Exemplo

Consulta pelo `requestNumber`:

```http
GET /api/v1/originator/contracts/by-request-number/GTAB12CD34EF HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
```

Resposta `200`:

```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": 34.92,
    "installmentCount": 12,
    "dueDate": "2025-04-28",
    "status": "CONVERTED_TO_CONTRACT",
    "installments": [
      {
        "installmentNumber": 1,
        "dueDate": "2025-04-28",
        "installmentAmount": 593.78,
        "amortizationAmount": 481.46,
        "interestAmount": 112.32,
        "iofAmount": 15.9,
        "feesAmount": 0,
        "outstandingBalance": 6531.58,
        "daysToCompensate": 30
      },
      {
        "installmentNumber": 2,
        "dueDate": "2025-05-28",
        "installmentAmount": 593.78
      }
    ],
    "createdDate": "2025-01-15T10:00:00Z"
  },
  "status": "CREATED",
  "endorsementStatus": "PENDING",
  "contractAmount": 5000,
  "installments": 12,
  "contractDate": "2025-01-15",
  "firstInstallmentDueDate": "2025-04-28",
  "lastInstallmentDueDate": "2026-03-28",
  "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"
  },
  "suppressNotification": false,
  "rejectionReason": null,
  "cancelReason": null,
  "createdDate": "2025-01-15T10:00:00Z"
}
```

Pelo número da CCB, mesmo contrato:

```http
GET /api/v1/originator/contracts/ccb/00345678 HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
```

Resposta idêntica à anterior.

## Erros

| Código | `errorCode` | Situação                                       |
| ------ | ----------- | ---------------------------------------------- |
| 404    | —           | Contrato não encontrado ou de outro originador |
| 429    | —           | Mais de 100 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).

## Buscar Contrato por Número da Requisição

> Retorna os detalhes do contrato a partir do requestNumber.

```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/contracts/by-request-number/{requestNumber}":{"get":{"summary":"Buscar Contrato por Número da Requisição","description":"Retorna os detalhes do contrato a partir do requestNumber.","tags":["Contracts"],"parameters":[{"name":"requestNumber","in":"path","required":true,"description":"Número da requisição do contrato","schema":{"type":"string"}}],"responses":{"200":{"description":"Contrato retornado 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}}}}}}}},"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":"Contrato 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**."}}}}}}}},"429":{"description":"Mais de 100 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

## Buscar Contrato por Número da CCB

> Retorna os detalhes do contrato a partir do número da CCB (contract\_number).

```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/contracts/ccb/{ccbNumber}":{"get":{"summary":"Buscar Contrato por Número da CCB","description":"Retorna os detalhes do contrato a partir do número da CCB (contract_number).","tags":["Contracts"],"parameters":[{"name":"ccbNumber","in":"path","required":true,"description":"Número da CCB do contrato","schema":{"type":"string"}}],"responses":{"200":{"description":"Contrato retornado 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}}}}}}}},"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":"Contrato não encontrado","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/>" %}
