Introduction

Au lieu de créer un portail de récompenses séparé ou de coordonner manuellement des fournisseurs, vous pouvez orchestrer les événements de cadeaux (gifting events) directement depuis vos systèmes existants, comme le CRM, le HRIS ou vos plateformes d'opérations internes. L'API permet à votre application de déclencher, gérer et suivre ces moments d'engagement de façon programmatique, tandis que Giftpack prend en charge l'exécution logistique (fulfillment), la disponibilité, la logistique et la conformité.

Giftpack n'est pas structuré comme une API e-commerce traditionnelle. Au lieu d'être centré sur des catalogues produits et des transactions de checkout, le système modélise les cadeaux (gifting) comme des événements relationnels. L'identité du destinataire, le timing et le contexte métier sont traités comme des entrées de premier plan, au même titre que l'article envoyé. Cela permet d'aligner naturellement les intégrations avec des déclencheurs réels: onboarding, anniversaires, clôtures de deals, campagnes de rétention ou jalons d'engagement client.

L'API fournit une visibilité de cycle de vie sur chaque étape du processus, y compris le statut de redemption, l'avancement de fulfillment et le suivi de livraison (delivery tracking). Ces endpoints permettent à vos systèmes de mesurer les résultats, d'automatiser les actions de suivi et d'intégrer les cadeaux (gifting) dans vos workflows de reporting et d'opérations.

Concept Clé

Au niveau système, Giftpack suit ce modèle de cycle de vie:

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

Chaque étape représente une transition d'état dans le cycle d'engagement:

• Intent définit le déclencheur métier ou l'objectif.
• Campaign agit comme conteneur d'engagement.
• Recipient représente l'identité qui participe à la campagne.
• Redemption capture l'action du destinataire.
• Fulfillment gère le processus opérationnel d'exécution logistique.
• Tracking fournit la visibilité post-action et les analyses.

Diagramme du cycle de vie

ÉVÉNEMENT MÉTIER
    │
    ▼
[ Intent ]
    │
    │  (API synchrone)
    ▼
[ Campaign Created ]
    │
    │  (API synchrone)
    ▼
[ Recipient Attached ]
    │
    │  (API synchrone)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── Action utilisateur (asynchrone) ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

Ce modèle s'applique de manière cohérente aux campagnes de cadeaux intelligents (smart gifting) AutoMatch™, aux commandes marketplace (marketplace orders), aux flux objets de marque (swag workflows) et aux cas d'automatisation d'entreprise. Le comprendre est essentiel pour construire des intégrations fiables dans des environnements asynchrones et event-driven.

Définitions

Ces définitions décrivent les objets métier principaux utilisés dans les intégrations API Giftpack. Comprendre leurs relations est essentiel avant de construire des workflows. Giftpack fonctionne sur trois couches principales:

1. Couche d'Engagement (Engagement Layer)
2. Couche Commerce (Commerce Layer)
3. Couche Supply & Opérations (Supply & Operations Layer)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

Authentification et Sécurité

Toutes les requêtes vers la Giftpack Integration API doivent être authentifiées avec une API Key valide.

L’authentification est obligatoire sur tous les endpoints et appliquée à la frontière du workspace. Les requêtes non autorisées ou mal authentifiées sont rejetées avant l’exécution de la logique métier.

Clés API

Chaque workspace Giftpack peut générer une ou plusieurs API Keys via le dashboard Giftpack.

Les API Keys servent à :

• Authentifier les requêtes API
• Identifier le workspace d’origine
• Appliquer l’autorisation au niveau ressource
• Appliquer les contrôles d’usage et limites de débit

Les API Keys sont workspace-scoped. Elles ne peuvent pas accéder aux ressources hors de leur workspace d’origine.

Giftpack ne partage jamais les API Keys entre workspaces.

Obtenir une API Key

Pour générer une API Key :

1. Connectez-vous à votre dashboard Giftpack
2. Accédez à Integration Hub → API Keys
3. Générez une nouvelle API Key sous Giftpack Integration

Les API Keys sont actives immédiatement après création. Les événements de création de clé sont journalisés pour audit et traçabilité.

Utilisation de l’API Key

Incluez votre API Key dans le header X-API-KEY pour chaque requête.

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

Les requêtes sans API Key valide retournent une erreur d’authentification. L’authentification est effectuée avant le traitement de la requête et l’évaluation des ressources.

Modèle d’autorisation

L’autorisation est appliquée au niveau workspace. Une API Key peut accéder uniquement à :

