API de gamificação Engagety

Desenvolvedores

Uma API REST simples e previsível

JSON in, JSON out. Autenticação por chave, processamento em tempo real.

1. Gere uma chave

Em Integrações, crie uma chave de API. Ela é exibida uma única vez.

2. Autentique

Envie a chave no header x-api-key em todas as requisições, sempre do seu servidor.

3. Envie eventos

A cada ação do usuário, chame /v1/events e use a resposta para exibir recompensas.

cURL

curl -X POST https://sua-app/api/public/v1/events \
  -H "x-api-key: gx_live_SUA_CHAVE" \
  -H "content-type: application/json" \
  -d '{"participant_id":"user_123","action":"purchase"}'

POST/v1/events

Registrar ação

Envia uma ação de um participante. Aplica pontos/XP, avança desafios ligados à ação, concede badges e atualiza o nível. O participante é criado automaticamente no primeiro evento.

{ "participant_id": "user_123", "action": "purchase",
  "name": "Ana Souza", "email": "ana@cliente.com",
  "metadata": { "order_id": "A-981" } }

GET/v1/participants/{participant_id}

Perfil do participante

Retorna pontos, XP, nível atual, próximo nível (XP restante) e badges conquistados.

GET/v1/challenges?participant_id=user_123

Listar desafios

Desafios ativos no período. Com participant_id, inclui progresso e conclusão de cada um.

POST/v1/challenges/{challenge_id}/progress

Pontuar em desafio

Avança manualmente o progresso de um desafio. Ao atingir a meta, entrega as recompensas.

{ "participant_id": "user_123", "amount": 1 }

GET/v1/leaderboard?by=xp&limit=10

Ranking

Ranking de participantes por xp ou points.

GET/v1/catalog

Catálogo

Ações, níveis e badges configurados — útil para exibir a jornada completa na sua interface.

Erros

Respostas de erro seguem o formato {"error":{"code","message"}}: 401 unauthorized, 400 invalid_body, 404 unknown_action, 404 challenge_not_available, 404 participant_not_found.