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

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 GET

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

A submissão (201) confirma apenas que o contrato foi recebido. O contrato ainda passa por averbação, envio ao provedor e formalização — acompanhe esses marcos via webhook ou consultando o GET /api/v1/fgts/contracts/{contractNumber}.

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

Situação
Seção
Endpoint

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

Operação
Método e Path
Descriçã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

Operação
Método e Path
Descrição

POST /api/v1/fgts/contracts/{contractNumber}/reserve-cancellations

Desistência ou quitação antecipada de contrato vigente

GET /api/v1/fgts/operations/{requestId}

Acompanha a solicitação de encerramento

Entenda o ciclo completo em Fluxo de formalização.

Atualizado