Quickstart

1. Pré-requisitos

Credenciais sandbox (client_id + client_secret) emitidas pela IORQ — peça ao seu contato comercial
fund_id sandbox vinculado à sua aplicação
Endpoint público para receber webhooks. Para testar localmente, use ngrok ou similar
curl ou um cliente HTTP equivalente

2. Passo a passo

Passo 1 — Obter um token

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

Guarde o access_token da resposta. Vale por 1 hora.

Passo 2 — Registrar o webhook

O serviço de webhooks é separado e exige o header Fund-Id:

curl -X POST 'https://webhook-sender-manager-development.iorq.com.br/webhook' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Fund-Id: YOUR_SANDBOX_FUND_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "message_type": "LOAN_UPDATE",
    "webhook_url": "https://abc123.ngrok.io/webhooks",
    "headers": { "X-My-Auth": "um-segredo-seu" }
  }'

Guarde o signing_secret retornado — ele aparece só nessa resposta e é com ele que você valida a assinatura X-IORQ-Signature de cada entrega. Headers custom em headers são uma camada adicional opcional.

Passo 3 — Preparar o arquivo de lastro

Em sandbox, qualquer PDF válido com menos de 2 MB serve. Crie um arquivo chamado CCB-TEST-001.pdf — o nome precisa bater com o backing_documents[].value que vamos enviar no próximo passo.

Passo 4 — Ceder a operação

curl -X POST 'https://hs-receiver-app-development.iorq.com.br/api/loan/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'loan_data={
    "fund_id": "YOUR_SANDBOX_FUND_ID",
    "originator_proposal_code": "QS-001",
    "banker_cnpj": "12345678000199",
    "product_type": "financing",
    "acquisition_value": 1000.00,
    "number_of_installments": 4,
    "date_issued": "2026-05-13",
    "borrower": {
      "cpf": "12345678909",
      "name": "Teste Quickstart",
      "birth_date": "1990-01-01",
      "email": "[email protected]",
      "phone": "+5511999990000",
      "address": {
        "postal_code": "01310100",
        "street": "Av. Paulista",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "installments": [
      {"code": "1", "due_date": "2026-06-13", "face_value": 280.00, "acquisition_value": 250.00},
      {"code": "2", "due_date": "2026-07-13", "face_value": 280.00, "acquisition_value": 250.00},
      {"code": "3", "due_date": "2026-08-13", "face_value": 280.00, "acquisition_value": 250.00},
      {"code": "4", "due_date": "2026-09-13", "face_value": 280.00, "acquisition_value": 250.00}
    ],
    "backing_documents": [{"type": "ccb", "value": "CCB-TEST-001"}]
  }' \
  -F 'files=@./CCB-TEST-001.pdf'

Resposta esperada (201):

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

Passo 5 — Consumir os webhooks

A IORQ envia um único message_type (LOAN_UPDATE) e o que aconteceu vem em data.status. Ao longo do ciclo você recebe, para entity_id: "QS-001":

data.status: "approved" — passou nas validações e na elegibilidade sandbox
(em caso de problema) data.status: "rejected" ou "invalid" — ver data.reason

Exemplo de corpo recebido:

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

Passo 6 — Liquidar uma parcela

Com a operação ativa, registre o pagamento da primeira parcela:

curl -X POST 'https://hs-receiver-app-development.iorq.com.br/api/installment/settle' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_id": "YOUR_SANDBOX_FUND_ID",
    "originator_proposal_code": "QS-001",
    "code": "1",
    "nosso_numero": "00012345",
    "paid_amount": 280.00,
    "payment_date": "2026-06-13",
    "is_partial_payment": false
  }'

Você recebe um webhook LOAN_UPDATE com data.status: "settled_installment" em seguida.

3. Checklist do "deu certo"

O POST /oauth2/token retornou 200 com access_token
O POST /webhook retornou 201 com o webhook registrado
O POST /api/loan/ retornou 201 com status: "created"
Seu endpoint recebeu o webhook com data.status: "approved"
O POST /api/installment/settle retornou 201 com status: "settled"
Seu endpoint recebeu o webhook com data.status: "settled_installment"

Se tudo isso aconteceu, parabéns — sua integração base está funcionando. Agora vale aprofundar em cada fluxo individualmente.

4. Próximos passos

Aprofundar — Cessão de operações

Multipart completo, campos do payload, estados, erros.

Aprofundar — Liquidação

liquidação na curva, antecipada e a menor.

Referência — Catálogo de eventos

Valores de data.status e formato do payload.

Configurar — Webhooks

Registro, gestão e autenticação das entregas.