API e webhooks

Acesso restrito

A API externa está desabilitada por padrão nesta versão e será liberada gradualmente. Esta documentação descreve o contrato vigente.

Autenticação

Crie uma credencial em Integrações e API na sua conta. A chave tem o formato nmr_<prefixo>_<segredo>, é exibida uma única vez e deve ser enviada no cabeçalho:

Authorization: Bearer nmr_xxxxxxxxxx_...

Cada operação exige um escopo; operações sem escopo de API (conta, cobrança, administração e ações sensíveis) recusam chaves. Credenciais podem expirar e ser revogadas a qualquer momento.

Escopos

Escopo	Permite	Exemplos
`lotteries:read`	Modalidades, regras, preços e probabilidades	GET /api/v1/lotteries, /lotteries/{slug}, /probabilities
`draws:read`	Resultados oficiais validados	GET /api/v1/lotteries/{slug}/draws, /latest, /{número}
`stats:read`	Estatísticas	GET /api/v1/stats/{slug}, /public/stats/{slug}
`generator:write`	Gerar jogos (consome a cota do plano)	POST /api/v1/generator/runs
`wallets:read`	Carteiras e jogos	GET /api/v1/wallets, /games
`wallets:write`	Criar e alterar jogos	POST /api/v1/games, PATCH /games/{id}
`checks:read`	Conferências	GET /api/v1/games/{id}/checks, POST /checks
`simulations:write`	Simulações (consome a cota do plano)	POST /api/v1/lab/projects/{id}/simulations
`webhooks:manage`	Gerenciar webhooks	/api/v1/integrations/webhooks

Limites, paginação e erros

Limite por credencial (padrão 120 requisições/minuto), informado em X-RateLimit-Limit e X-RateLimit-Remaining; ao exceder, resposta 429 com Retry-After.
Operações que geram jogos ou simulações consomem as cotas do plano da conta.
Listas paginadas por page e pageSize (máximo 100) ou cursor quando indicado.
Erros sempre no formato { "error": { "code", "message", "requestId" } }; informe o requestId ao suporte.

Versionamento e compatibilidade

A versão faz parte do caminho (/api/v1). Dentro de uma versão, apenas mudanças compatíveis: novos campos, novos endpoints e novos valores opcionais. Remoções ou mudanças de significado geram uma nova versão, com aviso prévio de no mínimo 90 dias e período de convivência.

Contrato OpenAPI: /api/v1/openapi.json · referência interativa: /api/docs.

Webhooks

Eventos: draw.published, games.checked, import.completed, report.ready e simulation.completed. Os envios são POST JSON com { id, type, createdAt, data } e os cabeçalhos Numers-Event, Numers-Event-Id, Numers-Delivery e Numers-Signature.

Responda 2xx em até 10 segundos; processe de forma assíncrona.
Entregas podem se repetir: use Numers-Event-Id para idempotência.
Falhas são reenviadas com intervalos crescentes (até 8 tentativas em cerca de 2 dias); após 15 falhas seguidas o endpoint é desativado e pode ser reativado na sua conta.
Somente HTTPS públicos são aceitos; destinos internos e privados são bloqueados.

Verifique a assinatura (HMAC-SHA256 de <t>.<corpo> com o segredo whsec_…) e rejeite carimbos de tempo antigos:

import { createHmac, timingSafeEqual } from 'node:crypto';

// corpo: texto bruto recebido (não reserializar o JSON)
export function verificarNumers(segredo, corpo, cabecalho, toleranciaSeg = 300) {
  const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.split('=')));
  const t = Number(partes.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranciaSeg) return false;
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpo}`).digest();
  const recebido = Buffer.from(partes.v1 ?? '', 'hex');
  return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
}