EDI Analytics API

Acesso programático aos mesmos motores que sustentam a plataforma EDI: resolução de valores mobiliários nos Estados Unidos, Brasil, México e Peru; cotações globais de fechamento; fundamentos padronizados com inteligência de períodos fiscais; matrizes as-of multidomínio; e execução assíncrona em lote. Uma requisição produz o mesmo número no Excel, em Python, no Quant Workstation e em um relatório agendado — a paridade é estrutural, não dependente de testes.

Início rápido

Autentique-se uma vez — o cookie de sessão carrega suas permissões de acesso em todas as chamadas subsequentes.

# 1. Faça login (armazena o cookie de sessão)
curl -c cookies.txt -X POST https://api.edi.finance/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourfirm.com", "password": "…"}'

# 2. Resolva identificadores em ids canônicos de entidade
curl -b cookies.txt -X POST https://api.edi.finance/api/analytics/v1/resolve \
  -H "Content-Type: application/json" \
  -d '{"identifiers": [{"value": "PETR4-BR"}, {"value": "AAPL"}]}'

# 3. Uma grade de comparáveis multimercado em USD, em uma única chamada
curl -b cookies.txt -X POST https://api.edi.finance/api/analytics/v1/matrix \
  -H "Content-Type: application/json" \
  -d '{"ids": ["AAPL-US","BBAS3-BR","BIMBOA-MX"],
       "metrics": ["close","MARKET_CAP","SECTOR"],
       "asOf": "2026-07-30", "currency": "USD"}'

Ou com o cliente de referência em Python:

from edi_analytics import EdiAnalyticsClient, spill_matrix

client = EdiAnalyticsClient("https://api.edi.finance")
client.login("you@yourfirm.com", "…")

env = client.matrix(ids=["AAPL-US", "BBAS3-BR"],
                    metrics=["close", "MARKET_CAP", "SECTOR"])
grid = spill_matrix(env, ids=["AAPL-US", "BBAS3-BR"],
                    metrics=["close", "MARKET_CAP", "SECTOR"])

Autenticação de serviço — chaves de API

Para scripts, SDKs e integrações servidor a servidor, crie uma chave de API (ela age em seu nome, com as suas permissões) e envie-a como X-API-Key ou Authorization: Bearer — sem cookies. As chaves são exibidas uma única vez na criação, podem expirar e são revogáveis; o gerenciamento de chaves sempre exige uma sessão autenticada, nunca uma chave.

# Crie uma chave (autenticado por sessão) e use-a onde quiser
curl -b cookies.txt -X POST https://api.edi.finance/api/analytics/v1/keys \
  -H "Content-Type: application/json" -d '{"label": "research pipeline", "expiresInDays": 365}'

curl -H "X-API-Key: edi_sk_…" -X POST https://api.edi.finance/api/analytics/v1/resolve \
  -H "Content-Type: application/json" -d '{"identifiers": [{"value": "AAPL"}]}'

Python: EdiAnalyticsClient("https://api.edi.finance", api_key="edi_sk_…") — dispense o login() por completo.

Conceitos fundamentais

O envelope

Todo endpoint de dados retorna o mesmo envelope de três partes. As linhas em data são planas e autodescritivas — serializam de forma idêntica para JSON, CSV e intervalos de spill do Excel.

{
  "data":   [ /* linhas planas de observação */ ],
  "errors": [ /* falhas no nível da linha — nunca uma falha da requisição */ ],
  "meta":   { "pagination": { "total": 412 }, "registryVersion": "2026.07.16.1A" }
}

Identificadores e o eco do requestId

Todo endpoint aceita diretamente identificadores de tipos mistos — tickers qualificados por mercado (PETR4-BR, BIMBOA-MX), tickers simples, ISINs, CUSIPs, CIKs e ids canônicos de entidade. Cada linha de resposta carrega tanto requestId (o seu identificador, exatamente como enviado — a chave de junção de volta para a célula da sua planilha ou o índice do seu dataframe) quanto entityId (a nossa chave canônica, estável através de mudanças de ticker e classes de ações).

Falha parcial é a norma

Um ticker inválido jamais pode derrubar uma pasta de trabalho de 500 células. Identificadores não resolvíveis, métricas desconhecidas e conversões sem cotação retornam como entradas em errors — cada uma com um requestId, um code estável e um detail legível — enquanto todas as demais linhas retornam normalmente.

