API da rifa

Um site parceiro usa esta API para publicar a campanha, emitir o bilhete e mostrar o sorteio. A compra é pública. A chave do parceiro fica no servidor desse site e serve para abrir a campanha e ler as vendas.

Endereço

Nesta máquina a base é http://127.0.0.1:3021. No ar, use o endereço publicado no servidor. O primeiro pedido é GET /v1/conexao. O site da AquisCore chega na mesma API por /bff. Um site de fora chama a base direto.

Conexão

Todas as respostas são JSON. O corpo enviado também é JSON, com o cabeçalho Content-Type: application/json.

GET /v1/conexao

{
  "servico": "aquiscore-rifas",
  "versao": 1,
  "rotas": []
}

A chave, quando a rota pede, vai no cabeçalho x-parceiro-chave. Ela nasce em Rifas, no painel da administradora, e aparece uma única vez. Sem a chave, abrir campanha responde 401.

Rotas

Emitir um bilhete

A lista pública não traz CPF. Traz o identificador, o prêmio, o valor do bilhete, quantos foram vendidos, a taxa de gestão em pontos-base (1000 é 10%) e os números. arrecadado é a soma. taxa fica com a administradora. premioReais fica separado para o prêmio. Os dois últimos somam o primeiro.

POST /v1/rifas/RF-exemplo/bilhetes
Content-Type: application/json

{
  "nome": "Helena Souza",
  "cpf": "390.533.447-05",
  "email": "helena@exemplo.com",
  "telefone": "11988880000",
  "cep": "06454-050",
  "cidade": "Barueri",
  "uf": "SP"
}

O CEP é opcional. Com oito dígitos, a API preenche a cidade e a UF quando encontra o endereço. O telefone precisa de DDD, com 10 ou 11 dígitos. A resposta de sucesso traz o número do bilhete e a conta atualizada:

{ "numero": 1, "contas": { "arrecadado": 25, "taxa": 2, "premioReais": 23, "invariante": true } }

Consulta de CPF, CNPJ e CEP

O formulário do site paralelo pode consultar antes de enviar. O tipo é cpf, cnpj ou cep.

POST /v1/consulta
Content-Type: application/json

{ "tipo": "cpf", "valor": "39053344705" }

CPF com dígito errado volta valido: false. Com a API Brasil ligada no servidor, a resposta também traz o nome e a situação na Receita. Sem o token, a API confirma os dígitos e não inventa nome. CEP encontrado devolve logradouro, bairro, município e UF.

Abrir uma campanha

POST /v1/parceiros/rifas
Content-Type: application/json
x-parceiro-chave: a-chave-entregue-uma-vez

{
  "nome": "Rifa do site paralelo",
  "premio": "Crédito de R$ 1.000",
  "valorBilheteReais": 25,
  "quantidade": 100,
  "taxaGestaoBps": 1000
}

O valor do bilhete é um número inteiro de reais, no máximo 100.000. A quantidade vai de 2 a 100.000. A taxa vai de 0 a 3.000 pontos-base, isto é, de 0% a 30%. A resposta 201 traz o identificador RF-.... Esse identificador é o que o site usa para vender.

GET /v1/parceiros/rifas devolve as campanhas daquela chave, com o nome do comprador e o CPF mascarado. O CPF completo fica só no painel da administradora.

Compra do número

O comprador paga o bilhete em reais. A instituição autorizada converte em BRL1 e a AquisCore não compra o token. A resposta de POST /v1/rifas/:id/bilhetes traz lancamento, com a taxa retida e o fundo que aquele bilhete acrescentou na carteira da campanha. A origem é livro. O registro não envia transferência. A rampa Pix ainda não está ligada: o lançamento entra no livro na emissão.

O sorteio continua sendo a conta pública do hash. Ele passa a um algoritmo na rede só quando existir o contrato oficial do BRL1. Até lá, nenhuma transação é enviada.

Taxa e carteira do livro

Cada campanha é uma carteira do livro da administradora. A resposta pública traz taxaCobrada, taxaRetida e fundo, em reais. A taxa fica retida na campanha e não passa para outra. O campo textoTaxa explica o percentual, o valor retido agora e a referência de um bilhete. A conta oficial usa o total arrecadado, em reais inteiros, sem arredondar a taxa para cima.

O endereço de controle nasce do identificador e aparece só no painel da administradora. Não é uma carteira Solana e não tem chave privada. O saldo do livro usa 6 casas, como o BRL1, e é o registro da administradora. Não é saldo na rede.

Sorteio

A venda é encerrada no painel. Depois disso, a administradora publica uma semente de pelo menos 8 caracteres e a API grava o hash. O site paralelo lê o resultado em GET /v1/rifas/:id, nos campos semente, hashSorteio e bilheteVencedor.

A conta é SHA-256 do texto identificador|números em ordem crescente separados por vírgula|semente. O vencedor é o item na posição do resto da divisão desse hash pela quantidade de bilhetes. Nenhuma transação vai à Solana enquanto o contrato oficial do BRL1 não existir.

Respostas de erro

O corpo do erro é { "erro": "texto em português" }.

Exemplo para colar no servidor do site

const base = "http://127.0.0.1:3021";
const chave = process.env.AQUISCORE_CHAVE;

const campanha = await fetch(base + "/v1/parceiros/rifas", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-parceiro-chave": chave,
  },
  body: JSON.stringify({
    nome: "Rifa do site paralelo",
    premio: "Crédito de R$ 1.000",
    valorBilheteReais: 25,
    quantidade: 100,
    taxaGestaoBps: 1000,
  }),
});
const rifa = await campanha.json();

const bilhete = await fetch(base + "/v1/rifas/" + rifa.id + "/bilhetes", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    nome: "Helena Souza",
    cpf: "39053344705",
    email: "helena@exemplo.com",
    telefone: "11988880000",
    cep: "06454050",
    cidade: "Barueri",
    uf: "SP",
  }),
});

A chave não entra na página que o visitante abre. O navegador dele pode chamar só a emissão do bilhete e a leitura pública. Um sorteio promocional continua dependendo da autorização do órgão competente.

Voltar às rifas