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
proposalPublicId
path
string (uuid)
Sim
Identificador público da proposta que originará o contrato
O número de parcelas vem da proposta.
Corpo
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
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
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
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.
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.
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.
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.
JWT token fornecido pelo administrador
Identificador público da proposta
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 do contrato. Informe pix ou bankAccount (exatamente um) para desembolso.
Valor principal do contrato em reais (decimal com 2 casas decimais).
Data da contratação da operação (yyyy-MM-dd). Não pode ser no passado.
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.
^\d{8}$Data do primeiro vencimento. Deve respeitar as regras de carência e calendário da operação. Não pode ser no passado.
Data prevista para vencimento da última parcela. Não pode ser no passado.
URL de redirecionamento após o fluxo de assinatura digital. Apenas scheme http/https aceito.
^$|^https?://.*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.
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.
Nome do atendente ou vendedor responsável pela venda. Opcional.
CPF do atendente ou vendedor responsável. Opcional.
Contrato criado com sucesso
Identificador público do contrato. Pode vir omitido (ausente no JSON) em contratos antigos.
0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02Nú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
GTAB12CD34EFNú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.
00345678Identificador 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.
1GT00345678Identificador público do trabalhador (16 caracteres Base64 URL-safe).
Kj8mP2xQ9nR4sT6vCiclo de vida do 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 |
CREATEDValores possíveis: Situação da averbação no convênio.
| 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 |
PENDINGValores possíveis: Protocolo retornado pelo provedor de averbação, quando disponível.
Valor principal do contrato em reais (decimal com 2 casas decimais).
5750Quantidade de parcelas definida no contrato.
12Data de contratação (yyyy-MM-dd).
2024-02-01Data de vencimento da primeira parcela.
2024-04-28Data de vencimento da última parcela.
2025-03-28Data e hora em que o contrato foi assinado (UTC).
Data e hora em que a formalização foi concluída (UTC).
Data e hora de liquidação/desembolso do contrato (UTC).
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.
Data e hora de confirmação da averbação (UTC).
Valor total de juros da operação em reais (decimal com 2 casas decimais).
1250Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places).
7125.36Taxa de juros mensal em percentual (decimal com 4 casas decimais).
1.99Custo efetivo mensal (CET mensal) em percentual (decimal com 4 casas decimais).
2.15Custo efetivo anual (CET anual) em percentual (decimal com 4 casas decimais).
28.97Valor líquido desembolsado ao trabalhador em reais (decimal com 2 casas decimais).
4800Valor do seguro prestamista em reais (decimal com 2 casas decimais).
87.3Valor do IOF incidente na operação em reais (decimal com 2 casas decimais).
45.2Valor da TAC (Taxa de Abertura de Crédito) em reais (decimal com 2 casas decimais).
0Nome do atendente ou vendedor responsável pela venda.
Maria AtendenteCPF do atendente ou vendedor responsável.
98765432100Data e hora de criação do contrato no sistema (UTC).
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.
1234567890123456789Status do documento do contrato (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 |
Motivo da pendência de desembolso, em texto livre destinado a leitura humana.
Preenchido por dois eventos do GTBanker, e apenas por eles:
| Evento GTBanker | Webhook correspondente | Conteúdo |
|---|---|---|
REVISAO_DESEMBOLSO | PAYMENT_REVISION | Revisão de conta de desembolso necessária - Ticket: <ticket> |
FALHA_DESEMBOLSO | PAYMENT_FAILURE | Falha 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.
Falha no pagamento - Código: FALHA_GENERICA - Saldo insuficiente na conta de origemMotivo 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.
Cancelado pelo funcionárioIndica se a notificação WhatsApp ao assinador foi suprimida (URL entregue via webhook ao originador).
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.
Dados inválidos, corpo ilegível, regra de negócio ou CET acima do teto.
Não autenticado
Permissão insuficiente
Proposta não encontrada ou de outro originador.
Número de contrato repetido, proposta já convertida, ou Idempotency-Key em processamento.
Regra de negócio sobre o contrato.
Janela de suspensão da Dataprev aberta (virada de competência). A operação não foi
registrada — reenvie depois de windowEnd.
Onde olhar para reagendar: o header Retry-After traz os segundos que faltam (é sempre
delta-seconds, nunca HTTP-date) e o corpo traz windowEnd como date-time. Use um dos dois —
não faça backoff exponencial, a volta tem hora marcada.
Mais de 75 requisições por segundo. Aguarde o header Retry-After e reenvie com nova Idempotency-Key — com a mesma chave, o 429 gravado é repetido.
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