API de Cotações

Histórico de cotações da B3 nos períodos: diário, semanal e mensal. Disponível no plano Desenvolvedor.

Autenticação

Toda requisição precisa da sua chave no cabeçalho X-Api-Key. Gere e revogue chaves na tela API de Cotações da sua conta.

curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/PETR4/mensal?inicio=2025-01-01"

A chave em claro aparece uma única vez, no momento em que é criada. Guarde-a em local seguro: se perder, revogue e gere outra. Nunca coloque a chave em código publicado nem em aplicativo distribuído ao usuário final, ela dá acesso à sua cota.

Limites

Limite	Valor
Requisições por minuto, por chave	150
Requisições simultâneas, por chave	10; as excedentes aguardam em fila
Requisições por dia, por chave	5.000, renovadas à meia-noite (horário de Brasília)
Período por consulta	diária: 1 ano · semanal: 10 anos · mensal: 20 anos
Itens por página	100 por padrão, máximo 500
Códigos por consulta em lote	20
Chaves ativas por conta	3

Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Ao estourar um limite a resposta é 429, com Retry-After em segundos.

Endpoints

GET/v1/cotacoes/{codigo}/diaria

Parâmetro	Descrição
`inicio`	Data inicial (`AAAA-MM-DD`). Padrão: um ano atrás.
`fim`	Data final. Padrão: hoje. Data futura é trazida para hoje.
`pagina`	Página, começando em 1.
`tamanho`	Itens por página, de 1 a 500.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/PETR4/diaria?inicio=2026-08-01&fim=2026-08-05"

{
    "codigo": "PETR4",
    "codigos": null,
    "periodicidade": "diaria",
    "inicio": "2026-08-01T00:00:00",
    "fim": "2026-08-05T00:00:00",
    "total": 3,
    "pagina": 1,
    "tamanho": 100,
    "itens": [
        { "codigo": "PETR4", "data": "2026-08-03T00:00:00", "precoFechamento": 42.800000 },
        { "codigo": "PETR4", "data": "2026-08-04T00:00:00", "precoFechamento": 42.420000 },
        { "codigo": "PETR4", "data": "2026-08-05T00:00:00", "precoFechamento": 42.220000 }
    ]
}

GET/v1/cotacoes/{codigo}/semanal

Fechamento de cada semana. A data de cada item é a segunda-feira que inicia a semana.

Parâmetro	Descrição
`inicio`	Data inicial (`AAAA-MM-DD`). Padrão: um ano atrás.
`fim`	Data final. Padrão: hoje. Data futura é trazida para hoje.
`pagina`	Página, começando em 1.
`tamanho`	Itens por página, de 1 a 500.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/PETR4/semanal?inicio=2026-08-01"

{
    "codigo": "PETR4",
    "codigos": null,
    "periodicidade": "semanal",
    "inicio": "2026-08-01T00:00:00",
    "fim": "2026-08-31T00:00:00",
    "total": 5,
    "pagina": 1,
    "tamanho": 100,
    "itens": [
        { "codigo": "PETR4", "data": "2026-08-03T00:00:00", "precoFechamento": 41.460000 },
        { "codigo": "PETR4", "data": "2026-08-10T00:00:00", "precoFechamento": 42.080000 },
        { "codigo": "PETR4", "data": "2026-08-17T00:00:00", "precoFechamento": 44.370000 },
        { "codigo": "PETR4", "data": "2026-08-24T00:00:00", "precoFechamento": 43.150000 },
        { "codigo": "PETR4", "data": "2026-08-31T00:00:00", "precoFechamento": 44.910000 }
    ]
}

GET/v1/cotacoes/{codigo}/mensal

Fechamento de cada mês. A data de cada item é o primeiro dia do mês.

Parâmetro	Descrição
`inicio`	Data inicial (`AAAA-MM-DD`). Padrão: um ano atrás.
`fim`	Data final. Padrão: hoje. Data futura é trazida para hoje.
`pagina`	Página, começando em 1.
`tamanho`	Itens por página, de 1 a 500.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/PETR4/mensal?inicio=2026-07-01"


{
    "codigo": "PETR4",
    "codigos": null,
    "periodicidade": "mensal",
    "inicio": "2026-07-01T00:00:00",
    "fim": "2026-09-18T00:00:00",
    "total": 3,
    "pagina": 1,
    "tamanho": 100,
    "itens": [
        { "codigo": "PETR4", "data": "2026-07-01T00:00:00", "precoFechamento": 43.360000 },
        { "codigo": "PETR4", "data": "2026-08-01T00:00:00", "precoFechamento": 44.910000 },
        { "codigo": "PETR4", "data": "2026-09-01T00:00:00", "precoFechamento": 48.690000 }
    ]
}

GET/v1/cotacoes/{codigo}/atual

Cotação mais recente do ativo. O campo atualizado diz quando o preço foi obtido. A atualização ocorre a cada 15 minutos.

