Voltar ao início

Webhook API

Envie eventos de compra do seu POS, e-commerce ou delivery. O Enggaja identifica o cliente e credita recompensas automaticamente.

Quick Start

Uma única requisição HTTP para enviar um evento de compra e gerar pontos:

cURL
curl -X POST https://api.enggaja.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "type": "purchase",
    "identifier_type": "cpf",
    "identifier_value": "12345678901",
    "data": { "amount": 89.90 },
    "idempotency_key": "order-2024-00123"
  }'
1

Seu sistema

Envia POST com evento

2

Enggaja

Identifica o cliente

3

Regras

Avalia condições e limites

4

Recompensa

Credita pontos, badges, cupons

Autenticação

Toda requisição deve incluir o header X-API-Key. A key é gerada ao criar o app no dashboard.

HTTP
POST /api/v1/events HTTP/1.1
Host: api.enggaja.com
Content-Type: application/json
X-API-Key: SUA_API_KEY
Nunca exponha sua API Key no frontend. Use apenas no servidor (backend). Ela identifica o estabelecimento e tem acesso total aos eventos.

Enviar Evento

POST/api/v1/events

Parâmetros do body (JSON)

CampoTipoDescrição
type*stringTipo do evento. Ex: purchase, checkin, review
data*objectDados do evento. Campos livres usados nas condições. Ex: {"amount":89.90}
user_idstringID do consumidor no Enggaja. Prioridade sobre outros identificadores.
identifier_typestringTipo do identificador: cpf ou phone
identifier_valuestringValor. CPF: 12345678901 | Telefone: 11999887766
platformstringNome da plataforma de origem. Ex: instagram, ifood, rappi. Qualquer string.
platform_identifierstringIdentificador do cliente na plataforma (username, email, ID externo).
idempotency_keystringChave única anti-duplicata. Max 255 chars. Ex: order-12345
timestampstringRFC3339 para backfill. Ex: 2024-01-15T14:30:00Z. Omitido = agora
prioritystringFila: immediate, normal (padrão), low
Identificação obrigatória: envie ao menos um — user_id, identifier_type + identifier_value, ou platform + platform_identifier.

Identificação do Cliente

Escolha o método que faz sentido para o seu sistema. O Enggaja normaliza os valores automaticamente.

CPF

POS / E-commerce
identifier_type: "cpf", identifier_value: "123.456.789-01"

Pontos, traços e espaços são removidos. Resultado: 11 dígitos.

Telefone

Delivery / WhatsApp
identifier_type: "phone", identifier_value: "11999887766"

Envie no formato local (sem +55). O Enggaja normaliza para E.164 (5511999887766).

Plataforma

Social / Delivery / Qualquer
platform: "instagram", platform_identifier: "joao_insta"

Envie o nome da plataforma e o identificador do cliente nela (username, email, ID). O valor é normalizado para minúsculo.

user_id direto

SSO / Banco compartilhado
user_id: "cusr_abc123def456"

Mais performático — sem lookup. Tem prioridade sobre os outros métodos.

Respostas

202 Evento aceito (assíncrono)

Resposta padrão. O evento entra na fila de processamento.

JSON
{
  "success": true,
  "data": {
    "status": "accepted",
    "message": "event queued for processing"
  }
}

200 Evento processado (sync)

Quando a fila está cheia, o evento é processado na hora e retorna o resultado completo.

JSON
{
  "success": true,
  "data": {
    "event_id": "evt_a1b2c3d4e5f6",
    "actions_run": ["act_compra_pontos"],
    "points_earned": 100,
    "xp_earned": 25,
    "coins_earned": 0,
    "badges_earned": [],
    "coupons_earned": [],
    "missions_updated": [],
    "missions_completed": [],
    "rules_executed": [],
    "warnings": [],
    "duplicate": false
  }
}

200 Duplicata (idempotência)

Mesmo resultado do original, mas duplicate: true. Pontos NÃO são creditados novamente.

