Voltar ao início

Enggaja para desenvolvedores

Leve pontos e produtos para qualquer frontend. Conecte compras e ações do seu backend à mesma experiência de fidelidade.

Usar os widgetsVer API de eventosWidgets v0.2.3

Comece pela superfície certa

O que você quer colocar no ar?

Widgets cuidam da experiência no navegador. A API recebe eventos com segurança no seu backend.

Frontend

Mostrar pontos e produtos

Web Components prontos para Nuxt, Vue e HTML. Sem dependências e sem expor sua API Key.

<enggaja-points />
Instalar widgets
Backend

Enviar compras e ações

Uma API HTTP para identificar clientes, processar regras e creditar recompensas de forma idempotente.

POST/api/v1/events
Integrar API
CDN público versionado API Key somente no servidor Resposta HTTP 202

API de eventos · 5 minutos

Envie seu primeiro evento

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

Web Components · Nuxt, Vue e HTML

Widgets para frontend

Use a apresentação oficial de saldo do Enggaja em Nuxt 3, Vue 3 ou qualquer frontend compatível com Web Components. O pacote inclui o mesmo ícone, tipografia numérica e cores exibidos no portal do consumidor.

Prévia ao vivo

Os próprios Web Components publicados, sem réplica visual.

CDN v0.2.3

Saldo

Compacto para cabeçalhos, perfis e checkout.

Catálogo

Produtos com preço, pontos e ações de carrinho.

Abrir bundle de pontos Abrir bundle de produtos

Instalação no Nuxt 3

nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => ['enggaja-points', 'enggaja-products'].includes(tag),
    },
  },
})
components/SaldoPontos.vue
<script setup lang="ts">
useHead({
  script: [{
    type: 'module',
    src: 'https://enggaja.com/widgets/points-widget.v0.2.3.js',
  }],
})
</script>

<template>
  <enggaja-points points="1240" />
</template>

HTML ou qualquer framework

HTML
<script type="module" src="https://enggaja.com/widgets/points-widget.v0.2.3.js"></script>
<enggaja-points points="1240"></enggaja-points>
O widget recebe o saldo pronto pela propriedade points. Busque o valor no seu backend; nenhuma API Key deve ser enviada ao navegador. Use label para trocar “pontos creditados” e variáveis CSS --enggaja-points-* para tematização controlada. As fontes oficiais Bricolage Grotesque e Nunito Sans são incorporadas em WOFF2 e carregadas pelo Web Component sem requisição ao Google Fonts.

Produtos disponíveis

O catálogo exportável preserva os cards do cardápio Enggaja, incluindo preço em centavos, alternativa em pontos e disponibilidade.

HTML / JavaScript
<script type="module" src="https://enggaja.com/widgets/products-widget.v0.2.3.js"></script>
<enggaja-products id="cardapio" user-points="1240"></enggaja-products>

<script>
  const products = [{
    id: 'prod_cafe',
    name: 'Cappuccino da casa',
    price: 1490,
    points_price: 300,
    availability: { available: true }
  }]

  document.querySelector('#cardapio')
    .setAttribute('products', JSON.stringify(products))

  document.querySelector('#cardapio')
    .setAttribute('quantities', JSON.stringify({ prod_cafe: 1 }))

  document.querySelector('#cardapio')
    .setAttribute('extras-cents', JSON.stringify({ prod_cafe: 400 }))
</script>
Carregue os produtos pelo seu backend e envie somente os campos públicos ao widget. Emextras-cents, informe a soma dos adicionais selecionados por produto, sempre em centavos. O eventoproduct-select abre detalhes; product-add eproduct-remove integram o carrinho controlado pelo site hospedeiro.

Server-to-server · Parceiro + unidade

API de fidelidade para parceiros

Exiba o catálogo resgatável de uma unidade e, com autorização do cliente, consulte saldo e distância até cada produto. Cada API Key pertence a uma combinação de parceiro, unidade e permissões — nunca envie essa chave ao navegador.

GET/api/partner/v1/catalog

Retorna todos os produtos ativos e resgatáveis da unidade, inclusive os que ainda estão longe do saldo do cliente.

POST/api/partner/v1/customer-context

Envie pelo menos um identificador — CPF, telefone (com ou sem +55) ou e-mail. Os enviados devem identificar a mesma conta vinculada à unidade.

cURL · contexto do cliente
curl -X POST https://api.enggaja.com/api/partner/v1/customer-context \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY_DO_PARCEIRO" \
  -d '{
    "cpf": "52998224725",
    "phone": "+5511999887766",
    "email": "[email protected]",
    "request_reference": "pedido-parceiro-001"
  }'
Se o cliente ainda não estiver vinculado à unidade, a resposta traz uma registration_url única e atribuível ao parceiro. Esse link permite medir cadastro e conversão sem virar dependência do cadastro, dos pontos ou do resgate.
O resgate não acontece pela API. Ela não reserva produto nem promete estoque. A troca é exclusivamente presencial e precisa ser revalidada pela unidade.
Baixar coleção Postman da Partner Loyalty API

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.