Na primeira chamada de um ativo que ainda não está sendo acompanhado, a resposta pode trazer a cotação de fechamento do dia anterior. Essa chamada passa a acompanhar o ativo, e as seguintes devolvem o preço do dia assim que ele for atualizado.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/PETR4/atual"


    { "codigo": "PETR4", "preco": 48.69, "atualizado": "2026-09-18T12:20:26.8987561" }

    { "codigo": "PETR4", "preco": 44.91, "atualizado": "2026-08-31T00:00:00"  }

GET/v1/cotacoes/{periodicidade}

Consulta em lote de até 20 códigos. periodicidade aceita diaria, semanal ou mensal.

Parâmetro	Descrição
`codigos`	Códigos dos ativos separados por virgula.
`inicio`	Data inicial (`AAAA-MM-DD`). Padrão: um ano atrás.
`fim`	Data final. Padrão: hoje. Data futura é trazida para hoje.
`pagina`	Página, começando em 1.
`tamanho`	Itens por página, de 1 a 500.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/cotacoes/mensal?codigos=PETR4,VALE3&inicio=2026-07-01"


    {
    "codigo": null,
    "codigos": [
        "PETR4",
        "VALE3"
    ],
    "periodicidade": "mensal",
    "inicio": "2026-07-01T00:00:00",
    "fim": "2026-09-18T00:00:00",
    "total": 6,
    "pagina": 1,
    "tamanho": 100,
    "itens": [
        { "codigo": "PETR4", "data": "2026-07-01T00:00:00", "precoFechamento": 43.360000 },
        { "codigo": "PETR4", "data": "2026-08-01T00:00:00", "precoFechamento": 44.910000 },
        { "codigo": "PETR4", "data": "2026-09-01T00:00:00", "precoFechamento": 48.690000 },
        { "codigo": "VALE3", "data": "2026-07-01T00:00:00", "precoFechamento": 76.310000 },
        { "codigo": "VALE3", "data": "2026-08-01T00:00:00", "precoFechamento": 78.180000 },
        { "codigo": "VALE3", "data": "2026-09-01T00:00:00", "precoFechamento": 73.730000 }
    ]
}

GET/v1/ativos

Códigos com histórico disponível.

Parâmetro	Descrição
`busca`	Retorna todos os códigos que contém o texto informado.
`pagina`	Página, começando em 1.
`tamanho`	Itens por página, de 1 a 500.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/ativos?busca=PETR4"


    {
    "total": 5,
    "pagina": 1,
    "tamanho": 100,
    "itens": [
        "PETR4",
        "PETR4F",
        "PETR4Q",
        "PETR4S",
        "PETR4T"
    ]
}

GET/v1/conta/uso

Consumo do dia da chave usada na requisição, com os limites vigentes e a data de expiração da chave.


    curl -H "X-Api-Key: SUA_CHAVE" "https://api.carteirainvest.com/v1/conta/uso"


{
    "nome": "TesteCarteiraInvest",
    "data": "2026-09-18T00:00:00",
    "chamadas": 35,
    "limiteDiario": 5000,
    "restantes": 4965,
    "limitePorMinuto": 150,
    "dataExpiracao": "2027-09-16T10:14:33.6256424"
}

GET/health

Disponibilidade da API. Não exige chave.


    curl -H "" "https://api.carteirainvest.com/health"


{
    "status": "ok"
}

Erros

Os erros seguem RFC 7807, no tipo application/problem+json.

Status	Quando acontece
400	Parâmetro inválido: código fora do formato, período acima do máximo, paginação fora da faixa.
401	Chave ausente, inválida, revogada ou expirada.
402	Chave válida, mas a assinatura não está no plano Desenvolvedor.
404	Código sem histórico disponível.
429	Limite por minuto, cota diária ou requisições simultâneas da chave excedidos. Veja `Retry-After`.
503	Consulta acima do tempo limite (reduza o período e tente de novo) ou API no limite de requisições simultâneas (tente de novo após o `Retry-After`).

{
  "type": "about:blank",
  "title": "Parâmetro inválido",
  "status": 400,
  "detail": "O período máximo por consulta na periodicidade diaria é de 1 ano. Divida a consulta em intervalos menores.",
  "instance": "/v1/cotacoes/PETR4/diaria"
}

Boas práticas

Histórico fechado não muda: guarde no seu lado e consulte só o período novo.
Para acompanhar vários ativos, prefira uma chamada em lote a várias chamadas individuais para economizar sua cota.
Trate 429 e 503 respeitando o Retry-After em vez de repetir a chamada imediatamente.
Mantenha no máximo 10 requisições em andamento por chave: acima disso as chamadas só esperam na fila.
A cotação atual tem até 15 minutos de defasagem: consultar com intervalo menor que isso devolve o mesmo preço e gasta cota.