Proveniência

Toda resposta informa a versão do registro de métricas que a precificou (meta.registryVersion), e as linhas carregam a moeda efetivamente retornada. Os números são auditáveis entre clientes: a mesma requisição produz o mesmo valor em qualquer lugar, por construção.

Vocabulário

Os parâmetros de requisição abaixo significam a mesma coisa em todo endpoint que os aceita.

Periodicidade (fundamentos)

basis seleciona o eixo de reapresentação: original (padrão) ou restated (em preparação — aguarda modelagem de vintages).

Frequência (cotações & séries)

Ajuste de preço

Moeda

currency tem como padrão LOCAL: os valores retornam em sua moeda nativa de cotação ou de reporte, informada por linha — uma planilha brasileira nunca recebe USD silenciosamente. Qualquer código ISO (USD, BRL, MXN, EUR, …) é convertido no servidor; veja conversão de moeda para saber qual taxa de câmbio se aplica em cada caso.

Resolução de valores mobiliários

A camada de identidade sob todas as demais chamadas. Envie até 2.000 identificadores de tipos mistos; receba de volta entidades canônicas com a estrutura empresa vs. listagem. Linhas que compartilham um entityId são classes de ações / listagens do mesmo emissor, enumeradas em listings.

// POST /api/analytics/v1/resolve
{ "identifiers": [ {"value": "PETR4-BR"}, {"value": "US0378331005"}, {"value": "037833100", "type": "CUSIP"} ] }

// 200 — uma linha por candidato
{ "data": [
    { "requestId": "PETR4-BR", "entityId": "BR-9512", "ticker": "PETR4",
      "market": "BR", "matchedBy": "ticker", "candidateCount": 1,
      "listings": [ {"ticker": "PETR3", "market": "BR"}, {"ticker": "PETR4", "market": "BR"} ] } ] }

• Tickers sem qualificação resolvem contra o seu mercado padrão e, na ausência dele, contra os EUA. Qualifique com um sufixo (-BR, -MX, -PE, -US) para ser explícito; tickers hifenizados como BRK-B permanecem intactos.
• candidateCount > 1 marca um identificador ambíguo — os endpoints de dados reportam esses casos como erros de linha em vez de adivinhar.
• O formato do identificador é classificado automaticamente; passe type (TICKER · ISIN · CUSIP · CIK · ENTITY_ID) para sobrescrever.

Catálogo de métricas

O registro oficial de todas as métricas que os motores conseguem calcular — o mesmo registro contra o qual executam o screener da plataforma, os painéis quant e a bancada de fórmulas, incluindo as métricas de fórmula personalizadas da sua organização. Faça autocompletar a partir daqui e uma requisição jamais nomeará uma métrica que os motores não conheçam.

Cada linha informa seu dataset, motor, tipo de valor, unidade, tipos de entidade suportados, tipos de tempo (as-of / série temporal), modos de período e status.

Cotações globais

OHLCV de fechamento em todos os mercados cobertos, com contenção de listagens cruzadas embutida: uma linha de São Paulo que compartilha o ticker com uma emissão americana jamais pode se emendar na série dos EUA. Observações duplicadas são deduplicadas em uma única linha canônica por pregão.

// POST /api/content/global-prices/v1/prices
{ "ids": ["BBAS3-BR"], "startDate": "2026-01-01", "endDate": "2026-07-30",
  "frequency": "M", "fields": ["price", "volume"] }

// 200 — observações de fim de mês, moeda nativa informada por linha
{ "data": [
    { "requestId": "BBAS3-BR", "entityId": "BR-1023", "date": "2026-06-30",
      "currency": "BRL", "price": 19.91, "volume": 31200400 }, … ] }

• fields: price · priceOpen · priceHigh · priceLow · volume. adjust seleciona a base de preço.
• Todos os onze valores de frequência são suportados, com corte por calendário e ancoragem na data inicial.
• Com um currency, cada observação é convertida pela taxa de câmbio à vista da data daquela observação; volume nunca é convertido.

Fundamentos

Dados fiscais padronizados com a inteligência de períodos da plataforma. O servidor é o dono da semântica de períodos — armazenamento como acumulado do ano, inferência do encerramento do exercício fiscal, derivação do Q4, janelas LTM — para que nenhuma fórmula precise sê-lo.

