1. Introdução

Bem-vindo à documentação oficial da API do winPoints. Nossa plataforma permite que sua empresa (tenant) integre de forma transparente e segura o seu próprio sistema (como E-commerces, ERPs, PDVs ou aplicativos móveis) ao motor de fidelidade winPoints.

Através da nossa API, sua equipe pode realizar a identificação de clientes, creditar pontos baseados em compras, debitar ou estornar pontos de transações, consultar extratos e saldos em tempo real, e resgatar vouchers de benefícios.

Coloque sua integração para funcionar em menos de 10 minutos seguindo estes passos:

1. Acesse o painel administrativo em winpoints.com.br/login e garanta que o onboarding básico do seu tenant esteja concluído.
2. Vá na aba Integrações e clique em Criar Nova Chave de API. Defina os escopos desejados (ex: points:write).
3. Copie a Chave Pública (API Key) e a Chave Secreta (API Secret) geradas.Aviso: A chave secreta só é mostrada uma única vez e não pode ser recuperada!
4. Configure as variáveis de ambiente no seu servidor backend com os valores copiados.
5. Faça sua primeira requisição de teste para o endpoint de checagem de integridade para confirmar a autenticação.

curl -X GET "https://winpoints.com.br/api/partner/v1/auth/check" \
  -H "X-WinPoints-Api-Key: wpk_live_sua_chave_publica" \
  -H "X-WinPoints-Timestamp: 1720951200" \
  -H "X-WinPoints-Signature: sua_assinatura_calculada"

O winPoints disponibiliza ambientes isolados para homologação (Sandbox) e operações financeiras reais (Produção).

Atenção: Chaves criadas para o ambiente de testes retornarão erro INVALID_API_ENVIRONMENT caso sejam enviadas com cabeçalhos destinados ao servidor de produção, e vice-versa.

A segurança da nossa API é baseada em assinaturas criptográficas HMAC-SHA256. Isso protege a integridade dos dados e impede ataques de replay.

Toda requisição deve conter três cabeçalhos (headers) obrigatórios:

• X-WinPoints-Api-Key: Sua chave pública gerada no painel.
• X-WinPoints-Timestamp: Timestamp Unix (em segundos) do momento da requisição (tolerado desvio de até 300 segundos).
• X-WinPoints-Signature: A assinatura hash gerada a partir do payload.

Como calcular a assinatura:

1. Obtenha o timestamp Unix atual em segundos (ex: 1720951200).
2. Calcule o hash SHA-256 (formato hex) do corpo (body) da requisição. Se não houver corpo (como em requisições GET), use o hash da string vazia: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
3. Crie um payload juntando os seguintes campos com quebra de linha (\n):

   TIMESTAMP
   HTTP_METHOD
   URL_PATH
   BODY_HASH

4. Derive o segredo de assinatura calculando o hash SHA-256 (hex) do seu segredo privado api_secret.
5. Gere a assinatura usando HMAC-SHA256, tendo a chave derivada no passo anterior e a mensagem do passo 3. O resultado em formato hexadecimal é o valor que deve ir no header X-WinPoints-Signature.

# 1. Requisição cURL de Crédito de Pontos Autenticada via HMAC
curl -X POST "https://winpoints.com.br/api/partner/v1/points/credit" \
  -H "Content-Type: application/json" \
  -H "X-WinPoints-Api-Key: wpk_live_seu_token_publico" \
  -H "X-WinPoints-Timestamp: 1720951200" \
  -H "X-WinPoints-Signature: assinatura_HMAC_calculada" \
  -d '{
    "email": "cliente@example.com",
    "amount": 1000,
    "description": "Compra no pedido 1029",
    "idempotency_key": "credit:order-1029:v1"
  }'

Para todas as operações de crédito, débito ou consulta de saldos, os clientes finais da empresa (usuários do programa de fidelidade) podem ser localizados por dois atributos exclusivos:

• user_id: Identificador UUID único gerado pelo winPoints.
• email: Endereço de email cadastrado pelo cliente.

Aviso de Validação: Ao realizar qualquer requisição, informe o user_id ou o email. Fornecer ambos ou nenhum dos dois resultará em um erro de validação USER_REFERENCE_REQUIRED.

Emite pontos para a conta de um cliente qualificado no contexto do seu tenant. Se houver campanhas de multiplicadores ativas e a transação corresponder às condições, a pontuação bônus é somada e aplicada automaticamente.

{
  "email": "cliente@example.com",
  "amount": 1000,
  "description": "Compra no pedido erp-84271",
  "idempotency_key": "credit:erp-84271:v1"
}

{
  "id": "7ac156a0-5c6a-4d22-b9cf-89196b208da0",
  "user_id": "908d1326-8092-48a5-8120-91a0210f92ab",
  "type": "earn",
  "amount": 1000,
  "source": "api:wpk_live_...",
  "description": "Compra no pedido erp-84271",
  "idempotency_key": "credit:erp-84271:v1",
  "created_at": "2026-07-14T04:15:00Z"
}

Deduz pontos do saldo ativo de um cliente para realizar estornos, ajustes manuais ou cancelamentos comerciais. Os pontos são consumidos respeitando a ordem de expiração (fila FIFO).

{
  "email": "cliente@example.com",
  "amount": 200,
  "description": "Estorno parcial de compra cancelada",
  "idempotency_key": "debit:refund-84271:v1"
}

