Cessão de operações

POST /api/loan/ · multipart/form-data · Bearer JWT

1. Quando usar este fluxo

Use POST /api/loan/ quando você (originador, bancarizador ou outro integrador) precisa disponibilizar uma operação de crédito formalizada para aquisição pelo FIDC. O endpoint aceita o pacote de dados da operação e os arquivos de lastro em uma única requisição (multipart).

🚧

Lastro suportado hoje

Atualmente a criação de cessão aceita apenas lastro CCB (o type de cada backing_document na criação deve ser ccb) e product_type em personal_loan, financing ou cdc. Duplicata e contrato pré-pago estão no roadmap — confirme com a IORQ antes de integrar esses lastros.

📘

Princípio

A IORQ não dita quem chama o endpoint — pode ser o originador (quando ele detém o lastro juridicamente) ou o bancarizador (quando ele emite o lastro). O fluxo é o mesmo. Quem chama, neste guia, chamamos genericamente de integrador.

Lastros suportados

O product_type (personal_loan, financing ou cdc) diferencia o produto de crédito; o lastro é sempre a CCB. Outros lastros (duplicata, contrato pré-pago) estão no roadmap.

2. Atores envolvidos

3. Fluxo end-to-end

sequenceDiagram
    participant INT as Integrador
    participant IORQ as IORQ
    participant ADM as Administradora

    INT->>IORQ: POST /oauth2/token
    IORQ-->>INT: Bearer JWT (1h)

    loop Para cada operação
        INT->>IORQ: POST /api/loan/ (multipart: dados + lastro)
        IORQ-->>INT: 201 Created
        IORQ->>IORQ: Valida schema + arquivos
        IORQ->>IORQ: Aplica critérios de elegibilidade
        alt Aprovada
            IORQ->>INT: Webhook LOAN_UPDATE (status: approved)
            IORQ->>ADM: Sinaliza criação no estoque
        else Recusada
            IORQ->>INT: Webhook LOAN_UPDATE (status: rejected + reason)
        end
    end

    ADM->>ADM: Gera termo + coleta assinaturas + valida lastro
    ADM->>INT: Desembolso (TED)

4. Pré-requisitos

• Credenciais OAuth2 (client_id, client_secret) provisionadas pela IORQ
• fund_id do FIDC alvo provisionado pela IORQ
• Endpoint HTTPS público para receber webhooks (registrado via POST /webhook)
• Lastro formalizado

5. Passo a passo

5.1 Autenticar

Toda chamada à API IORQ exige um Bearer JWT obtido via POST /oauth2/token. O token tem validade de 1 hora — reutilize-o entre múltiplas chamadas no mesmo lote.

POST /oauth2/token · application/x-www-form-urlencoded

curl -X POST 'https://auth.iorq.com.br/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'grant_type=client_credentials'

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

5.2 Construir o payload da operação

O payload é serializado como string JSON no campo loan_data de um multipart. Campos top-level são comuns a todos os lastros; backing_documents e operation_data variam por tipo de lastro.

Campos top-level (comuns a todos os lastros)

📘

Variação por tipo de lastro

Os campos top-level são os mesmos em todos os casos. O que muda é o conteúdo de backing_documents (que arquivo PDF anexar), additional_data (campos regulatórios específicos) e operation_data (metadados de negócio). Exemplos no §5.3.

5.3 Anexar o lastro

Cada operação aceita até 5 arquivos PDF, com até 2MB cada. Cada arquivo é declarado em backing_documents com dois campos:

• type — categoria do documento. Valores aceitos: ccb, renegotiation_signature, renegotiation_document, proof_of_payment_disbursement, proof_of_down_payment, other. Na criação da cessão, o type deve ser ccb.
• value — identificador único do documento dentro do seu sistema. O nome do arquivo PDF anexado deve corresponder exatamente a esse value (sem a extensão .pdf)

Exemplo (CCB)

Documentos: CCB assinada.

"backing_documents": [
  { "type": "ccb", "value": "CCB-001234" }
]

Arquivo correspondente:

• CCB-001234.pdf

Os demais tipos de documento (renegotiation_signature, renegotiation_document, proof_of_payment_disbursement, proof_of_down_payment, other) são usados no anexo posterior via POST /api/loan/files — na criação, apenas ccb é aceito.

5.4 Enviar a operação

Envie o multipart com o JSON e os PDFs anexados:

curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/loan/' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -F 'loan_data={"fund_id":"...","originator_proposal_code":"OP-001","banker_cnpj":"...",...}' \
  -F '[email protected]' \
  -F '[email protected]'

Resposta de sucesso (201):

{
  "status": "created",
  "message": "Loan received successfully"
}

🚧

Idempotência

O originator_proposal_code é a chave de negócio da operação — reenviar com o mesmo código não duplica a cessão. Use o mesmo código para todas as retentativas.

5.5 Receber webhooks de status

A elegibilidade roda de forma assíncrona. Você é notificado via webhook LOAN_UPDATE na URL registrada; o data.entity_id traz o originator_proposal_code para correlação e o data.status indica o que aconteceu:

Exemplo de webhook recebido:

{
  "event": "update",
  "data": {
    "entity_id": "OP-001",
    "status": "approved",
    "entity_type": "ccb"
  }
}

Veja a seção Webhooks para configuração, segurança e política de retentativa.

6. Estados da operação

stateDiagram-v2
    [*] --> received: POST /api/loan/ (201)
    received --> ineligible: Falha de elegibilidade
    received --> eligible: Passa nos critérios
    eligible --> approved: Aprovada
    approved --> sent_acquisition_to_administrator: ADM sinalizada
    sent_acquisition_to_administrator --> acquired: ADM confirma
    acquired --> active: No estoque do fundo
    ineligible --> [*]

Estados intermediários de processamento com a ADM não emitem webhook dedicado. A lista completa está em Ciclo de vida. Para reconciliação, você pode consultar o status atual a qualquer momento via GET /api/loan/?fund_id=...&originator_proposal_code={código} (a consulta é feita por filtro no endpoint de listagem — não há rota por path param).

7. Cenários de erro

Erros síncronos (resposta HTTP da chamada)

Recusas de negócio (via webhook LOAN_UPDATE com data.status: rejected)

Quando a elegibilidade rejeita a operação, o motivo vem no campo reason. Os códigos canônicos são definidos por fundo no momento da homologação, conforme o regulamento e a política do originador. Ver o processo de definição em Critérios de elegibilidade. A lista de critérios acordada é entregue pela IORQ na homologação do fundo.

8. Próximos fluxos

Depois que a cessão é desembolsada, a operação entra no ciclo normal do FIDC: