Covenants

GET /v1/covenants · header iorq-fund-id · somente leitura

1. O que é um covenant nesta API

Um covenant é um indicador da carteira ou do patrimônio do fundo que o regulamento obriga a ficar acima de um piso ou abaixo de um teto. A API publica, para cada covenant do catálogo:

• o valor apurado no último ponto disponível;
• o limite do regulamento e o tipo de limite (min ou max);
• a unidade em que valor e limite estão expressos;
• as datas: o dia da série a que o ponto pertence e a data do dado;
• a versão da fórmula usada no cálculo.

A API não diz se o fundo está enquadrado. Ela devolve o valor e o limite, e a comparação fica com quem consome.

2. Base de apuração

Todos os valores são apurados sobre o arquivo mais recente publicado pela administradora do fundo (posição de carteira, caixa e cotas), a base adm. A administradora publica o arquivo de um dia útil no dia útil seguinte, então no melhor caso o dado é de D-1 (D-3 na segunda-feira). Quando a administradora atrasa ou deixa de publicar, a apuração continua sobre o último arquivo recebido e o dado fica mais antigo que isso. A data do dado de cada valor vem em as_of. O campo base vem sempre adm.

3. A resposta

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

{
  "fund_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "as_of": "2026-10-01",
  "generated_at": "2026-10-05T13:26:00Z",
  "covenants": [
    {
      "code": "subordinacao_senior",
      "name": "Índice de subordinação sênior",
      "category": "covenant",
      "base": "adm",
      "value": 63.5,
      "unit": "%",
      "limit": 25,
      "limit_type": "min",
      "numerator_as_of": "2026-10-01",
      "denominator_as_of": "2026-10-01",
      "formula_version": "v1",
      "date": "2026-10-04",
      "as_of": "2026-10-01",
      "calculated_at": "2026-10-05T02:50:51Z"
    }
  ]
}

date e as_of. Os dois quase nunca coincidem. Um ponto com date 2026-10-04 (domingo) tem as_of 2026-10-01: no domingo, o arquivo mais recente da administradora era o de quinta. Para comparar com o relatório da administradora, use as_of.

Percentuais. Quando unit é % ou % a.m., value e limit vêm em pontos percentuais, não em fração: 63.5 é 63,5%, e 0.5 é 0,5%.

Números. value e limit são números JSON com precisão decimal. Não arredonde antes de comparar com o limite.

Último ponto, qualquer que seja a idade. A API sempre devolve o último ponto de cada covenant. Se o dado da administradora parar de chegar, o valor continua saindo com o mesmo as_of; confira essa data antes de usar o número.

Falta de dado. Se algum covenant do catálogo não tiver nenhum ponto, ou se um ponto estiver fora do contrato, a API responde 503 em vez de devolver uma lista incompleta. Ver os erros.

Cache. O valor muda no máximo algumas vezes por dia. A API guarda a resposta por 60 segundos por fundo, e o seu sistema pode guardar por mais tempo.

4. Catálogo

Só os covenants listados aqui podem aparecer na resposta. Cada fundo publica os covenants do seu regulamento, então a resposta de um fundo traz só parte desta lista. O limite de cada covenant é o do regulamento do fundo e vem no campo limit da própria resposta.

4.1 Patrimônio e estrutura de capital

4.2 Carteira

4.3 Inadimplência e retorno

Os indicadores de janela só passam a sair quando a janela de liquidação diária da administradora fica completa para o fundo. Até lá, não aparecem na resposta nem no histórico.

Alguns covenants podem vir sem régua numérica para um fundo (limit nulo), quando o regulamento não fixa um número.