PrimuxDocs

Referência da API

API de Loterias

Resultados oficiais da Mega-Sena, Quina, Lotofácil e de todas as outras loterias da Caixa, do concurso mais recente ou de qualquer concurso antigo.

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

Visão geral

Você escolhe a loteria na rota e recebe o resultado: dezenas, premiação por faixa, se acumulou e a estimativa do próximo concurso. Serve para sites de notícias, rádios, aplicativos e canais de mensagem.

  • Dez modalidades: Mega-Sena, Quina, Lotofácil, Lotomania, Timemania, Dupla Sena, Dia de Sorte, Super Sete, +Milionária e Federal.
  • Sem parâmetro vem o concurso mais recente; com concurso=N vem o concurso que você pedir, desde o primeiro.
  • As dezenas vêm na ordem crescente (dezenas) e na ordem em que foram sorteadas (dezenasOrdemSorteio).
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
{
  "loterias": [
    { "slug": "megasena", "nome": "Mega-Sena" },
    { "slug": "quina", "nome": "Quina" },
    { "slug": "lotofacil", "nome": "Lotofácil" }
  ]
}

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 o último resultado da Mega-Sena, confere o status e mostra o concurso, a data e as dezenas.

Exemplo completo
curl -i "https://dev-api.primux.cloud/v1/loterias/megasena" \
  -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_LOTERIAS_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

Lista das loterias

GET/v1/loterias

Lista as modalidades da Caixa que a API serve, com o identificador (slug) que vai na rota do resultado.

Requisição
curl "https://dev-api.primux.cloud/v1/loterias" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "loterias": [
    { "slug": "megasena", "nome": "Mega-Sena" },
    { "slug": "quina", "nome": "Quina" },
    { "slug": "lotofacil", "nome": "Lotofácil" }
  ]
}

Referência da API

Resultado de uma loteria

GET/v1/loterias/{loteria}

Devolve o resultado do concurso mais recente da loteria ou, com o parâmetro concurso, de um concurso específico. Traz as dezenas (na ordem crescente e na ordem do sorteio), a premiação por faixa, se acumulou e a previsão do próximo concurso. Concursos antigos não mudam e ficam salvos por mais tempo.

Parâmetros da URL

concurso inteiro
Número do concurso. Sem este parâmetro (ou com o valor "ultimo"), devolve o mais recente.

Loterias aceitas

IdentificadorNome
megasenaMega-Sena
quinaQuina
lotofacilLotofácil
lotomaniaLotomania
timemaniaTimemania
duplasenaDupla Sena
diadesorteDia de Sorte
superseteSuper Sete
maismilionaria+Milionária
federalFederal
Requisição
curl "https://dev-api.primux.cloud/v1/loterias/megasena" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "loteria": "megasena",
  "concurso": 3087,
  "data": "17/11/2026",
  "local": "ESPAÇO DA SORTE em SÃO PAULO, SP",
  "dezenas": ["06", "10", "23", "35", "41", "52"],
  "dezenasOrdemSorteio": ["23", "06", "52", "10", "41", "35"],
  "trevos": [],
  "timeCoracao": null,
  "mesSorte": null,
  "premiacoes": [
    { "descricao": "6 acertos", "faixa": 1, "ganhadores": 0, "valorPremio": 0 },
    { "descricao": "5 acertos", "faixa": 2, "ganhadores": 41, "valorPremio": 52310.77 },
    { "descricao": "4 acertos", "faixa": 3, "ganhadores": 3012, "valorPremio": 1021.43 }
  ],
  "acumulou": true,
  "proximoConcurso": 3088,
  "dataProximoConcurso": "19/11/2026",
  "valorArrecadado": 42979824,
  "valorAcumuladoProximoConcurso": 32125746.68,
  "valorEstimadoProximoConcurso": 40000000,
  "atualizado_em": "2026-11-19T21:32:20Z",
  "desatualizado": false
}

Referência da API

Sessão e plano

GET/v1/loterias/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/loterias/sessao" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "nome": "Meu site",
  "plano": "Loterias 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/loterias/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/loterias/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.

loteria texto
Identificador da loteria (ex.: megasena).
concurso inteiro
Número do concurso.
data texto
Data do sorteio (DD/MM/AAAA).
local texto pode faltar
Local onde o sorteio foi realizado.
dezenas lista de textos
Dezenas sorteadas, em ordem crescente, como texto (ex.: "06").
dezenasOrdemSorteio lista de textos
Dezenas na ordem em que foram sorteadas.
trevos lista de textos pode faltar
Trevos sorteados (só na +Milionária).
timeCoracao texto pode faltar
Time do Coração sorteado (só na Timemania).
mesSorte texto pode faltar
Mês da Sorte sorteado (só no Dia de Sorte).
premiacoes lista
Premiação por faixa: descricao, faixa, ganhadores e valorPremio.
acumulou booleano
true se nenhuma aposta acertou a faixa principal e o prêmio acumulou.
proximoConcurso inteiro pode faltar
Número do próximo concurso.
dataProximoConcurso texto pode faltar
Data do próximo sorteio (DD/MM/AAAA).
valorArrecadado número pode faltar
Total arrecadado no concurso, em reais.
valorAcumuladoProximoConcurso número pode faltar
Valor acumulado para o próximo concurso, em reais.
valorEstimadoProximoConcurso número pode faltar
Estimativa de prêmio do próximo concurso, em reais.
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
404loteria_inexistenteA loteria não existe. Veja a lista em /v1/loterias.
400concurso_invalidoO número do concurso é inválido.
404concurso_inexistenteEsse concurso não existe para a loteria.
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_LOTERIAS_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/loterias")

Perguntas frequentes

Quais loterias existem?

Chame /v1/loterias para a lista. Os identificadores são megasena, quina, lotofacil, lotomania, timemania, duplasena, diadesorte, supersete, maismilionaria e federal.

Como pego um concurso antigo?

Use o parâmetro concurso, por exemplo /v1/loterias/quina?concurso=6000. Concursos que ainda não aconteceram devolvem 404 concurso_inexistente.

Por que as dezenas são textos?

Para manter o zero à esquerda ("06"). Na Federal, cada item é um bilhete de 6 dígitos.

Quando o resultado novo aparece?

Logo depois do sorteio, no máximo 30 minutos depois que a fonte o publica. Compare concurso e data com os do dia do sorteio.