Documentation API

Vue d'ensemble

L'API Kreward vous permet d'intégrer votre programme de fidélité dans n'importe quel site ou backend. Disponible sur les plans Growth (450 HKD/mois) et Enterprise.

Ce que vous pouvez faire
• Inscrire un client et obtenir un QR code pour sa carte wallet
• Ajouter ou déduire des points / tampons en temps réel
• Consulter le solde d'un client
• Déclencher un remboursement depuis votre serveur

Démarrage rapide (3 étapes)

Obtenez vos clés API — Allez dans Dashboard → API et générez une paire de clés. Vous obtenez une clé publique et une clé secrète.
Testez la connexion — Appelez GET /v1/ping avec votre clé publique. Vous devriez recevoir {"ok":true}.
Inscrivez votre premier client — Appelez POST /v1/enroll avec un email. La réponse contient les QR codes Apple Wallet et Google Wallet.

Authentification

Incluez votre clé API dans le header Authorization avec le schéma Bearer à chaque requête.

PUBLIC

Utilisable dans le JavaScript frontend. Inscription uniquement. Peut être restreinte par liste blanche de domaines.

SECRET

Côté serveur uniquement. Accès complet. Ne jamais exposer dans le code frontend.

HTTP

Authorization: Bearer kw_pub_a3f...   # Public key
Authorization: Bearer kw_sk_9xB...    # Secret key (server only)

Erreurs

Toutes les erreurs retournent du JSON avec un champ error et un code HTTP approprié.

{ "error": "customer_not_found" }

Status	Meaning
200	Success
400	Bad request — missing or invalid parameter
401	Missing or invalid API key
403	Forbidden — plan not eligible, or origin blocked
404	Customer not found
409	Conflict — e.g. insufficient balance
429	Rate limit exceeded (100 req/min)
500	Internal server error

Endpoints

GET/v1/pingPublic or SecretHealth check

Verify the API is reachable and your key is valid.

cURL

curl https://api.kreward.net/v1/ping \
  -H "Authorization: Bearer kw_pub_YOUR_KEY"

{ "ok": true, "merchant": "My Shop" }

GET/v1/meSecret onlyAccount info

Returns your merchant details, active card templates, and current plan.

cURL

curl https://api.kreward.net/v1/me \
  -H "Authorization: Bearer kw_sk_YOUR_SECRET"

{ "merchant": "My Cafe", "plan": "growth", "templates": [
    { "id": "uuid...", "name": "Stamp Card", "type": "stamps", "goal": 8 }
] }

POST/v1/enrollPublic or SecretEnroll + wallet QR

Enroll a customer. Creates account if needed. Returns QR codes for Apple Wallet and Google Wallet.

Field	Type	Description
email	string	Si omis, retourne un QR pointant vers votre page d'inscription.
name	string	Customer display name (optional)
template_id	uuid	Card template (defaults to first active)

cURL

curl -X POST https://api.kreward.net/v1/enroll \
  -H "Authorization: Bearer kw_pub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Jane"}'

JavaScript

const res = await fetch('https://api.kreward.net/v1/enroll', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer kw_pub_YOUR_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]', name: 'Jane' }),
});
const data = await res.json();
// data.qr_ios / data.qr_android -> base64 PNG

PHP

$ch = curl_init('https://api.kreward.net/v1/enroll');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER=>true,CURLOPT_POST=>true,
  CURLOPT_HTTPHEADER=>['Authorization: Bearer kw_sk_SECRET','Content-Type: application/json'],
  CURLOPT_POSTFIELDS=>json_encode(['email'=>'[email protected]','name'=>'Jane'])]);
$data = json_decode(curl_exec($ch),true);

{ "enrolled": true, "card_id": "uuid...", "balance": 0,
  "qr_ios": "data:image/png;base64,...",
  "qr_android": "data:image/png;base64,...",
  "wallet_url_ios": "https://...", "wallet_url_android": "https://..." }

Affichez qr_ios / qr_android comme <img src="..."> — aucun stockage de fichier nécessaire. Ou redirigez vers wallet_url_ios / wallet_url_android pour une installation en un tap.

GET/v1/customerSecret onlyQuery balance

Param	Type	Description
email required	string	Customer email address
template_id	uuid	Specific card template

cURL

curl "https://api.kreward.net/v1/[email protected]" \
  -H "Authorization: Bearer kw_sk_YOUR_SECRET"

{ "card_type": "stamps", "balance": 5, "goal": 8, "name": "Jane" }

POST/v1/transactionSecret onlyAdd / deduct

Field	Type	Description
email required	string	Customer email
delta required	integer	Montant à ajouter (positif) ou déduire (négatif). Ex : +1 tampon, -50 points.
note	string	Optional note (order ID, etc.)
template_id	uuid	Target a specific template

cURL

curl -X POST https://api.kreward.net/v1/transaction \
  -H "Authorization: Bearer kw_sk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","delta":1,"note":"Order #1234"}'

Node.js

await fetch('https://api.kreward.net/v1/transaction', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.KREWARD_SECRET_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: order.email, delta: 1, note: order.id }),
});

PHP

wp_remote_post('https://api.kreward.net/v1/transaction', [
  'headers' => ['Authorization'=>'Bearer '.$_ENV['KREWARD_SECRET'],'Content-Type'=>'application/json'],
  'body' => json_encode(['email'=>$email,'delta'=>1,'note'=>'Order #'.$order_id]),
]);

{ "ok": true, "new_balance": 6, "card_type": "stamps", "goal": 8 }

