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.
https://dev-api.primux.cloud AuthBearer SUA_CHAVE FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/loteriasVisã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).
{
"loterias": [
{ "slug": "megasena", "nome": "Mega-Sena" },
{ "slug": "quina", "nome": "Quina" },
{ "slug": "lotofacil", "nome": "Lotofácil" }
]
}Início rápido
- Contrate a API no console (menu APIs), escolha o plano e pague a fatura.
- 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.
- 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.
curl -i "https://dev-api.primux.cloud/v1/loterias/megasena" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/loterias/megasena');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_LOTERIAS_CHAVE')],
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$dados = json_decode($corpo, true);
if ($status !== 200) {
// erro, mensagem: veja a seção Erros
exit('Erro ' . $status . ': ' . ($dados['mensagem'] ?? 'sem resposta') . PHP_EOL);
}
if ($dados['desatualizado']) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
echo 'Concurso ' . $dados['concurso'] . ' (' . $dados['data'] . '): ' . implode(' - ', $dados['dezenas']) . PHP_EOL;const resposta = await fetch('https://dev-api.primux.cloud/v1/loterias/megasena', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_LOTERIAS_CHAVE}` },
});
const dados = await resposta.json();
if (!resposta.ok) {
// dados.erro e dados.mensagem: veja a seção Erros
throw new Error(`Erro ${resposta.status}: ${dados.mensagem}`);
}
if (dados.desatualizado) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
console.log(`Concurso ${dados.concurso} (${dados.data}): ${dados.dezenas.join(' - ')}`);import os, sys, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/loterias/megasena",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_LOTERIAS_CHAVE']}"},
timeout=15,
)
dados = resposta.json()
if resposta.status_code != 200:
# dados["erro"] e dados["mensagem"]: veja a seção Erros
sys.exit(f"Erro {resposta.status_code}: {dados.get('mensagem')}")
if dados["desatualizado"]:
pass # a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
print(f"Concurso {dados['concurso']} ({dados['data']}): {' - '.join(dados['dezenas'])}")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
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.
Authorization: Bearer 0123456789abcdefghijklmnopqrstuvwxyz0123456789Referê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.
curl "https://dev-api.primux.cloud/v1/loterias" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/loterias');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_LOTERIAS_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/loterias', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_LOTERIAS_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/loterias",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_LOTERIAS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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
concursointeiro- Número do concurso. Sem este parâmetro (ou com o valor "ultimo"), devolve o mais recente.
Loterias aceitas
| Identificador | Nome |
|---|---|
megasena | Mega-Sena |
quina | Quina |
lotofacil | Lotofácil |
lotomania | Lotomania |
timemania | Timemania |
duplasena | Dupla Sena |
diadesorte | Dia de Sorte |
supersete | Super Sete |
maismilionaria | +Milionária |
federal | Federal |
curl "https://dev-api.primux.cloud/v1/loterias/megasena" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/loterias/megasena');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_LOTERIAS_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/loterias/megasena', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_LOTERIAS_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/loterias/megasena",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_LOTERIAS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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.
curl "https://dev-api.primux.cloud/v1/loterias/sessao" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/loterias/sessao');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_LOTERIAS_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/loterias/sessao', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_LOTERIAS_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/loterias/sessao",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_LOTERIAS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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.
curl "https://dev-api.primux.cloud/v1/loterias/uso" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/loterias/uso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_LOTERIAS_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/loterias/uso', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_LOTERIAS_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/loterias/uso",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_LOTERIAS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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.
loteriatexto- Identificador da loteria (ex.: megasena).
concursointeiro- Número do concurso.
datatexto- Data do sorteio (DD/MM/AAAA).
localtexto pode faltar- Local onde o sorteio foi realizado.
dezenaslista de textos- Dezenas sorteadas, em ordem crescente, como texto (ex.: "06").
dezenasOrdemSorteiolista de textos- Dezenas na ordem em que foram sorteadas.
trevoslista de textos pode faltar- Trevos sorteados (só na +Milionária).
timeCoracaotexto pode faltar- Time do Coração sorteado (só na Timemania).
mesSortetexto pode faltar- Mês da Sorte sorteado (só no Dia de Sorte).
premiacoeslista- Premiação por faixa: descricao, faixa, ganhadores e valorPremio.
acumuloubooleano- true se nenhuma aposta acertou a faixa principal e o prêmio acumulou.
proximoConcursointeiro pode faltar- Número do próximo concurso.
dataProximoConcursotexto pode faltar- Data do próximo sorteio (DD/MM/AAAA).
valorArrecadadonúmero pode faltar- Total arrecadado no concurso, em reais.
valorAcumuladoProximoConcursonúmero pode faltar- Valor acumulado para o próximo concurso, em reais.
valorEstimadoProximoConcursonúmero pode faltar- Estimativa de prêmio do próximo concurso, em reais.
atualizado_emtexto- Quando o dado foi obtido da fonte (UTC).
desatualizadobooleano- 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.
{
…
"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.
| Status | Código | Quando acontece |
|---|---|---|
| 404 | loteria_inexistente | A loteria não existe. Veja a lista em /v1/loterias. |
| 400 | concurso_invalido | O número do concurso é inválido. |
| 404 | concurso_inexistente | Esse concurso não existe para a loteria. |
| 401 | chave_invalida | Chave ausente, errada ou de formato inválido. |
| 403 | chave_de_outra_api | A chave é de outra API (por exemplo, a do clima usada nas cotações). |
| 403 | sessao_suspensa | A sessão está suspensa por falta de pagamento. Renove para voltar a usar. |
| 403 | sessao_cancelada | A sessão foi cancelada. |
| 404 | rota_inexistente | A rota não existe. Confira o caminho nesta documentação. |
| 429 | limite_por_minuto | O limite de consultas por minuto do plano foi atingido. Espere alguns segundos. |
| 429 | limite_diario | O limite de consultas do dia foi atingido. O contador zera à meia-noite. |
| 429 | muitas_requisicoes | Muitas requisições do mesmo endereço IP em pouco tempo. |
| 429 | muitas_tentativas | Muitas tentativas com chave inválida deste endereço. Espere um minuto. |
| 503 | servico_indisponivel | O serviço não respondeu agora. Tente de novo em instantes. |
| 503 | fonte_indisponivel | A fonte dos dados está fora do ar e ainda não há dado salvo para este item. |
{
"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.
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.