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-hs.sandbox.iorq.com.br/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

curl -X POST 'https://hs-api.sandbox.iorq.com.br/webhook' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks",
    "events": ["*"],
    "description": "Quickstart"
  }'

Guarde o signing_secret retornado. Você vai precisar dele para validar HMAC.

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-api.sandbox.iorq.com.br/loan' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'loan_data={
    "fund_id": "YOUR_SANDBOX_FUND_ID",
    "originator_proposal_code": "QS-001",
    "product_type": "financing",
    "acquisition_value": 1000.00,
    "number_of_installments": 4,
    "date_issued": "2026-05-13",
    "borrower": {
      "document_number": "12345678909",
      "document_type": "CPF",
      "name": "Teste Quickstart",
      "birth_date": "1990-01-01",
      "email": "[email protected]",
      "phone": "+5511999990000",
      "address": {
        "zip_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},
      {"code": "2", "due_date": "2026-07-13", "face_value": 280.00},
      {"code": "3", "due_date": "2026-08-13", "face_value": 280.00},
      {"code": "4", "due_date": "2026-09-13", "face_value": 280.00}
    ],
    "backing_documents": [{"type": "ccb", "value": "CCB-TEST-001"}]
  }' \
  -F 'files=@./CCB-TEST-001.pdf'

Resposta esperada:

{
  "originator_proposal_code": "QS-001",
  "status": "received",
  "fund_id": "...",
  "received_at": "2026-05-13T12:05:00Z"
}

Passo 5 — Consumir os webhooks

Em sandbox, a IORQ acelera o ciclo. Em até 30 segundos seu endpoint deve receber, em ordem:

loan_received — schema e arquivo válidos
loan_approved — passou nos critérios sandbox (sempre aprova quando o payload é válido)
loan_term_signed — termo simulado assinado
disbursement_completed — desembolso simulado registrado

Cada evento traz originator_proposal_code: "QS-001" para correlação.

Passo 6 — Liquidar uma parcela

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

curl -X POST 'https://hs-api.sandbox.iorq.com.br/installment/settle' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "originator_proposal_code": "QS-001",
    "installment_code": "1",
    "settled_at": "2026-06-13",
    "settled_value": 280.00,
    "payment_method": "pix",
    "idempotency_key": "QS-001-1"
  }'

Você recebe o webhook installment_settled em seguida.

3. Checklist do "deu certo"

O POST /token retornou 200 com access_token
O POST /webhook retornou 200 com signing_secret
O POST /loan retornou 201 com status: "received"
Seu endpoint recebeu os 4 webhooks da cessão
O POST /installment/settle retornou 200 com status: "settled"
Seu endpoint recebeu o webhook installment_settled

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, lastros agnósticos, estados, erros.

Aprofundar — Liquidação

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

Referência — Catálogo de eventos

Lista completa de eventos com payloads.

Referência — Códigos de erro

Tabela canônica de erros HTTP e de negócio.