API v1

API do RifaHub

Venda números das suas rifas pelo seu próprio site, app ou sistema. Você cria o pedido, mostra o PIX para o cliente e recebe um webhook quando o pagamento cai.

Criar chave de API

Autenticação

Envie a chave no cabeçalho Authorization. Guarde a chave só no servidor. Limite de 120 requisições por minuto por chave.

Authorization: Bearer rh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Valores em dinheiro vêm na menor unidade da moeda: 1990 em BRL é R$ 19,90. Datas em ISO 8601 (UTC). Erros seguem o formato abaixo.

{ "error": { "code": "numbers_taken", "message": "Os números 0042 acabaram de ser reservados..." } }

Rifas

GET/raffles

Lista as rifas da sua conta com vendidos, reservados e disponíveis. Filtro opcional: ?status=active.

curl https://rifahub.digital/api/v1/raffles -H "Authorization: Bearer $RIFAHUB_KEY"

GET/raffles/{slug}sem chave

Dados públicos de uma rifa publicada: preço, prêmios, pacotes e disponibilidade. Pode ser chamado do navegador (CORS liberado).

GET/raffles/{slug}/numberssem chave

Números pagos e reservados, para montar um seletor de números próprio.

Pedidos

POST/orders

Reserva números e gera o pagamento. Informe quantity para números aleatórios ou numbers para escolher. As regras antifraude e o limite por comprador da rifa valem aqui também.

curl -X POST https://rifahub.digital/api/v1/orders \
  -H "Authorization: Bearer $RIFAHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "raffle": "iphone-16-pro-max",
    "quantity": 10,
    "buyer": { "name": "Maria Souza", "phone": "11988887777", "email": "maria@email.com", "ip": "177.10.20.30" }
  }'

buyer.ip é opcional: mande o IP de quem está comprando no seu site para as regras antifraude por IP. Sem ele, só valem as regras por telefone e CPF.

Resposta 201:

{
  "data": {
    "id": "cmu4...",
    "status": "pending",
    "raffle": "iphone-16-pro-max",
    "quantity": 10,
    "numbers": [42, 177, 908, ...],
    "currency": "BRL",
    "amount": 900,
    "expires_at": "2026-09-17T02:30:00.000Z",
    "payment": {
      "method": "pix",
      "pix_code": "00020126...",
      "pix_qr_code_base64": "iVBORw0KGgo...",
      "checkout_url": null,
      "test_mode": false
    },
    "order_url": "https://rifahub.digital/r/iphone-16-pro-max/pedido/cmu4..."
  }
}

Códigos de erro comuns: raffle_not_found (404), forbidden (403), numbers_taken (409), raffle_closed, below_minimum, above_maximum, blocked_by_risk_rules, sold_out, payments_unavailable (422).

GET/orders/{id}

Status atual, números e cotas premiadas ganhas no pedido.

GET/orders

Lista pedidos. Filtros: raffle, status, limit (até 100) e cursor (use next_cursor da resposta anterior).

POST/orders/{id}/cancel

Cancela um pedido que ainda aguarda pagamento e libera os números.

Webhooks

Cadastre endpoints no painel. Cada evento chega como POST com o corpo abaixo e três cabeçalhos: RifaHub-Event, RifaHub-Delivery e RifaHub-Signature.

{
  "id": "entrega_id",
  "event": "order.paid",
  "created_at": "2026-09-17T01:23:23.225Z",
  "data": { "order": { "id": "...", "status": "paid", "numbers": [...], "amount": 900, ... } }
}

order.created	Pedido criado
order.paid	Pedido pago
order.expired	Pedido expirado
order.cancelled	Pedido cancelado
order.refunded	Pedido estornado
raffle.status_changed	Status da rifa alterado
draw.completed	Sorteio realizado
payout.paid	Saque pago
payout.rejected	Saque recusado

Validando a assinatura

O cabeçalho tem o formato t=timestamp,v1=assinatura. Calcule HMAC SHA-256 de "timestamp.corpo_bruto" com o segredo do endpoint e compare. Recuse eventos com mais de 5 minutos.

import crypto from "node:crypto";

function assinaturaValida(corpoBruto, cabecalho, segredo) {
  const partes = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")));
  const esperado = crypto.createHmac("sha256", segredo).update(`${partes.t}.${corpoBruto}`).digest("hex");
  const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
  return recente && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1));
}

Responda com qualquer status 2xx em até 10 segundos. Sem isso, reenviamos em 1 min, 5 min, 30 min, 2 h e 12 h.

Sem programar: incorporação

Se você só quer vender dentro do seu site, cole este código. A compra inteira acontece dentro do quadro.

<div data-rifahub="iphone-16-pro-max" data-ref="codigo-do-afiliado"></div>
<script src="https://rifahub.digital/embed.js" async></script>