Documentação da API ADECOINS

Carteira central de pontos de fidelidade (off-chain). 1 AC = R$ 1,00.

• Domínio: adecoins.com.br
• Painel admin: /admin
• Área do usuário: /carteira

---

API pública HMAC — /api/public/v1/*

Todas as rotas de merchants ficam sob o prefixo /api/public/v1 (o prefixo /api/public/ é obrigatório para bypass de auth no site publicado — não use /api/v1).

Base URL de produção:

https://adecoins.lovable.app/api/public/v1

Headers obrigatórios

Observações

• O HMAC é calculado sobre o raw body exatamente como enviado (sem re-serializar).
• Reusar uma X-Idempotency-Key com payload diferente retorna 409.
• Reusar com payload idêntico retorna a resposta original (status + body).

Como assinar (Node.js)

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

const secret = process.env.ADECOINS_MERCHANT_SECRET!;
const body = JSON.stringify({ email: "cliente@exemplo.com", amount: 10 });
const signature = createHmac("sha256", secret).update(body).digest("hex");

await fetch("https://adecoins.lovable.app/api/public/v1/reserve", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Merchant-Id": "adeplay",
    "X-Key-Id": process.env.ADECOINS_API_KEY!,
    "X-Secret": secret,
    "X-Signature": signature,
    "X-Idempotency-Key": randomUUID(),
  },
  body,
});

Como assinar (bash)

export ADECOINS_MERCHANT_SLUG="adeplay"
export ADECOINS_API_KEY="ak_..."
export ADECOINS_MERCHANT_SECRET="sk_..."

sign() {
  printf '%s' "$1" | openssl dgst -sha256 -hmac "$ADECOINS_MERCHANT_SECRET" -hex | awk '{print $2}'
}

---

Endpoints

GET /wallet — consulta saldo

Body vazio, assinar string vazia.

SIG=$(sign "")
curl -i "https://adecoins.lovable.app/api/public/v1/wallet?email=cliente@exemplo.com" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG"

Resposta:

{ "id": "...", "email": "cliente@exemplo.com", "available": 250.00, "pending": 0, "blocked": 0, ... }

POST /reserve — reservar saldo (pré-autorização)

BODY='{"email":"cliente@exemplo.com","amount":25.50,"external_ref":"pedido-123"}'
SIG=$(sign "$BODY")
curl -i -X POST "https://adecoins.lovable.app/api/public/v1/reserve" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

Retorna reservation_id para uso em confirm / cancel.

POST /confirm — confirmar reserva (débito efetivo)

BODY='{"reservation_id":"...","external_ref":"pedido-123"}'
SIG=$(sign "$BODY")
curl -i -X POST "https://adecoins.lovable.app/api/public/v1/confirm" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

POST /cancel — cancelar reserva (libera saldo)

BODY='{"reservation_id":"..."}'
SIG=$(sign "$BODY")
curl -i -X POST "https://adecoins.lovable.app/api/public/v1/cancel" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

POST /credit — creditar pontos (cashback / bônus)

BODY='{"email":"cliente@exemplo.com","amount":10.00,"description":"Cashback pedido 123","external_ref":"pedido-123"}'
SIG=$(sign "$BODY")
curl -i -X POST "https://adecoins.lovable.app/api/public/v1/credit" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

POST /refund — estornar transação confirmada

BODY='{"transaction_id":"...","amount":25.50,"reason":"Cliente cancelou"}'
SIG=$(sign "$BODY")
curl -i -X POST "https://adecoins.lovable.app/api/public/v1/refund" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $ADECOINS_MERCHANT_SLUG" \
  -H "X-Key-Id: $ADECOINS_API_KEY" \
  -H "X-Secret: $ADECOINS_MERCHANT_SECRET" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

amount é opcional — se omitido, estorna o valor total.

---

Códigos de erro

---

Credenciais

Gere/rotacione em /admin/keys (requer role admin):

• Key ID (ak_...) → ADECOINS_API_KEY
• Secret (sk_...) → ADECOINS_MERCHANT_SECRET (exibido uma única vez)
• Slug → ADECOINS_MERCHANT_SLUG (ex: adeplay)

Botão Rotacionar cria uma nova key e revoga a anterior atomicamente.