API do investidor

GET · somente leitura, mais o pedido de estoque (WIP) · host investor-api.iorq.com.br (sandbox: investor-api-dev.iorq.com.br)

1. O que esta API oferece

A API do investidor entrega, por credencial M2M, os covenants e os indicadores de acompanhamento dos fundos em que a gestora do investidor tem cotas: o valor apurado, o limite do regulamento, a unidade, as datas do dado e a versão da fórmula de cada covenant, a série histórica de cada um e o painel de patrimônio e carteira do fundo.

A referência das rotas fica em IORQ Investor API, na aba API Reference, separada da API do originador. A autenticação é a mesma (OAuth 2.0 client_credentials no host auth-hs.iorq.com.br), o header de fundo é o mesmo (iorq-fund-id) e o formato de erro é o mesmo. O que muda é o host e as permissões da credencial, descritas em Perfis de acesso.

Cada credencial enxerga só os fundos em que a gestora do investidor tem cotas; a lista sai em GET /v1/funds.

As rotas ficam na raiz do host, sem o prefixo /api da API operacional. Cada uma tem a sua página na referência: listInvestorFunds, listFundCovenants, listFundCovenantHistory, listFundIndicators e requestInventoryExport.

2. O que esta API não expõe

• Nenhum dado de devedor nas respostas. Não há CPF, nome, operação nem parcela no corpo de nenhuma rota. Os indicadores são agregados da carteira. A exceção é o estoque, que traz parcela, CPF/CNPJ e nome do devedor, mas num arquivo entregue por e-mail, com permissão própria.
• Nenhuma posição de cotista. A API não informa quantas cotas o investidor tem, nem o valor delas.
• Nenhum julgamento de enquadramento. A resposta traz o valor e o limite de cada covenant; a comparação entre os dois fica com quem consome.
• Nenhum dado em tempo real. Os números vêm do arquivo mais recente que a administradora do fundo publicou (base adm). No melhor caso é o arquivo do dia útil anterior (D-1); se a administradora atrasar ou não publicar, o dado fica mais antigo. Cada valor traz em as_of a data do dado em que foi calculado.
• Nenhum indicador de controle interno da gestão. Só saem os covenants do regulamento listados no catálogo e os indicadores do painel.
• Nenhuma escrita. As rotas de leitura são GET. O POST /v1/inventory-exports só pede a geração de um arquivo; ele não altera nada no fundo.

A API sempre devolve o último valor disponível, por mais antigo que seja. Confira a idade do dado em as_of antes de usá-lo.

3. Primeira chamada

sequenceDiagram
    participant INV as Investidor
    participant AUTH as IORQ Auth (Cognito)
    participant API as API do investidor

    INV->>AUTH: POST /oauth2/token (client_id + client_secret)
    AUTH-->>INV: access_token (JWT, exp=1h)
    INV->>API: GET /v1/funds (Bearer)
    API-->>INV: funds[].id
    INV->>API: GET /v1/covenants (Bearer + iorq-fund-id)
    API-->>INV: covenants do fundo

3.1 Obter o token

O token é o mesmo de qualquer integração com a IORQ. Os detalhes estão em Autenticação.

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

3.2 Listar os fundos

curl 'https://investor-api.iorq.com.br/v1/funds' \
  -H 'Authorization: Bearer eyJraWQiOiJyc2EtMjAyNiIs...'

{
  "funds": [
    {
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "FIDC Exemplo",
      "code": "fundo-exemplo"
    }
  ]
}

A lista traz só os fundos em que a credencial tem permissão de leitura, ordenados por id. Lista vazia significa que a credencial está provisionada, mas nenhum fundo vinculado pôde ser listado: fale com o seu contato na IORQ.

O id é o valor do header iorq-fund-id em toda rota de fundo. O code é um nome curto e estável, para log e exibição; ele não é aceito no header.

3.3 Consultar os covenants do fundo

curl 'https://investor-api.iorq.com.br/v1/covenants' \
  -H 'Authorization: Bearer eyJraWQiOiJyc2EtMjAyNiIs...' \
  -H 'iorq-fund-id: 6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f'

O corpo da resposta está em Covenants.

4. Erros

4.1 Formatos

Os erros de requisição e de acesso que o serviço gera têm o corpo padrão da IORQ API, com error_code estável:

{
  "message": "Fund is not available to this credential",
  "status": 403,
  "cid": "1-66fb2c1e-3a4b5c6d7e8f9a0b1c2d3e4f",
  "error_code": "FUND_ACCESS_DENIED"
}

Quando o dado do fundo existe mas não pode ser servido como está, a resposta é 503 com um problem document (RFC 9457, Content-Type: application/problem+json):

{
  "type": "urn:iorq:investor-api:problem:covenant-point-missing",
  "title": "Covenant has no point in the series",
  "status": 503,
  "detail": "No point in the series for covenant 'reserva_liquidez'",
  "error_code": "COVENANT_POINT_MISSING"
}

Os erros que o gateway gera antes de a requisição chegar ao serviço têm só message. Uma dependência interna fora do ar responde 503 com o corpo padrão mascarado: {"message": "Unexpected error", "status": 503, "cid": "..."}, sem error_code.

4.2 Tabela

Token inválido ou expirado responde 403, não 401, como no serviço de webhooks. Trate 403 com corpo {"message": "Forbidden"} como "renove o token".

5. Próximos passos