• Recipients
• Campaigns
• Marketplace Orders
• Swag Orders
• Credits
• Providers
• Autres ressources appartenant à son workspace

L’accès inter-workspaces est strictement interdit. Les décisions d’autorisation sont appliquées côté serveur et ne peuvent pas être contournées par des paramètres client.

Gestion du cycle de vie des clés

Les intégrations enterprise doivent implémenter des contrôles de cycle de vie des clés.

Bonnes pratiques :

• Utiliser des API Keys distinctes pour staging et production
• Faire une rotation périodique des API Keys
• Révoquer immédiatement une API Key en cas de compromission suspectée
• Éviter le partage des API Keys entre équipes ou systèmes

Si une API Key est révoquée, toute requête ultérieure avec cette clé est rejetée.

Giftpack ne fait pas de rotation automatique des API Keys. Cette gestion relève de l’organisation intégratrice.

Sécurité du transport

Toutes les requêtes API doivent être envoyées via HTTPS.

• Version TLS minimale : TLS 1.2
• Les requêtes HTTP non chiffrées sont rejetées

Toutes les données en transit sont chiffrées via TLS standard industrie.

Cela inclut :

• Données Recipient
• Informations d’expédition
• Métadonnées de commande
• Headers d’authentification

Giftpack ne prend pas en charge les connexions non sécurisées.

Limitation de débit

Les requêtes API sont soumises au rate limiting pour assurer stabilité et usage équitable. En cas de dépassement, l’API renvoie :

• Statut HTTP 429
• Code d’erreur RATE_LIMIT_EXCEEDED

Les intégrations doivent :

• Implémenter une logique de retry
• Utiliser des stratégies d’exponential backoff
• Éviter le polling agressif

Pour des charges enterprise à fort volume ou en pic, contactez Giftpack pour ajuster la configuration de rate.

Confidentialité des données et traitement des PII

Les APIs Giftpack peuvent traiter des données personnelles identifiables (PII), notamment :

• Noms des recipients
• Adresses e-mail
• Adresses d’expédition

Responsabilités développeur :

• Garantir une base légale de traitement
• Obtenir les consentements nécessaires le cas échéant
• Respecter les réglementations applicables (ex. GDPR, CCPA)
• Minimiser le stockage de données non nécessaires

Giftpack traite les données uniquement pour exécuter les workflows de gifting et rewards. Giftpack n’utilise pas les données recipients à des fins publicitaires ou de profilage non lié.

Considérations de logs et d’audit

Pour les environnements enterprise, les intégrations doivent :

• Journaliser les outbound API requests
• Journaliser les codes de réponse et états d’erreur
• Surveiller les échecs d’authentification anormaux
• Surveiller les événements de rate-limit inattendus

Giftpack conserve des logs internes pour :

• Tentatives d’authentification
• Utilisation des clés
• Événements de sécurité

Réponses d’erreur d’authentification

Les erreurs d’authentification et d’autorisation suivent une structure cohérente.

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

Codes d’erreur d’authentification courants :

• UNAUTHORIZED
• FORBIDDEN
• RATE_LIMIT_EXCEEDED

Bonnes pratiques de sécurité

Pour la production :

• Stocker les API Keys dans des variables d’environnement sécurisées
• Ne jamais exposer d’API Keys dans des applications frontend/client-side
• Ne pas committer les API Keys dans le contrôle de version
• Restreindre l’accès interne aux clés de production
• Privilégier les intégrations server-to-server

En cas de suspicion de compromission d’une API Key :

1. Révoquez la clé immédiatement
2. Générez une clé de remplacement
3. Vérifiez les logs API récents pour détecter tout usage anormal

Gestion des Erreurs et Carte des Statuts

L’API Giftpack utilise des codes HTTP standards et renvoie des payloads d’erreur structurés.

Toutes les réponses d’erreur incluent un code d’erreur lisible par machine et un request_id. En contactant le support, journalisez et fournissez toujours le request_id.

Format de Réponse d’Erreur

Toutes les erreurs suivent cette structure :

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

Champs

• code – Identifiant d’erreur lisible par machine
• message – Explication lisible par humain
• request_id – Identifiant unique de traçage pour le débogage

Le request_id doit être conservé dans vos logs pour le troubleshooting opérationnel.

Codes de Statut HTTP

Giftpack utilise la sémantique standard des statuts HTTP :

