PrimuxDocs

Referência da API

API de Cotação de Moedas

Cotação de qualquer par de moedas e criptomoedas, escolhido por você a cada consulta, com compra, venda, máxima, mínima e variação.

Basehttps://dev-api.primux.cloud AuthBearer SUA_CHAVE FormatoJSON · UTF-8
URL base
https://dev-api.primux.cloud/v1/cotacoes

Visão geral

Você informa os pares (por exemplo USD-BRL,EUR-BRL,BTC-USD) e recebe a cotação de cada um. Serve para lojas, calculadoras, sites de notícias e sistemas financeiros.

  • Até 10 pares por consulta, em qualquer combinação que a fonte cote (moedas comuns e criptomoedas).
  • Cada cotação traz compra, venda, máxima e mínima do dia, variação e o horário da cotação.
  • /v1/cotacoes/pares lista todos os pares disponíveis, com o nome de cada um.
Os dados vêm de fontes públicas e são renovados no máximo a cada 30 minutos por item. Consultar mais vezes não traz dado mais novo, mas também não é problema: as respostas repetidas saem do dado já salvo.
Resposta 200
{
  "cotacoes": [
    {
      "par": "EUR-BRL",
      "origem": "EUR",
      "destino": "BRL",
      "nome": "Euro/Real Brasileiro",
      "compra": 6.4983,
      "venda": 6.5003,
      "maxima": 6.5309,
      "minima": 6.4449,
      "variacao": 0.0444,
      "variacao_pct": 0.687958,
      "cotado_em": "2026-11-19 18:16:46"
    }
  ],
  "atualizado_em": "2026-11-19T21:32:20Z",
  "desatualizado": false
}

Início rápido

  1. Contrate a API no console (menu APIs), escolha o plano e pague a fatura.
  2. Abra a sessão contratada e gere a chave de API. Ela aparece uma única vez: guarde-a em uma variável de ambiente do seu servidor.
  3. Faça a consulta enviando a chave no cabeçalho Authorization (Bearer) e use o JSON da resposta.

O exemplo consulta dólar, euro e bitcoin, confere o status e mostra compra e venda de cada par.

Exemplo completo
curl -i "https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD" \
  -H "Authorization: Bearer SUA_CHAVE"

Chave de API

Cada sessão contratada tem a sua própria chave. A chave identifica o plano, conta as consultas e vale só para esta API.

  • A chave aparece uma única vez, na hora de gerar. Se perder, gere outra: a anterior deixa de funcionar na hora.
  • Use a chave só no seu servidor (back-end). Nunca a coloque em aplicativo, página ou código que o público consiga ler.
  • Uma chave não abre outra API: a chave do clima não consulta cotações nem loterias (erro chave_de_outra_api).

Abrir o console e gerar a chave

Se vários sistemas seus precisam consultar a API, passe pelo seu servidor e guarde o resultado: assim você gasta menos consultas do plano.
Guardando a chave
export PRIMUX_COTACOES_CHAVE="COLE_AQUI_A_SUA_CHAVE"

Autenticação

Envie a chave em todas as requisições, no cabeçalho Authorization, no formato Bearer. Não há parâmetro de URL para a chave.

Sem a chave, com chave errada ou de outra API a resposta é 401 ou 403 com um código de erro estável. Muitas tentativas com chave inválida bloqueiam o endereço por um minuto.
Cabeçalho HTTP
Authorization: Bearer 0123456789abcdefghijklmnopqrstuvwxyz0123456789

Referência da API

Cotações

GET/v1/cotacoes

Devolve a cotação atual de um ou mais pares de moedas (até 10 por consulta). Você escolhe os pares: moedas comuns (USD-BRL, EUR-BRL) e criptomoedas (BTC-USD). A lista é devolvida em ordem alfabética de par.

Parâmetros da URL

