Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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.

Prazo de assinatura

Vale para a estratégia GIRO. Na assinatura pelo originador, 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 não estende o prazo.

Response

201 Created com o contrato no mesmo formato de Buscar Contrato. Em CREATED, rejectionReason e cancelReason são null.

Próximo passo, conforme a estratégia de assinatura:

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

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

Exemplo

Resposta 201:

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)

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.

Criar Contrato

post
/api/v1/originator/proposals/{proposalPublicId}/contracts

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.

Autorizações
AuthorizationstringObrigatório

JWT token fornecido pelo administrador

Parâmetros de rota
proposalPublicIdstring · máx: 36Obrigatório

Identificador público da proposta

Parâmetros de cabeçalho
Idempotency-Keystring · máx: 255Opcional

Chave de idempotência para evitar duplicação em retentativas. Se fornecida, o servidor retornará a mesma resposta para chamadas com a mesma chave do mesmo originador. A chave é retida por 7 dias. Depois desse prazo ela é expurgada e uma requisição com a mesma chave é tratada como nova, sendo reprocessada.

Corpo

Corpo do contrato. Informe pix ou bankAccount (exatamente um) para desembolso.

contractAmountnumber · decimal · mín: 0.01Obrigatório

Valor principal do contrato em reais (decimal com 2 casas decimais).

contractDatestring · dateObrigatório

Data da contratação da operação (yyyy-MM-dd). Não pode ser no passado.

contractNumberstring · mín: 8 · máx: 8Opcional

Número do contrato informado pelo originador. Obrigatório quando o originador está configurado com estratégia ORIGINATOR_PROVIDED (contractNumberStrategy). Deve ter exatamente 8 dígitos numéricos. Ignorado quando a estratégia é SYSTEM_GENERATED.

Pattern: ^\d{8}$
firstInstallmentDueDatestring · dateOpcional

Data do primeiro vencimento. Deve respeitar as regras de carência e calendário da operação. Não pode ser no passado.

lastInstallmentDueDatestring · dateOpcional

Data prevista para vencimento da última parcela. Não pode ser no passado.

redirectUrlstring · máx: 1000Opcional

URL de redirecionamento após o fluxo de assinatura digital. Apenas scheme http/https aceito.

Pattern: ^$|^https?://.*
suppressNotificationbooleanOpcional

Quando true, a plataforma não envia notificação WhatsApp ao assinador. A URL de assinatura é entregue via webhook CONTRACT_DOCUMENT_READY para o originador gerenciar. Quando ausente ou false, o comportamento padrão (envio de notificação) é mantido.

signatureExpirationDatestring · dateOpcional

Data limite para assinatura do contrato (yyyy-MM-dd). Não pode ser no passado. Omitido, vale o padrão de 7 dias.

O prazo é repassado ao provedor de assinatura, que é quem faz o link expirar ao fim desse dia. Ele conta da geração do link, não da criação do contrato — este 201 ainda não confirma o prazo.

Vencido o prazo, a plataforma leva o documentStatus a EXPIRED, cancela o contrato (status = CANCELLED) e entrega o webhook CONTRACT_SIGNING_FAILED com errorCode SIGNATURE_EXPIRED — o mesmo desfecho das demais falhas de assinatura. A verificação é periódica, então há defasagem de alguns minutos entre o vencimento e a mudança de status.

Na assinatura gerenciada pelo originador o campo é aceito e devolvido, mas quem controla o prazo do link é o próprio originador.

Quando ausente, aplica-se o padrão do provedor — hoje 7 dias, contados a partir do momento em que o link é gerado, e não da criação do contrato (entre as duas coisas há a geração do PDF). Por isso, se a data informada já tiver passado quando o link for gerado, ela é encurtada para o fim do dia corrente, nunca estendida para o padrão.

Reenviar o link (POST /contracts/{publicId}/resend) não estende este prazo.

Aplica-se apenas à assinatura gerenciada pela Giro. Em contratos com assinatura delegada ao originador, o campo é aceito e registrado, mas quem controla o prazo do link é o próprio originador.

attendantNamestring · máx: 150Opcional

Nome do atendente ou vendedor responsável pela venda. Opcional.

attendantCpfstring · máx: 14Opcional

CPF do atendente ou vendedor responsável. Opcional.

Respostas
201

Contrato criado com sucesso

application/json
publicIdstring · máx: 36Opcional

Identificador público do contrato. Pode vir omitido (ausente no JSON) em contratos antigos.