• 200 / 201 – Requête réussie
• 400 – Validation échouée ou requête mal formée
• 401 – API Key manquante ou invalide
• 403 – Permissions insuffisantes
• 404 – Ressource introuvable
• 409 – Conflit (ex. ressource dupliquée ou violation d’état)
• 429 – Limite de débit dépassée
• 5xx – Erreur interne serveur

Guide de Retry

Toutes les erreurs ne doivent pas être rejouées.

Peut être rejoué en sécurité

• 429 (Limite de débit dépassée)
• 5xx (Erreurs serveur)

Utilisez un exponential backoff pour les retries. Évitez les retries immédiats et agressifs.

Ne pas réessayer

• 400 (Erreurs de validation)
• 401 / 403 (Échec d’authentification ou de permission)
• 404 (Référence de ressource invalide)
• 409 (Conflits de logique métier)

Ces erreurs indiquent des problèmes côté client à corriger avant renvoi.

Statut Asynchrone vs Statut HTTP

Une réponse HTTP réussie ne garantit pas la fin du fulfillment.

Par exemple :

• 201 Created confirme qu’un campaign a été créé
• Ne confirme pas le redemption
• Ne confirme pas le shipment
• Ne confirme pas le delivery

Les opérations Giftpack progressent souvent de manière asynchrone.

Pour déterminer l’état du lifecycle :

• Interrogez le statut de la ressource via des endpoints GET
• Ou écoutez les événements webhook

Traitez toujours un succès HTTP comme une acceptation de requête, pas comme une finalisation métier.

Considérations d’Idempotence

Si votre intégration effectue des retries, assurez-vous que les requêtes dupliquées ne créent pas d’effets de bord.

Selon le cas :

• Utilisez des external identifiers uniques
• Stockez vos propres request tracking IDs
• Évitez les retries aveugles sur les erreurs 4xx

Giftpack peut refuser la création dupliquée selon la logique de l’endpoint.

Comportement de Rate Limiting

Lorsque les limites de débit sont dépassées :

• Le statut HTTP 429 est renvoyé
• Rejouez après un délai

Les intégrations doivent :

• Implémenter un exponential backoff
• Éviter les boucles de polling serrées
• Préférer les mises à jour webhook au polling GET fréquent

Support et Diagnostic

Si vous rencontrez des erreurs inattendues :

• Journalisez le payload d’erreur complet
• Enregistrez le request_id
• Fournissez le request_id au support Giftpack

Cela permet une traçabilité rapide dans les logs serveur.

Webhooks et Événements Asynchrones

Les workflows Giftpack sont asynchrones.

Une réponse API réussie confirme qu’une requête a été acceptée. Les mises à jour de lifecycle (redemption, fulfillment, shipping, delivery) sont communiquées via des événements webhook.

Les intégrations de production doivent traiter les webhooks comme le mécanisme principal de mise à jour d’état. Le polling des endpoints de statut doit être limité à la réconciliation ou à la reprise.

Types d’Événements Pris en Charge

Les types d’événements webhook sont gérés et affichés dans le dashboard Giftpack. Pour consulter/configurer les triggers disponibles :

https://giftpack.ai/app/developer/webhooks

L’UI du dashboard est la source de vérité pour les événements disponibles en production.

Exemples actuellement pris en charge :

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed

La disponibilité peut évoluer. Référez-vous toujours au dashboard pour la production.

Configuration Webhook

Les webhooks sont configurés par workspace via le dashboard. Chaque configuration inclut :

• name
• endpoint
• event_types
• toggle active
• secret key scoped au workspace

Exemple :

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

Plusieurs configurations webhook peuvent exister par workspace.

Modèle de Livraison

La livraison webhook suit un modèle at-least-once.

Cela implique :

• Un événement peut être livré plusieurs fois
• L’ordre de livraison n’est pas strictement garanti
• Les handlers doivent être idempotents

Une livraison est considérée réussie si votre endpoint retourne un statut HTTP 2xx.

Les réponses non-2xx déclenchent des tentatives supplémentaires.

Contrat de l’Endpoint Récepteur

Votre endpoint webhook doit :

• Accepter les requêtes POST avec payload JSON
• Retourner 2xx pour confirmer le succès
• Répondre dans une fenêtre de timeout raisonnable
• Gérer les événements dupliqués en sécurité

Exemple d’ack :

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

Utilisez l’ID d’événement webhook comme clé de déduplication.

Journal d’Événements et Tentatives

Giftpack fournit un journal complet des événements webhook dans le dashboard. Chaque événement contient :