pares texto obrigatório
Pares no formato ORIGEM-DESTINO separados por vírgula, de 1 a 10. Aceita também a barra (USD/BRL). Exemplo: USD-BRL,EUR-BRL,BTC-USD.
O par é ORIGEM-DESTINO: USD-BRL diz quantos reais vale 1 dólar. Para o contrário, peça BRL-USD, se a fonte cotar esse par (confira em /v1/cotacoes/pares).
Requisição
curl "https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "cotacoes": [
    {
      "par": "EUR-BRL",
      "origem": "EUR",
      "destino": "BRL",
      "nome": "Euro/Real Brasileiro",
      "compra": 6.4983,
      "venda": 6.5003,
      "maxima": 6.5309,
      "minima": 6.4449,
      "variacao": 0.0444,
      "variacao_pct": 0.687958,
      "cotado_em": "2026-11-19 18:16:46"
    }
  ],
  "atualizado_em": "2026-11-19T21:32:20Z",
  "desatualizado": false
}

Referência da API

Pares disponíveis

GET/v1/cotacoes/pares

Lista todos os pares de moedas que a fonte cota, com o nome de cada um. Use para montar telas de escolha ou conferir um par antes de consultar. A lista é renovada uma vez por dia.

Requisição
curl "https://dev-api.primux.cloud/v1/cotacoes/pares" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "pares": [
    { "par": "BTC-BRL", "nome": "Bitcoin/Real Brasileiro" },
    { "par": "EUR-BRL", "nome": "Euro/Real Brasileiro" },
    { "par": "USD-BRL", "nome": "Dólar Americano/Real Brasileiro" }
  ],
  "atualizado_em": "2026-11-19T00:05:11Z",
  "desatualizado": false
}

Referência da API

Sessão e plano

GET/v1/cotacoes/sessao

Mostra o nome da sessão, o plano, o estado, a validade e os limites do plano. Não conta como consulta nos limites de uso do plano, mas passa pela mesma autenticação.

Requisição
curl "https://dev-api.primux.cloud/v1/cotacoes/sessao" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "nome": "Meu site",
  "plano": "Cotações 5.000",
  "estado": "criada",
  "valido_ate": "2026-12-19T14:30:00Z",
  "limite_diario": 5000,
  "limite_por_minuto": 60
}

Referência da API

Uso

GET/v1/cotacoes/uso

Mostra quantas consultas a sessão fez hoje e no mês e, se o plano tem limite diário, quantas ainda restam hoje. O contador do dia zera à meia-noite.

Requisição
curl "https://dev-api.primux.cloud/v1/cotacoes/uso" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "data": "2026-11-19",
  "consultas_hoje": 128,
  "consultas_no_mes": 2410,
  "limite_diario": 5000,
  "restante_hoje": 4872
}

Campos da resposta

Todos os campos da resposta de sucesso. Campos marcados como "pode faltar" aparecem só quando a fonte informa o valor.

cotacoes[].par texto
Par consultado, no formato ORIGEM-DESTINO.
cotacoes[].origem texto
Moeda de origem (a que está sendo cotada).
cotacoes[].destino texto
Moeda de destino (a que expressa o valor).
cotacoes[].nome texto
Nome do par em português.
cotacoes[].compra número
Valor de compra: quanto o mercado paga pela moeda de origem, em unidades da moeda de destino.
cotacoes[].venda número
Valor de venda: quanto o mercado cobra pela moeda de origem, em unidades da moeda de destino.
cotacoes[].maxima número
Maior valor do dia.
cotacoes[].minima número
Menor valor do dia.
cotacoes[].variacao número
Variação do valor de compra em relação ao fechamento anterior.
cotacoes[].variacao_pct número
Variação em porcentagem.
cotacoes[].cotado_em texto
Data e hora da cotação na fonte.
atualizado_em texto
Quando o dado foi obtido da fonte (UTC).
desatualizado booleano
true quando a fonte falhou na renovação e este é o último dado salvo.

Atualização dos dados

O painel não consulta a fonte a cada chamada sua. Cada item (cidade, conjunto de pares ou concurso mais recente) é renovado no máximo a cada 30 minutos e guardado; as chamadas seguintes recebem o dado salvo.

  • atualizado_em diz quando o dado foi obtido da fonte (horário UTC).
  • Se a fonte estiver fora do ar na hora de renovar, você recebe o último dado salvo e desatualizado vem como true.
  • Se a fonte estiver fora e nunca houve dado salvo para o item, a resposta é 503 fonte_indisponivel.
