API da premieAí

Começo rápido

1. 1. Crie uma chave. No painel, em Minha conta > Chaves de API, dê um nome, escolha o nível e os perfis. A chave (ppk_...) aparece uma vez só: guarde num cofre de segredos. Ainda sem empresa cadastrada? Comece pelo sandbox, com uma chave de teste.
2. 2. Teste a conexão.

   export PREMIAPAY_CHAVE="ppk_..."
   curl https://premieai.com.br/api/v1/eu -H "Authorization: Bearer $PREMIAPAY_CHAVE"

3. 3. Crie uma campanha com os ganhadores. O orçamento é a soma dos prêmios.

   curl -X POST https://premieai.com.br/api/v1/campanhas \
     -H "Authorization: Bearer $PREMIAPAY_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{
       "nome": "Vendedores destaque · Outubro",
       "motivo": "Meta de vendas batida",
       "ganhadores": [
         {
           "nome": "Ana Souza",
           "cpf": "123.456.789-09",
           "valorCentavos": 50000,
           "contato": "11999998888"
         },
         {
           "nome": "Bruno Lima",
           "cpf": "987.654.321-00",
           "valorCentavos": 30000
         }
       ],
       "condicao": {
         "escolha": "padrao"
       }
     }'

4. 4. Siga o fluxo. O Financeiro aprova o orçamento (POST /campanhas/{id}/orcamento/aprovar) e outra pessoa aprova os ganhadores (POST /campanhas/{id}/ganhadores/aprovar). Os ganhadores recebem o link e você recebe premio.pago a cada Pix. Use GET /pendencias para saber o que está esperando ação.

Sandbox: teste sem dinheiro de verdade

Entre com o seu e-mail e crie uma chave de teste em Minha conta > Sandbox. Não precisa de empresa, CNPJ nem cofre aprovado. A chave de teste (ppk_test_...) usa a mesma URL e as mesmas rotas da API e do MCP, mas tudo roda num ambiente separado:

• Um cofre de teste só seu, com empresa e CNPJ fictícios e R$ 10.000,00 de saldo de mentira.
• Nenhum Pix, WhatsApp ou e-mail sai de verdade. Os dados de teste nunca se misturam com os reais, e uma chave real nunca enxerga o sandbox.
• As regras são as de produção: perfis, quem envia não aprova, alçada, extrato imutável e idempotência. Os webhooks também: cadastre a sua URL com a chave de teste e receba eventos assinados.
• Toda resposta do sandbox traz o cabeçalho PremiaPay-Ambiente: sandbox, e GET /eu devolve "ambiente": "sandbox".

O que em produção depende do banco, do ganhador ou de outra pessoa da empresa, você aciona com os simuladores (grupo Sandbox da referência). Um fluxo completo:

export PREMIAPAY_CHAVE_TESTE="ppk_test_..."
API=https://premieai.com.br/api/v1

# 1. Campanha com ganhadores fictícios
curl -X POST $API/campanhas -H "Authorization: Bearer $PREMIAPAY_CHAVE_TESTE" \
  -H "Content-Type: application/json" -d '{"nome":"Teste","ganhadores":[{"nome":"Ana Souza","cpf":"123.456.789-09","valorCentavos":5000}]}'

# 2. Você é do Financeiro: aprove o orçamento com o saldo de teste
curl -X POST $API/campanhas/cam_.../orcamento/aprovar -H "Authorization: Bearer $PREMIAPAY_CHAVE_TESTE" \
  -H "Idempotency-Key: $(uuidgen)"

# 3. Quem envia não aprova: uma pessoa fictícia aprova os ganhadores
curl -X POST $API/sandbox/aprovacoes -H "Authorization: Bearer $PREMIAPAY_CHAVE_TESTE" \
  -H "Content-Type: application/json" -d '{"campanhaId":"cam_..."}'