Example: 0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02
requestNumberstring · máx: 36Opcional

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

Example: GTAB12CD34EF
contractNumberstringOpcional

Número do contrato (8 dígitos com zero à esquerda). Por padrão (estratégia GIRO), o número é gerado automaticamente pela plataforma. Na estratégia ORIGINATOR_MANAGED, o originador pode informar o número no momento da criação do contrato.

Example: 00345678
dataprevContractNumberstring · máx: 30 · anulávelOpcional

Identificador do contrato perante o Dataprev — corresponde ao campo numeroContrato trocado com o Dataprev em averbação, alteração, suspensão, reativação e exclusão. Use este valor para correlacionar o contrato na GTPayroll com os registros do Dataprev.

Trate como string opaca: o formato não faz parte do contrato e pode mudar sem aviso. Não derive nem reconstrua o valor a partir de outros campos.

Pode vir null em contratos legados criados antes da introdução do campo.

Example: 1GT00345678
employeePublicIdstringOpcional

Identificador público do trabalhador (16 caracteres Base64 URL-safe).

Example: Kj8mP2xQ9nR4sT6v
statusstring · enumOpcional

Ciclo de vida do contrato.

ValorSignificado
CREATEDContrato criado, aguardando assinatura
SIGNEDAssinado pelo trabalhador
ENDORSEDAverbação consignada confirmada
FORMALIZEDFormalizado no sistema de pagamento
COMPLETEDOperação concluída (desembolsado)
CANCELLEDCancelado
Example: CREATEDValores possíveis:
endorsementStatusstring · enumOpcional

Situação da averbação no convênio.

ValorSignificado
PENDINGAguardando averbação
PROCESSINGEm processamento no convênio
ENDORSEDAverbação confirmada
FAILEDFalha na averbação
RETRYINGNova tentativa em andamento
Example: PENDINGValores possíveis:
endorsementProtocolstringOpcional

Protocolo retornado pelo provedor de averbação, quando disponível.

contractAmountnumber · decimalOpcional

Valor principal do contrato em reais (decimal com 2 casas decimais).

Example: 5750
installmentsintegerOpcional

Quantidade de parcelas definida no contrato.

Example: 12
contractDatestring · dateOpcional

Data de contratação (yyyy-MM-dd).

Example: 2024-02-01
firstInstallmentDueDatestring · dateOpcional

Data de vencimento da primeira parcela.

Example: 2024-04-28
lastInstallmentDueDatestring · dateOpcional

Data de vencimento da última parcela.

Example: 2025-03-28
signedAtstring · date-timeOpcional

Data e hora em que o contrato foi assinado (UTC).

formalizedAtstring · date-timeOpcional

Data e hora em que a formalização foi concluída (UTC).

paidAtstring · date-timeOpcional

Data e hora de liquidação/desembolso do contrato (UTC).

paymentReceiptUrlstring · uri · máx: 512 · anulávelOpcional

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.

endorsedAtstring · date-timeOpcional

Data e hora de confirmação da averbação (UTC).

totalInterestAmountnumber · decimalOpcional

Valor total de juros da operação em reais (decimal com 2 casas decimais).

Example: 1250
debitAmountnumber · decimalOpcional

Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places).

Example: 7125.36
monthlyInterestRatenumber · decimalOpcional

Taxa de juros mensal em percentual (decimal com 4 casas decimais).

Example: 1.99
monthlyEffectiveCostnumber · decimalOpcional

Custo efetivo mensal (CET mensal) em percentual (decimal com 4 casas decimais).

Example: 2.15
annualEffectiveCostnumber · decimalOpcional

Custo efetivo anual (CET anual) em percentual (decimal com 4 casas decimais).

Example: 28.97
disbursementAmountnumber · decimalOpcional

Valor líquido desembolsado ao trabalhador em reais (decimal com 2 casas decimais).

Example: 4800
insuranceAmountnumber · decimalOpcional

Valor do seguro prestamista em reais (decimal com 2 casas decimais).

Example: 87.3
iofAmountnumber · decimalOpcional

Valor do IOF incidente na operação em reais (decimal com 2 casas decimais).

Example: 45.2
tacAmountnumber · decimalOpcional

Valor da TAC (Taxa de Abertura de Crédito) em reais (decimal com 2 casas decimais).

Example: 0
attendantNamestring · máx: 150Opcional

Nome do atendente ou vendedor responsável pela venda.