// POST /api/content/fundamentals/v1/fundamentals
{ "ids": ["AAPL-US"], "metrics": ["REVENUE"], "periodicity": "LTM",
  "fiscalPeriod": { "start": "2025-01-01", "end": "2026-07-30" } }

// 200 — receita móvel dos últimos doze meses em cada encerramento de trimestre fiscal
{ "data": [
    { "requestId": "AAPL-US", "metric": "REVENUE", "periodicity": "LTM",
      "fiscalYear": 2026, "fiscalPeriod": "Q2", "fiscalEndDate": "2026-03-28",
      "currency": "USD", "value": 451442000000 }, … ] }

• fiscalPeriod.start/end são datas de calendário; o servidor as resolve para períodos fiscais encerrados. Janela padrão: cinco anos para trás.
• As linhas reportam a moeda de reporte do emissor, ou a currency solicitada após conversão.
• Métricas desconhecidas são erros de linha por métrica; o restante da requisição ainda retorna.

Matriz

Muitos ativos × muitas métricas em uma única data as-of, em uma requisição — a primitiva da grade de comparáveis. As métricas podem misturar datasets livremente: cotações, fundamentos, múltiplos de valuation, medidas derivadas e atributos de texto retornam todos pelo mesmo envelope.

// POST /api/analytics/v1/matrix
{ "ids": ["AAPL-US", "BBAS3-BR", "BIMBOA-MX"],
  "metrics": ["close", "MARKET_CAP", "PE_LTM", "SECTOR"],
  "asOf": "2026-07-30", "currency": "USD" }

// 200 — uma célula por (id, métrica); as-of = última observação na data ou antes dela
{ "data": [
    { "requestId": "AAPL-US",   "metric": "MARKET_CAP", "dataset": "derived",
      "valueType": "currency", "value": 4925847973597 },
    { "requestId": "BBAS3-BR",  "metric": "close",  "dataset": "prices", "value": 4.11 },
    { "requestId": "BIMBOA-MX", "metric": "SECTOR", "dataset": "entity_attributes",
      "valueType": "text", "value": "Food & Beverage" } ] }

• Nomes de métrica que colidem entre datasets (REVENUE reportado vs. de consenso) são resolvidos por uma precedência documentada — as demonstrações reportadas vencem. Passe {"metric": "REVENUE", "dataset": "estimates"} para sobrescrever explicitamente.
• Métricas de demonstrações financeiras aceitam periodMode: "fy" para valores do último exercício fiscal; use o endpoint de fundamentos para séries QTR/LTM/YTD, ou as métricas de valuation pré-calculadas (PE_LTM, EV_EBITDA_LTM, …).
• Células cujo cálculo resulta em nulo ficam ausentes, não viram erro — uma planilha preenche #N/A.

Screener

Execute screens no mesmo motor do screener da plataforma — condições sobre métricas financeiras, métricas de preço, múltiplos de valuation e as métricas de fórmula personalizadas da sua organização, com filtros de setor, bolsa, país e universo. Endpoints complementares: POST /count retorna a contagem de correspondências sem materializar linhas (conecte-o a um indicador ao vivo de "N empresas correspondem"), e GET /fields lista todos os campos filtráveis.

// POST /api/content/screener/v1/search
{ "conditions": [ { "metric": "MARKET_CAP", "operator": "gt", "value": 100000000000 },
                  { "metric": "ROE", "operator": "gte", "value": 0.15 } ],
  "metrics": ["REVENUE", "PE"], "sortBy": "MARKET_CAP", "currency": "USD", "limit": 50 }

// 200 — uma linha por ativo correspondente; meta.pagination.total = total de correspondências
{ "data": [
    { "ticker": "AAPL", "entityId": "0000320193", "sector": "Technology",
      "nativeCurrency": "USD", "marketCap": 4925847973597,
      "metrics": { "REVENUE": 451442000000, "PE": 43.9 } }, … ] }

• Operadores: gt · gte · lt · lte · eq · neq. Uma empresa sem uma métrica condicionada é reprovada no screen.
• currency aqui tem como padrão USD (não LOCAL): os limiares de um screen comparam emissores entre si, o que exige uma moeda comum. As linhas ainda informam sua nativeCurrency; meta.fxRateDate divulga a data da taxa de câmbio utilizada.
• tickers restringe o universo de candidatos; batch:"Y" enfileira screens grandes pela execução em lote.