{
  "id": "890afb20-dca0-410a-b283-acde47219080",
  "user_id": "908d1326-8092-48a5-8120-91a0210f92ab",
  "type": "adjustment",
  "amount": -200,
  "source": "api:wpk_live_...",
  "description": "Estorno parcial de compra cancelada",
  "idempotency_key": "debit:refund-84271:v1",
  "created_at": "2026-07-14T04:16:00Z"
}

Transfere pontos diretamente de um cliente doador para um cliente beneficiário. A operação é atômica (ou ambas as contas são atualizadas com sucesso, ou a transferência inteira falha).

{
  "from_email": "doador@example.com",
  "to_email": "beneficiario@example.com",
  "amount": 500,
  "description": "Transferência de pontos promocional",
  "idempotency_key": "transfer:p2p-74291:v1"
}

{
  "debit_transaction": {
    "id": "1a2b3c4d-...",
    "user_id": "...",
    "type": "adjustment",
    "amount": -500,
    "description": "Transferência de pontos promocional",
    "idempotency_key": "transfer:p2p-74291:v1"
  },
  "credit_transaction": {
    "id": "5e6f7g8h-...",
    "user_id": "...",
    "type": "earn",
    "amount": 500,
    "description": "Transferência de pontos promocional",
    "idempotency_key": "transfer:p2p-74291:v1"
  }
}

Recupera a lista de recompensas do catálogo do tenant que estão ativas e possuem estoque disponível maior que zero. Os parceiros podem usar este endpoint para apresentar opções de resgate diretamente dentro dos seus próprios sistemas.

[
  {
    "id": "18ac28f4-279c-4822-bc50-1a1a7b48cb92",
    "title": "Vale compras R$ 50",
    "category": "giftcard",
    "points_price": 2500,
    "stock": 42
  }
]

Consome o saldo de pontos do cliente e gera um resgate ativo de benefício. Dependendo da categoria da recompensa, um código de voucher ou uma instrução de envio é gerada.

{
  "email": "cliente@example.com",
  "reward_id": "18ac28f4-279c-4822-bc50-1a1a7b48cb92",
  "idempotency_key": "redeem:order-9821:v1",
  "delivery_email": "recebedor@example.com"
}

{
  "id": "e472a190-84c1-48bd-bbca-7facde1289cf",
  "reward_id": "18ac28f4-279c-4822-bc50-1a1a7b48cb92",
  "reward_title": "Vale compras R$ 50",
  "reward_category": "giftcard",
  "status": "completed",
  "points_amount": 2500,
  "remaining_balance": 140,
  "voucher_code": "WIN-VALE-50-G8F2",
  "delivery_email": "recebedor@example.com",
  "delivery_address": {},
  "delivery_status": "delivered",
  "created_at": "2026-07-14T04:18:00Z",
  "replayed": false
}

Para evitar a emissão dupla de pontos ou débitos concorrentes acidentais causados por instabilidades de rede, nossa API exige o preenchimento de uma chave de idempotência (idempotency_key) em todas as requisições de escrita.

A chave de idempotência é única por tenant e deve seguir o padrão Regex: ^[A-Za-z0-9._:-]+$. Recomendamos compor a chave com o tipo da transação e o identificador do pedido do seu sistema (ex: credit:pedido-98421:v1).

Caso uma requisição seja reenviada com os mesmos parâmetros e a mesma chave, a API retornará o status 200 OK e a resposta idêntica original (com a tag "replayed": true no caso de resgates). Caso a mesma chave seja enviada com parâmetros de corpo modificados, a requisição será rejeitada com o erro IDEMPOTENCY_KEY_REUSED (HTTP 409).

Para manter a estabilidade do sistema, a API de parceiros do winPoints impõe um limite máximo de requisições de 60 requisições por minuto por credencial ativa.

Ao atingir o limite, a API retornará o status HTTP 429 Too Many Requests e o cabeçalho Retry-After: 60, indicando em quantos segundos seu sistema deve aguardar para repetir a operação.

Caso sua requisição falhe, a API retornará um corpo JSON com uma estrutura padronizada contendo código interno e mensagem amigável:

Para manter a segurança das chaves e das transações de pontos, siga estritamente estas diretrizes:

• Nunca armazene chaves no Git. Use variáveis de ambiente seguras ou um gerenciador de segredos (Secrets Manager).
• Nunca faça chamadas à API no Frontend (HTML/React/JS do navegador). Isso expõe sua chave pública e secreta para qualquer usuário. Todas as chamadas de integração devem ocorrer no seu servidor backend corporativo.
• Rotacione as chaves periodicamente. No painel administrativo da empresa, você pode clicar em "Rotacionar" para gerar um novo segredo sem indisponibilizar o serviço. A chave antiga é invalidada imediatamente após a geração da nova.

Antes de virar a chave para produção, garanta que todos os itens a seguir estejam concluídos:

Se precisar de suporte adicional de integração ou encontrar problemas com as assinaturas de chamadas, entre em contato com nosso time de engenharia pelo email corporativo: suporte@winpoints.com.br.

Ao abrir um ticket, forneça sempre o seu tenant_slug e, se possível, o request_id da resposta HTTP com erro. Nunca envie chaves privadas ou tokens por e-mail.