Aller au contenu
FOVE
Essai gratuit

Documentation développeur

L’API REST de FOVE relie une caisse, une boutique en ligne ou un back-office à vos programmes de fidélité. Référence complète et interactive : OpenAPI.

Authentification

Créez une clé secrète dans Intégrations, avec seulement les droits nécessaires (scopes). Elle s’utilise côté serveur, jamais dans un navigateur. Les clés fove_sk_test_ et fove_sk_live_ sont séparées.

curl https://api.fove.digital/api/v1/programs \
  -H "Authorization: Bearer fove_sk_live_…"

Idempotence

Chaque POST exige un en-tête Idempotency-Key unique (8 à 120 caractères). Rejouer la même requête renvoie la réponse d’origine avec Idempotent-Replayed: true ; la même clé avec un autre corps est refusée (422). Les commandes e-commerce sont en plus dédupliquées par externalOrderId.

curl -X POST https://api.fove.digital/api/v1/loyalty/transactions \
  -H "Authorization: Bearer fove_sk_live_…" \
  -H "Idempotency-Key: vente-2026-10-28-0042" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "…", "amount": "15000", "saleReference": "T-0042" }'

Endpoints

MéthodeCheminUsage
GET/api/v1/customersLister et rechercher les clients (pagination par curseur, filtre q)
GET/api/v1/customers/lookupTrouver un client par externalId, email ou phone
POST/api/v1/customersCréer un client
GET/api/v1/programsLister les programmes
POST/api/v1/loyalty/accountsCréer la carte d’un client dans un programme
GET/api/v1/loyalty/accounts/{id}Solde, historique récent, récompenses disponibles
GET/api/v1/loyalty/transactionsHistorique des opérations
POST/api/v1/loyalty/transactionsCréditer un achat (points calculés par FOVE)
POST/api/v1/loyalty/transactions/{id}/reverseAnnuler une opération par écriture compensatoire
GET/api/v1/rewardsCatalogue de récompenses
POST/api/v1/redemptionsUtiliser une récompense
POST/api/v1/integrations/commerce/orders/paidCommande payée : client rattaché, carte créée si besoin, points crédités
POST/api/v1/integrations/commerce/orders/refundedRemboursement total ou partiel

SDK TypeScript

Le paquet @fove/sdk gère l’authentification, les clés d’idempotence et les nouvelles tentatives sur erreur réseau.

import { FoveClient } from "@fove/sdk";

const fove = new FoveClient({ apiKey: process.env.FOVE_SECRET_KEY! });

// Dans le webhook de paiement de votre boutique
const result = await fove.orderPaid({
  programId: process.env.FOVE_PROGRAM_ID!,
  externalOrderId: order.id,
  orderNumber: order.orderNumber,
  customer: { externalId: user.id, email: user.email, firstName: user.firstName },
  amount: order.total.toString(),
  currency: order.currency,
  paidAt: order.paidAt.toISOString(),
});

// Remboursement
await fove.orderRefunded({ programId, externalOrderId: order.id, externalRefundId: refund.id, amount: "25.00" });

Webhooks

Événements : customer.created, loyalty_account.created, loyalty_transaction.created, redemption.created, redemption.cancelled. Chaque envoi est signé (en-tête fove-signature, HMAC-SHA256) et réessayé jusqu’à 8 fois en cas d’échec. Les livraisons sont visibles dans Intégrations.

import { verifyWebhookSignature } from "@fove/sdk";

const ok = verifyWebhookSignature(rawBody, req.headers["fove-signature"], process.env.FOVE_WEBHOOK_SECRET!);
if (!ok) return res.status(400).end();

Widget

Un script indépendant de tout framework. Il utilise une clé publique (fove_pk_) limitée aux domaines que vous déclarez : elle lit la configuration publique et ne peut jamais créditer de points. Collez-le avant </body> (WordPress, Astro, Next.js, Symfony ou HTML).

<script src="https://app.fove.digital/widget/fove-widget.js"
        data-key="fove_pk_live_…"
        data-position="right" defer></script>

Erreurs et limites

Les erreurs ont la forme { "error": { "code", "message", "details" } }. Codes fréquents : insufficient_balance, account_inactive, customer_exists, quota_exceeded (402), rate_limited (429). Limite par défaut : 300 requêtes par minute et par clé.