Fundos

Dados de fundos dos mercados locais no Brasil (mais de 65.000 fundos registrados na CVM), México e Peru, com as convenções de identificador que cada mercado realmente usa: fundos BR resolvem por CNPJ em qualquer formato (00.000.684/0001-21 ou 00000684000121), fundos MX e PE por ticker ou id de entidade. Quatro endpoints compartilham um único contrato:

// POST /api/content/funds/v1/prices
{ "ids": ["00000684000121", "+TASAD1F1"], "fields": ["nav", "netAssets"],
  "startDate": "2026-01-01", "endDate": "2026-07-30", "frequency": "M", "currency": "USD" }

• As séries BR referem-se à classe principal do fundo; fundos PE carregam a moeda de cada emissão (PEN ou USD), informada por linha.
• currency converte os campos monetários (cota, patrimônio líquido, fluxos) pela taxa à vista de cada observação, exatamente como em cotações globais.

Execução em lote

Todo endpoint de dados aceita "batch": "Y" com o corpo de requisição idêntico — vire uma única flag quando a pasta de trabalho crescer além dos limites síncronos. O ramo em lote executa o mesmo caminho de código do síncrono, então os resultados são idênticos por construção.

Os jobs pertencem à conta que os enviou e expiram após 24 horas. Jobs com falha entregam um envelope EXECUTION_ERROR pelo mesmo contrato.

Conversão de moeda

A conversão é feita no servidor e é sensível à semântica — o tipo certo de taxa de câmbio se aplica a cada valor:

Taxas cruzadas compõem-se via USD. Uma conversão que não pode ser precificada — moeda de origem desconhecida, par não suportado, nenhuma taxa dentro da janela de defasagem — é um erro de linha FX_UNAVAILABLE com as linhas afetadas descartadas: você nunca recebe silenciosamente valores nativos sem conversão.

Taxonomia de erros

Falhas no nível da requisição usam os status HTTP padrão: 400 requisição malformada · 401 não autenticado · 404 id de lote desconhecido/expirado.

Limites de requisição

Clientes & Excel

Python. O cliente de referência (edi_analytics.py) encapsula o login, o envelope e o polling de lotes, e traz os helpers de spill usados pela integração com o Excel — spill_scalar, spill_series, spill_fundamentals, spill_matrix — cada um retornando uma grade 2-D pronta para um dataframe ou uma matriz dinâmica.

Excel. O suplemento registra fórmulas exatamente sobre esta API:

=EDI("AAPL-US", "MARKET_CAP")                      → 4,925,847,973,597
=EDI.HISTORY("BBAS3-BR", "price", "2026-01-01", "2026-07-30", "M")   → spill de 7×2
=EDI.FUNDAMENTALS("AAPL-US", "REVENUE", "LTM")   → spill de períodos fiscais
=EDI.MATRIX(A2:A20, B1:F1)                          → spill de uma grade de comparáveis

Entradas inválidas degradam célula a célula (#N/A, #NAME?) — nunca uma atualização de pasta de trabalho que falha por inteiro. O suplemento agrupa as requisições de fórmula pela execução em lote automaticamente.

Qualquer outra stack. O documento OpenAPI 3 alimenta clientes gerados para outras linguagens.

Experimente

Entre com sua conta EDI e execute requisições ao vivo contra a API — todos os exemplos desta página são executáveis. As requisições rodam com as suas permissões de acesso, exatamente como rodariam a partir do Excel ou de um script.

Recursos em preparação

Estes eixos de requisição fazem parte do contrato, mas são deliberadamente rejeitados (HTTP 400, com mensagem explicativa) até que o maquinário que os sustenta entre em produção — você pode programar contra o vocabulário hoje sem risco de respostas erradas silenciosas:

• basis: "restated" — demonstrações reapresentadas, aguardando modelagem de vintages.
• periodicity: "SEMI" — emissores de reporte semestral, aguardando normalização.
• adjust: "UNSPLIT" / "SPLIT_SPINOFF" — aguardando histórico de fatores de ajuste.
• Endpoints point-in-time (/point-in-time, /periods) — reservados para backtesting livre de viés de lookahead.
• Domínios de conteúdo de fundos e screener.