Integração com PDV

Conecte sua frente de caixa ou ERP ao cashback do MercadoClube.

Documentação

Autenticação

Envie em todas as chamadas os cabeçalhos X-API-Key e X-Secret-Token. Guarde-os só no servidor do seu PDV, nunca no navegador.

URL base: https://mercadoclube.com/api/public/v1/pos

Webhooks enviados ao seu PDV trazem X-MercadoClube-Timestamp e X-MercadoClube-Signature = HMAC-SHA256 de timestamp + "." + corpo com o seu segredo de webhook.

POST

/api/public/v1/pos/sales

Registrar venda

Registra a venda, credita o cashback do torcedor, a doação ao clube e debita a comissão do saldo da loja. Use external_id único por venda: repetir o mesmo valor devolve o resultado original (sem cobrar duas vezes). Para abater cashback, envie customer_pin (PIN de 4 dígitos digitado pelo torcedor).

curl -X POST https://mercadoclube.com/api/public/v1/pos/sales \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MERCADOCLUBE_API_KEY" \
  -H "X-Secret-Token: $MERCADOCLUBE_SECRET" \
  -d '{ "external_id": "CUPOM-000123", "amount": 150.00, "customer": { "cpf": "123.456.789-09" }, "redeem_cashback": 10.00, "customer_pin": "1234" }'

Resposta

201 Created
{ "ok": true, "sale": { "id": "…", "external_id": "CUPOM-000123",
  "amount": 150, "redeemed_cashback": 10, "net_payable": 140,
  "customer_cashback": 7.5, "club_donation": 3, "status": "confirmed" } }

GET

/api/public/v1/pos/balance

Consultar saldo e cliente

Sem parâmetros, devolve o saldo de cashback da loja e os percentuais. Com customer_email, customer_cpf ou customer_phone, informa se o torcedor existe e se o plano está ativo. O saldo do torcedor nunca é mostrado à loja.

curl "https://mercadoclube.com/api/public/v1/pos/balance?customer_cpf=12345678909" \
  -H "X-API-Key: $MERCADOCLUBE_API_KEY" \
  -H "X-Secret-Token: $MERCADOCLUBE_SECRET"

Resposta

200 OK
{ "ok": true, "merchant": { "reserve_balance": 820.5, … },
  "customer": { "found": true, "display_name": "Ana", "plan_active": true } }

POST

/api/public/v1/pos/webhooks/trigger

Reenviar confirmação ao seu PDV

Envia de novo a confirmação de pagamento de uma venda para a URL de webhook cadastrada. Cada venda nova já dispara o evento sale.confirmed automaticamente.

curl -X POST https://mercadoclube.com/api/public/v1/pos/webhooks/trigger \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MERCADOCLUBE_API_KEY" \
  -H "X-Secret-Token: $MERCADOCLUBE_SECRET" \
  -d '{ "sale_id": "UUID-DA-VENDA" }'

Resposta

200 OK  { "ok": true, "webhook": { "delivered": true, "status": 200 } }

Códigos de erro

400	validation_error / invalid_json	Corpo inválido
401	missing_credentials / invalid_credentials	Chave ou token errados
402	merchant_reserve_insufficient	Saldo da loja insuficiente — faça uma recarga
403	integration_revoked / ip_not_allowed / invalid_customer_pin	Acesso negado
404	customer_not_found / sale_not_found	Não encontrado
422	insufficient_cashback / customer_pin_required / redeem_exceeds_amount	Regra de negócio
502	webhook_unreachable	Seu webhook não respondeu