• Métadonnées d’événement
• Payload brut
• Statut de livraison
• Nombre de tentatives
• Diagnostics request/response par tentative

Statuts de livraison dans les logs :

• 0 – failed
• 1 – processing
• 2 – success

L’API de détail expose :

• Webhook event (événement logique)
• Webhook event requests (tentatives individuelles)

Exemple d’objet détail :

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

Chaque tentative inclut :

• Endpoint cible
• Statut HTTP
• Headers de réponse
• Body de réponse
• Timestamp

Ce journal assure une traçabilité complète et simplifie le debugging.

Console de Test Webhook

Giftpack fournit une console de test Webhook intégrée. Elle permet de :

• Sélectionner un endpoint webhook
• Choisir un type d’événement
• Envoyer un payload simulé
• Voir la réponse en direct de votre endpoint

Cela permet :

• Validation end-to-end
• Inspection du payload
• Diagnostic immédiat

Exemple de réponse de test :

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

La console de test est destinée à la validation avant activation en production.

Exigences de Transport

Même si l’UI peut actuellement accepter http et https, les intégrations de production doivent toujours utiliser HTTPS.

HTTPS garantit :

• Chiffrement en transit
• Protection contre l’interception
• Conformité aux exigences de sécurité enterprise

Bonnes Pratiques d’Intégration

Pour un traitement webhook fiable :

• Utiliser un traitement idempotent
• Logger tous les événements entrants
• Stocker les IDs d’événement pour déduplication
• Éviter les traitements synchrones longs dans le handler
• Déporter les tâches lourdes en background jobs
• Surveiller les tentatives de livraison en échec

L’intégration webhook est la source autoritative des mises à jour de lifecycle. N’assumez pas qu’une réponse API synchrone représente l’état final.

Vérification de Signature Webhook

Pour garantir que les événements webhook proviennent de Giftpack et n’ont pas été altérés, chaque requête est signée avec un secret spécifique au workspace.

Les intégrations de production doivent vérifier les signatures webhook.

Format du Header de Signature

Chaque requête webhook inclut le header suivant :

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

Composants

• t — timestamp Unix (secondes)
• v1 — signature HMAC SHA-256

La signature est générée via :

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

Le raw body doit être utilisé tel que reçu.

Processus de Vérification

Pour vérifier une requête webhook :

1. Extraire le header X-GIFTPACK-SIGNATURE
2. Parser t et v1
3. Récupérer le raw body avant parsing JSON
4. Calculer :

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

1. Comparer avec une timing-safe comparison
2. Rejeter si :

• La signature ne correspond pas
• Le timestamp est trop ancien (recommandé : > 5 min)

Protection contre les Replay Attacks

Pour éviter les replay attacks :

• Vérifier que le timestamp est récent (±300 secondes)
• Stocker les event IDs traités et rejeter les doublons
• Refuser les payloads non signés

Fenêtre temporelle exemple :

current_time - timestamp <= 300 seconds

Exemple (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300;

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Exemple Express :

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Gestion des Secrets

Les webhook secrets :

• Sont uniques par configuration webhook
• Doivent être stockés de manière sécurisée (variables d’environnement)
• Ne doivent jamais être exposés en code client-side
• Doivent être rotés en cas de suspicion de compromission

Si un secret est roté, mettez à jour l’intégration immédiatement.

Gestion des Échecs

Si la vérification échoue :

• Retourner un statut HTTP non-2xx
• Ne pas traiter le payload
• Logger l’échec pour monitoring sécurité

Des échecs répétés peuvent indiquer :

• Mismatch de secret
• Endpoint mal configuré
• Trafic malveillant

Rappel du Modèle de Livraison

La livraison webhook suit un modèle at-least-once. Des événements dupliqués sont possibles.

Construit par Cas d’Usage

Giftpack API est conçu autour de workflows métier réels.

Au lieu de naviguer endpoint par endpoint, choisissez d’abord le cas métier à implémenter. Chaque cas ci-dessous décrit :

• Intention métier
• Séquence API
• Lifecycle attendu
• Événements webhook pertinents

La vérification de signature webhook est documentée dans Webhooks et Événements Asynchrones.

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

POST /v1/campaigns

POST /v1/giftees

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

GET /v1/providers/{providerCode}/products

GET /v1/providers/{providerCode}/products/{productId}

POST /v1/marketplaceorders

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

POST /v1/pointrecipients/{memberId}/enablepointfeature

PATCH /v1/pointrecipients/{memberId}/points

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned