Contratos (Formalização)
Nesta seção o originador submete um contrato de empréstimo com garantia FGTS (uma CCB — Cédula de Crédito Bancário) e a Giro.Tech cuida da formalização: averba a garantia na Caixa, envia o contrato ao provedor bancário e acompanha o pagamento ao tomador.
Modelo
Submeter contrato → 201 { contractNumber, status } → (formalização) → webhook (source: CONTRACT) OU polling do GETA submissão é síncrona: a API responde 201 com o contractNumber gerado (sequencial por originador). Todo o andamento posterior é assíncrono — averbação na Caixa, envio ao provedor, formalização e pagamento — e chega ao originador por webhook (source = CONTRACT) ou por polling do GET.
Modo A vs Modo B
O envio do PDF assinado da CCB define o modo de entrada:
Modo
Como
status inicial
Modo A
O PDF assinado vai junto na submissão (campo signedDocumentBase64).
RECEIVED
Modo B
O contrato é submetido sem o PDF; o documento assinado é enviado depois em POST .../documents.
AWAITING_SIGNED_DOCUMENT
No Modo B, o contrato fica em AWAITING_SIGNED_DOCUMENT até o documento assinado ser anexado, quando então segue direto para PENDING_ENDORSEMENT e a formalização prossegue. Se a geração da CCB falhar, o contrato vai para DOCUMENT_GENERATION_FAILED (webhook CONTRACT_DOCUMENT_GENERATION_FAILED). Esse estado não é terminal: se a geração for concluída depois — resultado atrasado ou geração refeita pelo suporte —, o contrato volta a AWAITING_SIGNED_DOCUMENT e o webhook CONTRACT_DOCUMENT_GENERATED é emitido.
Cancelamento vs encerramento
Contrato em formalização (pré-terminal)
DELETE /api/v1/fgts/contracts/{contractNumber}
Contrato já vigente — desistência ou quitação antecipada
POST .../reserve-cancellations
Formalização
POST /api/v1/fgts/contracts
Submete uma CCB para formalização (Modo A com PDF assinado, ou Modo B sem)
POST /api/v1/fgts/contracts/{contractNumber}/documents
Anexa o PDF assinado da CCB (fluxo Modo B)
GET /api/v1/fgts/contracts/{contractNumber}
Consulta o status e os marcos de formalização do contrato
POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries
Nova tentativa de averbação para contrato em ENDORSEMENT_REJECTED, reusando o mesmo reserveIdentifier. Teto de 3 retentativas; recusa por teto chega por webhook, não na resposta
POST /api/v1/fgts/contracts/{contractNumber}/payment-approval
Aprova manualmente o pagamento quando o gate está ativo (requiresPaymentApproval)
DELETE /api/v1/fgts/contracts/{contractNumber}
Cancela durante a formalização (pré-terminal)
PUT /api/v1/fgts/contracts/{contractNumber}/disbursement-account
Atualiza a conta de pagamento quando o provedor pede revisão
GET /api/v1/fgts/contracts/{contractNumber}/documents/template
URL temporária para baixar o documento da CCB gerado pela Giro ao final da formalização
GET /api/v1/fgts/contracts/{contractNumber}/documents/signed
URL temporária para baixar o PDF assinado que o originador enviou
Encerramento
POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations
Desistência ou quitação antecipada de contrato vigente
Entenda o ciclo completo em Fluxo de formalização.
Atualizado