POST/v1/redeemSecret onlyClaim a reward tier

Tiers are milestones identified by their at threshold (see GET /v1/customer). Claiming a tier marks it redeemed — it does not spend balance, except redeeming the final stamp milestone (at == stamps_total) on a stamps card, which loops the card (balance becomes the held overflow, milestones re-arm).

Field	Type	Description
email required	string	Customer email
at required	integer	The tier threshold to claim (positive integer)

cURL

curl -X POST https://api.kreward.net/v1/redeem \
  -H "Authorization: Bearer kw_sk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","at":8}'

{ "ok": true, "redeemed_at": 8, "looped": true, "redeemed_tiers": [],
  "balance_before": 8, "balance_after": 0, "card_type": "stamps" }

HTML / JavaScript simple

Ajoutez un formulaire d'inscription à n'importe quel site statique en moins de 10 minutes, avec uniquement la clé publique.

HTML

<form id="loyalty-form">
  <input type="email" id="lf-email" placeholder="Your email" required>
  <button type="submit">Get my loyalty card</button>
</form>
<div id="loyalty-result" style="display:none"></div>
<script>
document.getElementById('loyalty-form').addEventListener('submit', async e => {
  e.preventDefault();
  const res = await fetch('https://api.kreward.net/v1/enroll', {
    method:'POST',
    headers:{'Authorization':'Bearer kw_pub_YOUR_KEY','Content-Type':'application/json'},
    body: JSON.stringify({ email: document.getElementById('lf-email').value }),
  });
  const d = await res.json();
  if (d.qr_ios) {
    document.getElementById('loyalty-result').innerHTML =
      '<a href="'+d.wallet_url_ios+'"><img src="'+d.qr_ios+'" width="160"></a> '+
      '<a href="'+d.wallet_url_android+'"><img src="'+d.qr_android+'" width="160"></a>';
    document.getElementById('loyalty-result').style.display='block';
  }
});
</script>

Astuce : Configurez les origines autorisées dans le dashboard API pour que votre clé publique ne fonctionne que depuis votre domaine.

WordPress / WooCommerce

Step 1 — Stockez votre clé secrète dans wp-config.php (jamais en dur dans vos plugins) :

wp-config.php

define('KREWARD_SECRET_KEY', 'kw_sk_YOUR_SECRET');

Step 2 — Ajoutez dans functions.php ou un plugin personnalisé :

PHP

add_action('woocommerce_order_status_completed', function($order_id) {
  $order = wc_get_order($order_id);
  if (!$order->get_billing_email()) return;
  wp_remote_post('https://api.kreward.net/v1/transaction', [
    'headers' => ['Authorization'=>'Bearer '.KREWARD_SECRET_KEY,'Content-Type'=>'application/json'],
    'body' => json_encode(['email'=>$order->get_billing_email(),'delta'=>1,'note'=>'Order #'.$order_id]),
  ]);
});

add_action('woocommerce_created_customer', function($customer_id) {
  $user = get_user_by('id', $customer_id);
  wp_remote_post('https://api.kreward.net/v1/enroll', [
    'headers' => ['Authorization'=>'Bearer '.KREWARD_SECRET_KEY,'Content-Type'=>'application/json'],
    'body' => json_encode(['email'=>$user->user_email,'name'=>$user->display_name]),
  ]);
});

Intégration Shopify

Option A — Shopify Flow (sans code)

Installez Shopify Flow depuis l'App Store (gratuit).
Créez un workflow déclenché par "Commande payée".
Ajoutez une action "Envoyer une requête HTTP" vers POST /v1/transaction.
Configurez le header Authorization et le corps avec email depuis order.email et delta: 1.

Option B — Webhook personnalisé (Node.js)

Node.js

app.post('/webhooks/shopify/order-paid', async (req, res) => {
  const order = req.body;
  res.sendStatus(200);
  if (!order.email) return;
  await fetch('https://api.kreward.net/v1/transaction', {
    method:'POST',
    headers:{'Authorization':`Bearer ${process.env.KREWARD_SECRET_KEY}`,'Content-Type':'application/json'},
    body:JSON.stringify({ email:order.email, delta:1, note:`Shopify ${order.name}` }),
  });
});

Bonnes pratiques de sécurité

Ne jamais exposer votre clé secrète dans le code frontend ou les dépôts publics. Utilisez des variables d'environnement.
Restreindre les origines autorisées pour votre clé publique afin qu'elle ne fonctionne que sur vos domaines.
Révoquez et régénérez la clé si vous soupçonnez une compromission.
Utilisez uniquement HTTPS — l'API impose TLS.
Conservez la clé secrète dès la création — elle n'est jamais récupérable ensuite.
Limite de débit : 100 requêtes par minute par clé.

⚠️ Votre clé secrète donne un accès complet à votre programme de fidélité — quiconque la possède peut ajouter ou retirer des points. Traitez-la comme un mot de passe de base de données.

Kreward External API

Vue d'ensemble

Démarrage rapide (3 étapes)

Authentification

PUBLIC

SECRET

Erreurs

Endpoints

HTML / JavaScript simple

WordPress / WooCommerce

Step 1 — Stockez votre clé secrète dans wp-config.php (jamais en dur dans vos plugins) :

Step 2 — Ajoutez dans functions.php ou un plugin personnalisé :

Intégration Shopify

Option A — Shopify Flow (sans code)

Option B — Webhook personnalisé (Node.js)

Bonnes pratiques de sécurité

Prêt à commencer ?

🔑 Clés API

📡 Test /ping

📦 Plan Growth