Como consultar fundamentos da B3 em Python com o Crivo

Para consultar fundamentos de uma ação pelo Crivo, envie um GET para /fundamentus/{ticker} com sua chave no header X-API-Key. A resposta reúne os indicadores e a proveniência necessária para entender seus períodos. O número sem o período é uma informação incompleta.

O exemplo usa TOTS3 e foi executado em 11 de outubro de 2026. A resposta tinha data contábil de 30 de junho e lucro acumulado de janeiro a junho. A consulta feita em outubro não transformou o balanço em um balanço de outubro.

Prepare o acesso sem colocar a chave no código

Você precisa de uma chave válida e do acesso comercial exigido pela API. Criar uma conta ou uma chave não certifica, por si só, uma assinatura ativa. Consulte as condições atuais na documentação do Crivo antes de integrar.

Guarde o segredo na variável de ambiente CRIVO_API_KEY do processo que executará a consulta. Não o coloque na URL, no repositório ou em uma planilha distribuída. O exemplo usa apenas a biblioteca padrão do Python e define um timeout de 30 segundos.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, build_opener, HTTPRedirectHandler

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, *args):
        return None

key = os.environ["CRIVO_API_KEY"].strip()
if not key:
    raise ValueError("CRIVO_API_KEY está vazia")
client = build_opener(NoRedirect())

def get_json(path):
    req = Request("https://api.crivo.ai" + path,
                  headers={"X-API-Key": key, "Accept": "application/json"})
    try:
        with client.open(req, timeout=30) as response:
            return json.load(response)
    except HTTPError as error:
        raise RuntimeError(f"Consulta interrompida: HTTP {error.code}") from None

data = get_json("/fundamentus/TOTS3")
assert data["ticker"] == "TOTS3" and data["currency"] == "BRL"
result = {
    "referencia_contabil": data["as_of_date"],
    "lucro_atribuivel_brl": data["profitability"]["net_profit"],
    "roe_razao": data["profitability"]["roe"],
    "intervalos": data["provenance"]["period_intervals"],
}
print(json.dumps(result, ensure_ascii=False, indent=2))

O cliente recusa redirecionamentos para evitar encaminhar a credencial a outro destino. Ele encerra em erro HTTP; não transforma falha de autenticação ou limite em um conjunto vazio de fundamentos.

Confira a empresa antes de interpretar os números

O ticker é a entrada da consulta, mas a identidade da companhia precisa ser verificável. Para descobrir ações, use /stocks?search=TOTS3. Na consulta realizada, o catálogo identificou TOTVS e código CVM 19992. O snapshot de fundamentos trouxe a mesma identidade em sua proveniência.

Para uma integração com muitas ações, preserve essa identificação. Ações ordinárias e preferenciais podem representar o mesmo emissor. Contar tickers como se cada um fosse uma empresa duplica negócios em amostras e rankings.

Os valores monetários do snapshot estão em reais, não em milhões. A tabela faz a conversão para leitura. O lucro, a receita e o EBITDA usados aqui pertencem ao semestre; patrimônio é um saldo de fechamento. Não somamos saldos com fluxos nem chamamos o lucro semestral de lucro trimestral.

Use provenance para saber o que a resposta mede

O campo as_of_date identifica a referência contábil. Os intervalos de provenance mostram o início e o fim de cada demonstração e, quando disponível, a semântica acumulada. A data de montagem da resposta, computed_at, informa outra coisa: quando o serviço produziu aquele JSON.

Confira também a atribuição do lucro. Neste snapshot, net_profit é R$ 917,352 milhões, atribuíveis à controladora. O lucro consolidado total é R$ 920,532 milhões. O estado de atribuição retornado era consistente; isso ajuda a rastrear a conta, mas não substitui a leitura da demonstração original para uma análise financeira.

Percentuais são razões decimais. O ROE retornado de aproximadamente 0,1681 equivale a 16,81%. A fórmula desse snapshot usa o lucro semestral sobre o patrimônio atribuível à controladora no fechamento. Não o apresente como ROE anualizado ou calculado sobre patrimônio médio.

Preserve null e trate cada erro pelo significado

Um campo null significa ausência do valor nesse contrato ou captura. Substituí-lo por zero altera a interpretação: dívida desconhecida passaria a parecer dívida inexistente; um múltiplo indisponível poderia entrar como “o mais barato” de um ranking.

HTTP 401 indica problema de autenticação. Um 403 pode indicar acesso comercial indisponível; confira o código da resposta. Em 429, respeite o limite e o Retry-After quando informado. Falha de rede ou 5xx pede diagnóstico e uma política de repetição limitada, sem assumir que a última consulta funcionou.

O passo seguinte é salvar a resposta com o horário da consulta e calcular sobre essa cópia. Isso permite reproduzir o relatório depois que o preço ou a demonstração forem atualizados. A qualidade da integração está em preservar identidade, unidade e período junto do número que será mostrado ao usuário.