Consultar ações e FIIs da B3 em PHP: cotação, histórico e projeção

Mostrar a cotação de uma ação na tela é fácil quando o ativo é a PETR4 da vida. O problema aparece quando o usuário digita CPTS11, HFOF11 ou IRIM11 — os fundos imobiliários (FIIs) que muita gente carrega na carteira e que a maioria das APIs gratuitas internacionais simplesmente não cobre.

Este guia mostra como consultar qualquer ativo da B3 — ações e FIIs — em PHP, recuperar a série histórica de preços e montar uma projeção simples, usando a SDK do Falcon Data Hub.

Por que isso costuma dar trabalho

APIs como a Alpha Vantage cobrem bem ações americanas e até as grandes da B3 com sufixo .SA, mas a cobertura de FIIs brasileiros é fraca ou inexistente. Resultado: o PETR4 funciona, mas o CPTS11 volta vazio — e seu usuário fica sem dado justamente no ativo que ele acompanha todo dia.

O Falcon Data Hub resolve isso por baixo dos panos: quando a fonte primária não cobre o ativo, ele cai para uma fonte que enxerga ações e FIIs da B3. Para quem consome a API, é uma chamada só — o fallback é transparente.

Setup

composer require quantumtecnology/falcon-datahub-sdk

Configure o token uma vez (no boot da aplicação ou num service provider):

use QuantumTecnology\FalconDataHub\Falcon;
use QuantumTecnology\FalconDataHub\FalconConfig;

Falcon::configure(new FalconConfig(
    token: env('FALCON_TOKEN'),
));

Consulta básica

$result = Falcon::action()->search('CPTS11');

// $result->success  // bool
// $result->message  // string
// $result->data     // array com symbol, time_series, variations, predictions, analysis

if (! $result->success) {
    throw new RuntimeException($result->message);
}

$data = $result->data;

O mesmo código funciona para ação (PETR4) ou FII (CPTS11) — você não precisa saber de antemão o tipo do ativo.

O que vem na resposta

$data['symbol'];       // "CPTS11"
$data['time_series'];  // histórico diário: [{ date, data: { open, high, low, close, volume } }, ...]
$data['variations'];   // variação % de um dia para o outro: { "2026-05-29": 0.39, ... }
$data['analysis'];     // análise pronta: variação diária + projeção de preço

O bloco analysis é o atalho: ele já entrega a variação diária e uma projeção de preço dos próximos dias úteis, calculada por regressão linear sobre o fechamento — sem você precisar treinar nada.

Cotação atual e variação do dia

function cotacaoAtual(array $data): array
{
    // time_series vem ordenado do mais recente para o mais antigo
    $ultimo = $data['time_series'][0]['data'] ?? null;

    if (! $ultimo) {
        throw new RuntimeException('Sem histórico para este ativo.');
    }

    return [
        'symbol'     => $data['symbol'],
        'preco'      => (float) $ultimo['close'],
        'abertura'   => (float) $ultimo['open'],
        'maxima'     => (float) $ultimo['high'],
        'minima'     => (float) $ultimo['low'],
    ];
}

$cotacao = cotacaoAtual($result->data);
// ['symbol' => 'CPTS11', 'preco' => 7.64, 'abertura' => 7.64, ...]

Projeção de preço pronta

Em vez de implementar a regressão na mão, use o analysis->projection que a API já devolve:

$projecao = $data['analysis']['projection'] ?? null;

if ($projecao) {
    echo "Último fechamento: R$ {$projecao['last_close']}\n";
    echo "Tendência: R$ {$projecao['slope_per_day']}/dia\n";

    foreach ($projecao['forecast'] as $dia) {
        echo "{$dia['date']}: R$ {$dia['price']}\n";
    }
}

A saída é a projeção dos próximos dias úteis na mesma escala do preço — pronta para virar a linha tracejada de um gráfico no seu front.

> A projeção é uma estimativa estatística simples (regressão linear sobre o fechamento), útil para indicar tendência. Não é recomendação de investimento.

Montando um payload pronto para o front

Juntando tudo numa função que sua API interna pode expor:

function resumoAtivo(string $simbolo): array
{
    $result = Falcon::action()->search($simbolo);

    if (! $result->success) {
        throw new RuntimeException($result->message);
    }

    $data    = $result->data;
    $serie   = collect($data['time_series'] ?? []);
    $ultimo  = $serie->first()['data'] ?? [];

    return [
        'symbol'     => $data['symbol'],
        'preco'      => (float) ($ultimo['close'] ?? 0),
        'historico'  => $serie
            ->map(fn ($p) => [
                'date'  => $p['date'],
                'close' => (float) ($p['data']['close'] ?? 0),
            ])
            ->values()
            ->all(),
        'projecao'   => $data['analysis']['projection']['forecast'] ?? [],
    ];
}

Com isso o front recebe preço atual, histórico para o gráfico e projeção — tudo de uma chamada.

Limites a considerar

• Fonte com cota: a fonte primária de cotações tem limite diário no plano gratuito. O Falcon Data Hub controla esse orçamento e usa fallback, mas em rajadas de consultas a símbolos novos vale espaçar as chamadas.
• Cache: cotação diária muda uma vez por dia. Cachear o resultado por algumas horas (Redis, ou o cache do Laravel) economiza requisições e deixa sua tela instantânea.
• Ativos novos: a primeira consulta a um símbolo inédito popula o histórico e pode demorar um pouco mais; as próximas vêm do cache do Data Hub.

use Illuminate\Support\Facades\Cache;

$resumo = Cache::remember("ativo:{$simbolo}", now()->addHours(6),
    fn () => resumoAtivo($simbolo)
);

Conclusão

Consultar a B3 em PHP não precisa de uma conta de corretora nem de raspar site na unha. Com uma chamada — Falcon::action()->search() — você cobre ações e FIIs, recebe o histórico pronto para o gráfico e ainda ganha a projeção de preço de brinde. Adicione um cache de algumas horas e você tem um widget de cotações estável para o seu produto.