Padrões da API

Todos os endpoints da Business API seguem as convenções abaixo. Quando um endpoint foge de alguma delas, a página dele diz explicitamente.

Catálogo de endpoints

Base URL: https://api-business.openi.com.br/api/v1. Todos os caminhos começam com /companies/{companyId}.

Todos são somente leitura. O único POST é uma busca que recebe os parâmetros no corpo.

Período: from e to

Todo endpoint com uma data principal aceita from e to com o mesmo nome e o mesmo comportamento:

• Aplicam-se à data principal do endpoint (coluna Período do catálogo) — ex.: transactionAt nas transações, date nos lançamentos
• Formato: YYYY-MM-DD ou data-hora ISO 8601
• Ambos inclusivos: from=2026-08-01&to=2026-08-31 cobre agosto inteiro, do primeiro ao último instante do dia 31 (UTC). Com data-hora, compara o instante exato
• Cada um é opcional (exceto no fluxo de caixa): só from é "a partir de", só to é "até"
• from depois de to retorna 400
• Sempre restringem o resultado, mesmo com joinOperator=or

GET .../bank-accounts/transactions?from=2026-08-01&to=2026-08-31

Para qualquer outra data (ex.: createdAt para sincronização incremental, bankTransferDate, expiresAt), use filters — que tem as mesmas regras de formato:

filters=[{"id":"createdAt","operator":"gt","value":"2026-08-07T15:00:00Z"}]

Os dois se combinam: from/to recortam o período e filters refina dentro dele.

Posições de investimento são uma foto em um momento, não um período: por isso usam asOfDate em vez de from/to.

Parâmetros de escopo

accountId (transações, lançamentos bancários) e investmentId (lançamentos de investimentos) delimitam o conjunto consultado:

• Repetíveis na query: ?accountId=a&accountId=b. No corpo do POST, investmentIds é um array
• Ids que não pertencem à empresa retornam 404
• Assim como from/to, sempre restringem o resultado, independentemente de joinOperator

Filtros, ordenação e busca

Um único formato para todos os endpoints: filters=[{ id, operator, value }], joinOperator, sort=[{ id, desc }] e search. O id é sempre o nome do campo na resposta. Referência completa em Filtros, ordenação e busca; a lista de campos de cada endpoint fica na seção Campos filtráveis da página dele.

Datas nas respostas

• Instantes em ISO 8601 UTC: "2026-08-07T14:33:00.000Z"
• Datas de agrupamento diário (date no fluxo de caixa e nos resumos diários) em YYYY-MM-DD
• Datas ausentes vêm como null

Valores monetários

Na entrada (filtros), valores são sempre decimais com ponto: 1500.50.

Na saída, o padrão é string decimal com duas casas e sem símbolo de moeda ("1500.50") — a moeda vem em currency / currencyCode. Exceções:

Taxas (rate, annualRate...) e quantidades são strings numéricas. Nas transações bancárias e nos lançamentos bancários, os valores têm sinal: positivo para entradas, negativo para saídas.

Paginação

Parâmetros iguais em todos os endpoints paginados:

• page: a partir de 1 (padrão: 1)
• perPage: de 1 a 500 (padrão: 10; 30 no POST de busca)

O formato da resposta varia por família de endpoint:

Para percorrer tudo: nos lançamentos, avance page enquanto hasMore for true; nos demais, até receber menos de perPage itens. Detalhes em Paginação.

Respostas e erros

Sucesso:

{ "status": "success", "data": { } }

Erro:

{ "status": "error", "message": "from: must not be after to" }