Quickstart

1. Pré-requisitos

• Credenciais sandbox (client_id + client_secret) e fund_id recebidos por e-mail da IORQ
• 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 iorq-fund-id com o UUID do fundo — o mesmo recebido por e-mail na seção Fundos liberados:

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

Guarde o standard_webhooks_secret retornado — ele aparece só nessa resposta e é com ele que você valida a assinatura webhook-signature de cada entrega (Configuração e segurança). Headers custom em headers são uma camada adicional opcional. contract_version: "v2" é o envelope tipado que uma integração nova deve usar, e event_types: ["*"] assina todos os tipos; os dois campos e o PATCH para mudá-los depois estão em Configurando webhooks. O corpo legado v1 fica em Contrato v1 (legado) e só interessa a quem já o consome.

Antes de ceder qualquer coisa, confirme que a IORQ alcança a sua URL com um evento de teste (use o webhook_id da resposta acima):

curl -X POST 'https://webhook-sender-manager-development.iorq.com.br/api/webhook/SEU_WEBHOOK_ID/test' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'iorq-fund-id: YOUR_SANDBOX_FUND_ID'

A resposta é 202, e em seguida o seu endpoint recebe um webhook.test assinado. Se nada chegar, o roteiro de diagnóstico está em Validar o primeiro evento.

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' \
  -H 'iorq-fund-id: YOUR_SANDBOX_FUND_ID' \
  -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

Cada fato chega como um evento com um type próprio, e a operação é identificada por data.loan.originator_code (o seu originator_proposal_code, aqui QS-001). Em sandbox você recebe:

1. loan.invalid — só se a operação reprovar na validação ou na elegibilidade; o motivo vem em data.errors[] ou data.reason_text. A elegibilidade aprovada não gera evento.
2. loan.approved — o gestor do fundo aprovou o lote de aquisição em que a operação está. Em sandbox essa aprovação é feita pela IORQ: combine com o seu contato na IORQ quando estiver pronto para este passo.
3. (se o gestor recusar) loan.rejected.

O ciclo em sandbox termina aqui. Sandbox não tem administradora, então acquisition.completed, que em produção vem horas depois do loan.approved e põe a operação em active, não acontece lá; o que depende dele fica para produção (Passo 6, abaixo).

Exemplo de corpo recebido no loan.approved:

{
  "id": "evt_01K4Q8ZJ0000000000000000AA",
  "type": "loan.approved",
  "schema_version": "2026-10-01",
  "occurred_at": "2026-05-13T15:02:11.482913Z",
  "fund": { "id": "YOUR_SANDBOX_FUND_ID", "name": "NOME DO SEU FUNDO" },
  "subject": { "type": "loan", "id": "QS-001" },
  "idempotency_key": "loan.approved:loan:QS-001",
  "data": {
    "loan": { "originator_code": "QS-001", "id": "0d3a2f7e-5c1b-4c8e-9f4a-2b7d6e1a9c33", "kind": "ccb", "banker_code": null },
    "installment": null,
    "charge": null,
    "errors": null,
    "reason_text": null
  }
}

Grave a idempotency_key antes de processar: a entrega é at-least-once. O envelope e a tabela de tipos estão no Catálogo de eventos.

📘

Em produção, hoje, data.loan.id chega nulo

Em sandbox os produtores já publicam v2, e data.loan.id vem preenchido como acima. Em produção eles ainda publicam v1, a IORQ remonta o envelope na entrega e o campo chega null em todo evento: concilie pelo originator_code. O que mais muda entre os dois ambientes está em O que muda entre sandbox e produção.

Passo 6 — O que só acontece em produção

A liquidação exige uma operação active, e uma operação só fica active com o acquisition.completed da administradora, que sandbox não tem. Por isso POST /api/installment/settle não é testável em sandbox: a parcela ainda não está num estado que admite baixa. Em produção, com o mesmo webhook, o ciclo continua:

1. acquisition.completed — a administradora confirmou a cessão; a operação está ativa e liquidável.
2. POST /api/installment/settle para registrar o pagamento de uma parcela; você recebe installment.settled em seguida, com data.installment.number.
3. installment.settlement_completed — a administradora confirmou a baixa.

O mesmo vale para as outras confirmações da administradora (repurchase.completed, renegotiation.completed). A chamada e os campos da liquidação estão em Liquidação; a passagem para produção, em Ambientes e hosts.

3. Checklist do "deu certo"

• O POST /oauth2/token retornou 200 com access_token
• O POST /api/webhook retornou 200 com o webhook registrado (contract_version: "v2") e o standard_webhooks_secret
• Seu endpoint recebeu o webhook.test com assinatura válida
• O POST /api/loan/ retornou 201 com status: "created"
• Seu endpoint recebeu loan.approved para QS-001, com assinatura válida

Se tudo isso aconteceu, parabéns — sua integração base está funcionando. A liquidação e as confirmações da administradora você valida em produção, com o mesmo código. Agora vale aprofundar em cada fluxo individualmente.

4. Próximos passos