Dado salvo (fonte fora do ar)
{
  …
  "atualizado_em": "2026-11-19T21:02:11Z",
  "desatualizado": true
}

Erros

Todo erro devolve um JSON com erro (código estável, para você testar no código) e mensagem (texto em português). Teste o código, não o texto.

StatusCódigoQuando acontece
400par_invalidoAlgum par não segue o formato ORIGEM-DESTINO (por exemplo USD-BRL).
400par_ausenteNenhum par informado no parâmetro pares.
400pares_demaisMais de 10 pares em uma consulta.
404par_inexistenteA fonte não cota algum dos pares. Veja a lista em /v1/cotacoes/pares.
401chave_invalidaChave ausente, errada ou de formato inválido.
403chave_de_outra_apiA chave é de outra API (por exemplo, a do clima usada nas cotações).
403sessao_suspensaA sessão está suspensa por falta de pagamento. Renove para voltar a usar.
403sessao_canceladaA sessão foi cancelada.
404rota_inexistenteA rota não existe. Confira o caminho nesta documentação.
429limite_por_minutoO limite de consultas por minuto do plano foi atingido. Espere alguns segundos.
429limite_diarioO limite de consultas do dia foi atingido. O contador zera à meia-noite.
429muitas_requisicoesMuitas requisições do mesmo endereço IP em pouco tempo.
429muitas_tentativasMuitas tentativas com chave inválida deste endereço. Espere um minuto.
503servico_indisponivelO serviço não respondeu agora. Tente de novo em instantes.
503fonte_indisponivelA fonte dos dados está fora do ar e ainda não há dado salvo para este item.
Resposta de erro
{
  "erro": "limite_diario",
  "mensagem": "Limite diário de envios do plano atingido. O contador zera à meia-noite."
}

Limites e boas práticas

  • Cada consulta bem-sucedida conta uma unidade no limite do plano (por minuto e por dia). Consultas recusadas por chave inválida não contam.
  • O limite por minuto usa uma janela deslizante; o limite diário zera à meia-noite (horário de Brasília).
  • Passou do limite: a resposta é 429 com limite_por_minuto ou limite_diario. Nada é cobrado a mais.
  • Veja o uso do dia e do mês em /uso e os limites do seu plano em /sessao.

Boas práticas

  • Guarde o resultado no seu sistema pelo mesmo tempo que a API guarda (até 30 minutos): você gasta menos consultas e responde mais rápido.
  • Defina um tempo máximo (timeout) de 10 a 15 segundos nas chamadas.
  • Trate 429 e 503 esperando e tentando de novo, sem repetir em laço apertado.
  • Confira desatualizado: se for true, mostre o dado mesmo assim e, se for importante, avise o usuário da hora em atualizado_em.

Tentar de novo com segurança

Para 429 e 503, espere e tente de novo com intervalo crescente (1, 2, 4, 8 segundos) e desista depois de poucas tentativas.

Tentar de novo com segurança
import os, time, requests

def consultar(url, tentativas=4):
    for n in range(tentativas):
        r = requests.get(url, headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"}, timeout=15)
        if r.status_code not in (429, 503):
            return r
        time.sleep(2 ** n)  # 1 s, 2 s, 4 s, 8 s
    return r

resposta = consultar("https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD")

Perguntas frequentes

Quais moedas posso consultar?

As que a fonte cota: consulte /v1/cotacoes/pares para ver a lista completa de pares, incluindo criptomoedas como BTC-USD.

Qual é a diferença entre compra e venda?

Compra é o valor que o mercado paga pela moeda de origem; venda é o valor que ele cobra. Para mostrar um preço ao público, a venda costuma ser a referência.

Posso pedir o par ao contrário (BRL-USD)?

Só se a fonte cotar esse par. Se não existir, a resposta é 404 par_inexistente; nesse caso, calcule 1 dividido pelo valor do par USD-BRL.

Com que frequência a cotação muda?

O painel renova cada conjunto de pares no máximo a cada 30 minutos. O horário da cotação na fonte está em cotado_em.