Máquina de Estados da Operação de Crédito

Toda operação de crédito (CreditOperation) possui o campo status que reflete sua posição no ciclo de vida. O status é retornado em GET /credit-operations/{externalContractId} e define as ações permitidas na esteira.

Estados da Operação (`CreditOperationStatus`)

Status	Significado
`RECEIVED`	Operação criada e persistida com sucesso, aguardando aprovação.
`APPROVED`	Operação aprovada pela equipe ou parceiro, pronta para formalização de contrato.
`REJECTED`	Operação reprovada ou recusada — estado terminal.
`CONTRACT_REQUESTED`	Emissão eletrônica da minuta de contrato solicitada à esteira de documentos.
`CONTRACT_GENERATED`	Minuta de contrato gerada (ou recebida via upload externo), pronta para assinatura.
`CONTRACT_GENERATION_FAILED`	Falha na geração do contrato de crédito.
`CONTRACT_SIGNING_PENDING`	Assinatura eletrônica interna solicitada; aguardando assinatura do tomador.
`CONTRACT_SIGNED`	Contrato assinado com sucesso (via esteira eletrônica ou manifesto de fingerprint externo). Apto ao desembolso.
`DISBURSEMENT_REQUESTED`	Desembolso do crédito solicitado à plataforma bancária (SCD Core).
`DISBURSED`	Valor desembolsado com sucesso na conta bancária ou Pix do tomador — estado terminal de crédito.
`DISBURSEMENT_FAILED`	Falha reportada na liquidação do desembolso bancário.
`CANCELLED`	Operação cancelada pelo parceiro antes da liquidação — estado terminal.

Diagrama de Transições

stateDiagram-v2
    [*] --> RECEIVED: POST /credit-operations
    RECEIVED --> APPROVED: POST /approve
    RECEIVED --> REJECTED: Análise de Risco

    APPROVED --> CONTRACT_REQUESTED: POST /contract
    CONTRACT_REQUESTED --> CONTRACT_GENERATED: Sucesso
    CONTRACT_REQUESTED --> CONTRACT_GENERATION_FAILED: Falha

    APPROVED --> CONTRACT_GENERATED: POST /contract/upload (Externo)

    CONTRACT_GENERATED --> CONTRACT_SIGNING_PENDING: POST /contract/sign (Interno)
    CONTRACT_SIGNING_PENDING --> CONTRACT_SIGNED: Conclusão Assinatura

    CONTRACT_GENERATED --> CONTRACT_SIGNED: POST /contract/fingerprint (Externo)

    CONTRACT_SIGNED --> DISBURSEMENT_REQUESTED: POST /disbursement
    DISBURSEMENT_REQUESTED --> DISBURSED: Confirmação SCD Core
    DISBURSEMENT_REQUESTED --> DISBURSEMENT_FAILED: Falha SCD Core

    RECEIVED --> CANCELLED: POST /cancel
    APPROVED --> CANCELLED: POST /cancel
    CONTRACT_GENERATED --> CANCELLED: POST /cancel
    CONTRACT_SIGNED --> CANCELLED: POST /cancel

Regras de Bloqueio (HTTP 409 Conflict)

Cada endpoint de transição valida o estado antes de agir. Requisições fora de ordem resultam em erro 409 Conflict:

Gerar Contrato (POST .../contract ou legado /ccb): Exige status APPROVED. Utiliza as condições, signatários e vencimentos (firstPaymentDate e installments) já calculados e persistidos na criação da operação.
Upload de Minuta Externa (POST .../contract/upload): Exige status APPROVED ou CONTRACT_GENERATED.
Solicitar Assinatura Eletrônica (POST .../contract/sign ou legado /ccb/sign): Exige status CONTRACT_GENERATED.
Submeter Manifesto de Fingerprint (POST .../contract/fingerprint): Exige que a operação possua documento de contrato vinculado e esteja nos status CONTRACT_GENERATED ou CONTRACT_SIGNING_PENDING.
Solicitar Desembolso (POST .../disbursement): Exige status CONTRACT_SIGNED.
Cancelar (POST .../cancel): Permitido em qualquer estado não-terminal anterior ao desembolso; bloqueado se a operação já estiver DISBURSED.
Solicitar KYC (POST .../kyc): Executado uma única vez por operação; bloqueado em estados terminais (DISBURSED, REJECTED, CANCELLED).

Estados da Operação (CreditOperationStatus)

Diagrama de Transições

Regras de Bloqueio (HTTP 409 Conflict)

Estados da Operação (`CreditOperationStatus`)