JSON
{
  "success": true,
  "data": {
    "event_id": "evt_a1b2c3d4e5f6",
    "duplicate": true,
    "points_earned": 100,
    "xp_earned": 25
  }
}

Erros

Todas as respostas de erro seguem o formato:

JSON
{
  "success": false,
  "error": "mensagem descritiva"
}
StatusMensagemO que fazer
400"type is required"Envie type e data no body
400"unsupported identifier_type: must be 'cpf' or 'phone'"Use cpf ou phone
401"invalid or missing API key"Verifique o header X-API-Key
404"user not found for identifier:cpf"Cliente precisa se cadastrar no portal primeiro
409"idempotency key already used for a different user"Cada idempotency_key é vinculada ao primeiro cliente
429Rate limitAguarde e reenvie

Idempotência

Use idempotency_key para evitar processamento duplicado. Essencial para retries e falhas de rede.

1.Evento chega com idempotency_key que já existe para o mesmo tenant → retorna resultado original com duplicate: true
2.Mesma key mas cliente diferente (anti-fraude) → 409
3.Sem key → evento sempre processado normalmente

Boas práticas

  • Use o ID do pedido: "order-12345", "ifood-abc123"
  • Única por estabelecimento (tenant)
  • Máximo 255 caracteres
  • Whitespace-only é tratado como vazio

Exemplos de Código

Compra via POS (CPF)

O caso mais comum: POS envia o CPF do cliente na hora da venda.

curl -X POST https://api.enggaja.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "type": "purchase",
    "identifier_type": "cpf",
    "identifier_value": "12345678901",
    "data": {
      "amount": 89.90,
      "payment_method": "credit_card"
    },
    "idempotency_key": "order-2024-00123"
  }'

Delivery (Telefone)

Delivery apps identificam por telefone. Envie sem +55.

cURL
curl -X POST https://api.enggaja.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "type": "purchase",
    "identifier_type": "phone",
    "identifier_value": "11999887766",
    "data": { "amount": 45.50, "source": "ifood" },
    "idempotency_key": "ifood-order-abc123"
  }'

Com user_id direto

Se você já tem o ID do consumidor (SSO, banco compartilhado).

cURL
curl -X POST https://api.enggaja.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "type": "purchase",
    "user_id": "cusr_abc123def456",
    "data": { "amount": 200.00, "items_count": 3 }
  }'

Perguntas frequentes

Preciso de um SDK para integrar?

▾

Não. A integração é via HTTP REST. Qualquer linguagem que faça requisições HTTP funciona.

E se o CPF ou telefone não estiver cadastrado?

▾

O webhook retorna HTTP 404 com a mensagem "user not found for identifier:cpf". O cliente precisa se cadastrar no portal do estabelecimento antes.

Posso enviar o mesmo evento duas vezes?

▾

Sim, desde que use o campo idempotency_key. O Enggaja detecta duplicatas e retorna o resultado original sem creditar pontos novamente.

Como testo a integração?

▾

Use sua API Key real. Crie um usuário de teste no portal e envie eventos com dados fictícios. Você pode deletar os eventos depois pelo dashboard.

O webhook suporta OAuth?

▾

Não. A autenticação é exclusivamente via API Key no header X-API-Key.

Outras funcionalidades

Pontos de Fidelidade

Clientes acumulam pontos e trocam por prêmios

Desafios e Recompensas

Crie desafios que aumentam a frequência de compras

Níveis e Status VIP

Bronze, Prata, Ouro — clientes sobem de nível

Conquistas e Badges

Gamificação que gera engajamento e boca a boca

Integração Instagram

Menções e comentários viram pontos de fidelidade

O Enggaja combina todas essas funcionalidades em uma única plataforma. Saiba mais ou explore o blog.

Pronto pra começar?

Configure em 5 minutos. Sem app. Sem contrato. A partir de R$197/mês.