Example: Maria Atendente
attendantCpfstring · máx: 14Opcional

CPF do atendente ou vendedor responsável.

Example: 98765432100
createdDatestring · date-timeOpcional

Data e hora de criação do contrato no sistema (UTC).

nsustring · máx: 19Opcional

NSU (Número Sequencial Único) do documento do contrato. Usado para rastreamento em ambas as estratégias (GIRO e ORIGINATOR_MANAGED); na ORIGINATOR_MANAGED também para referência no upload do documento assinado.

Example: 1234567890123456789
documentStatusstring · enumOpcional

Status do documento do contrato (DocumentStatus).

ValorSignificado
PENDINGAguardando geração do PDF
GENERATEDPDF gerado, aguardando assinatura/upload
PENDING_SIGNATUREAguardando assinatura
SIGNATURE_PENDING_RETRYReenvio de link de assinatura em andamento
SIGNEDDocumento assinado recebido
REJECTEDDocumento rejeitado
EXPIREDDocumento/link expirado
CANCELLEDDocumento cancelado
FAILEDFalha na geração do documento
PROCESSEDDocumento processado
Valores possíveis:
rejectionReasonstring · anulávelOpcional

Motivo da pendência de desembolso, em texto livre destinado a leitura humana.

Preenchido por dois eventos do GTBanker, e apenas por eles:

Evento GTBankerWebhook correspondenteConteúdo
REVISAO_DESEMBOLSOPAYMENT_REVISIONRevisão de conta de desembolso necessária - Ticket: <ticket>
FALHA_DESEMBOLSOPAYMENT_FAILUREFalha no pagamento - Código: <codigo> - <mensagem>

Nesses dois casos o contrato permanece em FORMALIZED — o status não muda.

O contrato também registra internamente falhas de formalização e de geração de documento, mas essas não são expostas neste campo: são diagnóstico de plataforma e chegam como null aqui. Um contrato CANCELLED por falha de geração de documento, portanto, tem rejectionReason nulo — para cancelamento, veja cancelReason.

O campo é limpo quando o desembolso é concluído com sucesso (PAYMENT_SUCCESS), então um contrato COMPLETED não carrega pendência antiga.

Trate como texto opaco para exibição: o formato não faz parte do contrato e pode mudar sem aviso. Para lógica de negócio, use o payload do webhook, que traz ticket, codigo e mensagem em campos separados.

null enquanto não houver pendência de desembolso.

Example: Falha no pagamento - Código: FALHA_GENERICA - Saldo insuficiente na conta de origem
cancelReasonstring · anulávelOpcional

Motivo do cancelamento do contrato, em texto livre destinado a leitura humana.

Preenchido quando o contrato vai a CANCELLED por cancelamento do trabalhador (Cancelado pelo funcionário) ou por exclusão da averbação, caso em que traz o motivo da desaverbação. Complementa rejectionReason, que cobre apenas pendência de desembolso.

Trate como texto opaco para exibição. null enquanto o contrato não for cancelado.

Example: Cancelado pelo funcionário
suppressNotificationbooleanOpcional

Indica se a notificação WhatsApp ao assinador foi suprimida (URL entregue via webhook ao originador).

signatureExpirationDatestring · date · anulávelOpcional

Data limite de assinatura informada na criação do contrato. null quando o originador não informou — nesse caso vale o padrão do provedor de assinatura. Devolve o que foi pedido, não o prazo efetivo, que só é resolvido quando o link é gerado.

post/api/v1/originator/proposals/{proposalPublicId}/contracts
POST /api/v1/originator/proposals/{proposalPublicId}/contracts HTTP/1.1
Host: ingress.gtpayroll.staging.giro.tech
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 429

{
  "contractAmount": 5750,
  "contractDate": "2024-02-01",
  "firstInstallmentDueDate": "2024-04-28",
  "lastInstallmentDueDate": "2025-03-28",
  "attendantName": "Maria Atendente",
  "attendantCpf": "98765432100",
  "signatureExpirationDate": "2026-09-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"
  }
}
{
  "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02",
  "requestNumber": "GTAB12CD34EF",
  "contractNumber": "00345678",
  "dataprevContractNumber": "1GT00345678",
  "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": "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",
  "suppressNotification": false,
  "signatureExpirationDate": "2026-09-18",
  "rejectionReason": null,
  "cancelReason": null,
  "createdDate": "2025-01-15T10:00:00Z"
}

Atualizado