Cessão de operações

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

1. Quando usar este fluxo

Use POST /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).

📘

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 fluxo é idêntico em todos os casos. O que muda são os campos específicos do payload (em backing_documents e operation_data) e quais arquivos de lastro são anexados.

2. Atores envolvidos

3. Fluxo end-to-end

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

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

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

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

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 /token. O token tem validade de 1 hora — reutilize-o entre múltiplas chamadas no mesmo lote.

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

curl -X POST 'https://auth-hs.iorq.com.br/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 (ccb, duplicate, fiscal_note, prepaid_contract, etc.)
• 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)

CCB

Documentos: CCB assinada. Opcionalmente: nota fiscal, comprovante de garantia.

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

Arquivos correspondentes:

• CCB-001234.pdf
• NF-9876.pdf

Duplicata

Documentos: duplicata mercantil + nota fiscal eletrônica + comprovante de aceite (quando aplicável).

"backing_documents": [
  { "type": "duplicate",   "value": "DUP-5678" },
  { "type": "fiscal_note", "value": "NFE-9876543" }
]

Arquivos correspondentes:

• DUP-5678.pdf
• NFE-9876543.pdf

Contrato pré-pago

Documentos: contrato vigente entre originador e tomador.

"backing_documents": [
  { "type": "prepaid_contract", "value": "CONTRACT-7777" }
]

Arquivos correspondentes:

• CONTRACT-7777.pdf

5.4 Enviar a operação

Envie o multipart com o JSON e os PDFs anexados:

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

Resposta de sucesso (201):

{
  "originator_proposal_code": "OP-001",
  "status": "received",
  "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
  "received_at": "2026-05-13T11:00:00Z"
}

🚧

Idempotência

Reenviar com o mesmo originator_proposal_code retorna 200 com o status atual da operação, sem duplicar. 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 na URL registrada. Cada evento traz o originator_proposal_code para correlação.

Exemplo de webhook recebido:

{
  "event": "loan_approved",
  "originator_proposal_code": "OP-001",
  "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
  "timestamp": "2026-05-13T11:02:34Z"
}

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

6. Estados da operação

stateDiagram-v2
    [*] --> received: POST /loan (201)
    received --> rejected: Falha de elegibilidade
    received --> approved: Passa nos critérios
    approved --> term_signing: ADM sinalizada
    term_signing --> term_signed: Partes assinam
    term_signed --> disbursed: TED emitida
    rejected --> [*]
    disbursed --> [*]

Estados intermediários (term_signing) não emitem webhook dedicado. Para reconciliação, você pode consultar o status atual a qualquer momento via GET /loan/{originator_proposal_code}.

7. Cenários de erro

Erros síncronos (resposta HTTP da chamada)

Recusas de negócio (via webhook loan_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 e a lista por fundo via GET /funds/{fund_id}/eligibility.

8. Próximos fluxos

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