# 4. A ganhadora resgata (pago, falhou ou pendente) e você recebe premio.pago
curl -X POST $API/sandbox/resgates -H "Authorization: Bearer $PREMIAPAY_CHAVE_TESTE" \
  -H "Content-Type: application/json" -d '{"campanhaId":"cam_...","participanteId":"par_...","resultado":"pago"}'

O link de resgate de cada ganhador (/r/teste_..., no campo codigo de GET /campanhas/{id}) também abre no navegador, com a página que o ganhador vê e uma faixa de ambiente de teste. Para recomeçar, use POST /sandbox/zerar. Limites do sandbox: até 5 chaves de teste por pessoa e até 200 ganhadores por lista.

Chaves e níveis

Envie a chave em Authorization: Bearer ppk_.... Cada chave pertence a uma pessoa e age em nome dela no cofre da empresa. Guardamos só o hash; se perder, revogue e crie outra.

A chave também pode usar só parte dos perfis da pessoa. Exemplo: quem é Gestor e Financeiro cria uma chave só de Gestor para o robô que monta campanhas, e o dinheiro continua passando pelas mãos dela.

Perfis e aprovação

• Quem envia uma lista de ganhadores não pode aprovar a mesma lista, nem pela API. Para automatizar de ponta a ponta, use chaves de pessoas diferentes.
• Listas acima da alçada do contrato pedem duas aprovações, uma delas do Financeiro.
• Saque vai sempre para uma conta do mesmo CNPJ e precisa de uma segunda pessoa do Financeiro.
• O Pix do prêmio só sai para uma chave no CPF do ganhador.
• Tudo o que a API faz entra no extrato imutável e no registro de acessos da chave.

Idempotência

Em toda ação com dinheiro, envie Idempotency-Key com um valor único por operação (um UUID). Se a conexão cair e você repetir o pedido com a mesma chave e o mesmo corpo, a API devolve a resposta original com Idempotent-Replayed: true e não executa de novo. A chave vale por 24 horas. A mesma chave com outro corpo é recusada (422). Nas demais ações de escrita, o cabeçalho é opcional e funciona igual.

Erros

Todo erro tem o mesmo formato, com uma mensagem pronta para mostrar ao usuário e o id do pedido para o suporte.

HTTP/1.1 422
{
  "erro": { "codigo": "regra_violada", "mensagem": "Quem enviou a lista não pode aprovar a mesma lista" },
  "requestId": "req_Yt2..."
}

Webhooks

Cadastre uma URL https em Minha conta > Webhooks (ou por POST /webhooks). A cada mudança no cofre enviamos um POST com o evento. Responda 2xx em até 10 segundos. Se falhar, tentamos de novo por até 24 horas; o mesmo evento pode chegar mais de uma vez, então descarte repetições pelo id. Para buscar em vez de receber, use GET /eventos?depoisDe=evt_....

POST /premiapay/webhook
PremiaPay-Event-Id: evt_Q2x...
PremiaPay-Event-Type: premio.pago
PremiaPay-Signature: t=1793481234,v1=5f2b...

{
  "id": "evt_Q2x...",
  "tipo": "premio.pago",
  "criadoEm": "2026-11-01T14:03:11.000Z",
  "versao": "2026-11-01",
  "cofreId": "cof_...",
  "dados": { "campanhaId": "cam_...", "participanteId": "par_...", "nome": "Ana Souza", "cpf": "***.456.789-**", "valor": 50000 }
}

Conferir a assinatura (Node.js)

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

// corpo: o texto cru da requisição, antes de JSON.parse
function assinaturaValida(corpo, cabecalho, segredo) {
  const { t, v1 } = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // mais de 5 min
  const esperado = createHmac("sha256", segredo).update(`${t}.${corpo}`).digest("hex");
  return v1?.length === esperado.length && timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}

Agentes de IA (MCP)

As mesmas operações estão disponíveis como ferramentas MCP, para conectar o Claude, o ChatGPT ou o seu próprio agente. A diferença: no MCP, ações sensíveis pedem uma confirmação da pessoa antes de executar. Na API, o nível da chave já é a autorização.