Bien démarrer

Les API Giftpack permettent à votre backend de créer et d'exploiter des parcours de récompense, d'incitation, d'articles promotionnels et de sélection par le destinataire. Giftpack gère la disponibilité du catalogue, les expériences destinataires, l'exécution des commandes et les mises à jour de livraison, tandis que votre système reste responsable du déclencheur métier et des données client.

L'URL de base en production est :

https://developer.giftpack.ai

Consultez la référence de l'API pour connaître l'ensemble des schémas de requête et de réponse. Utilisez ce guide pour choisir la famille de ressources adaptée et comprendre l'évolution des ressources après leur création.

Choisir un parcours

Modèle de ressources

Smart Gifting utilise une campagne comme conteneur du programme et un giftee pour représenter le cycle de vie propre à chaque destinataire :

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

Les commandes directes du catalogue utilisent une marketplace order comme conteneur de commande et un marketplace order receiver pour représenter le cycle de vie propre à chaque destinataire :

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

Ne considérez pas giftee et marketplace_order_receiver comme interchangeables. Leurs noms d'événements correspondent à des familles de commandes distinctes, même lorsque leurs états d'exécution se ressemblent.

Cycle de vie d'une requête

Les requêtes de création et de mise à jour renvoient l'état actuel de la ressource. Les actions du destinataire, l'exécution, l'expédition et la livraison se poursuivent de manière asynchrone.

Pour garantir la fiabilité de votre intégration :

• Enregistrez l'identifiant de ressource renvoyé.
• Abonnez-vous à la famille d'événements webhook correspondante.
• Utilisez l'id de l'événement webhook comme clé de déduplication.
• Effectuez un rapprochement via un endpoint GET si votre système détecte un événement manqué ou retardé.
• Ne relancez pas automatiquement une requête qui modifie l'état, sauf si l'opération de l'API documente explicitement un contrat d'idempotence.

Premier appel

Après avoir créé une clé API dans Giftpack, vérifiez l'accès avec le catalogue des événements webhook :

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

La réponse répertorie les types d'événements webhook actuellement pris en charge par l'API. Cet endpoint, et non une liste figée côté client, constitue le catalogue d'événements de référence.

Étapes suivantes

1. Lisez Authentification et sécurité avant de stocker ou d'utiliser une clé API.
2. Sélectionnez un parcours dans Scénarios d'implémentation.
3. Configurez et vérifiez les webhooks avant de mettre une intégration en production.
4. Consultez la référence de l'API pour les champs obligatoires et les modèles de réponse propres à chaque endpoint.

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é

Les principales opérations Giftpack sous /v1 utilisent une clé API limitée à un workspace, transmise dans l'en-tête X-API-KEY. Les clés API doivent être utilisées uniquement par des applications serveur de confiance.

Conditions d'accès

La gestion des clés API est accessible depuis les paramètres développeur. Le workspace et l'utilisateur actuel doivent avoir accès à la fonctionnalité Giftpack Open API et disposer des autorisations requises pour les paramètres développeur.

Si la page Developer n'est pas accessible, demandez à un administrateur du workspace de confirmer l'offre souscrite et votre rôle avant de développer l'intégration.

Créer et stocker une clé

1. Connectez-vous à Giftpack.
2. Ouvrez Developer Settings.
3. Créez une clé API pour l'environnement concerné.
4. Stockez la clé dans un gestionnaire de secrets côté serveur.

Ne placez jamais une clé API dans du JavaScript exécuté dans le navigateur, une application mobile, des journaux, des captures d'écran, des tickets de support ou un dépôt de code source.

Utilisez des identifiants distincts pour les environnements de staging et de production. Révoquez immédiatement toute clé susceptible d'avoir été exposée.

Authentifier une requête

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

La clé API identifie le workspace. L'autorisation d'accès aux ressources est appliquée côté serveur : disposer de l'identifiant d'une ressource appartenant à un autre workspace ne donne pas accès à cette ressource.

Environnement et transport

• Envoyez les requêtes de production à https://developer.giftpack.ai.
• Utilisez HTTPS pour chaque requête.
• Conservez les identifiants dans un stockage de secrets propre à chaque environnement.
• Ne réutilisez pas une clé de production en développement local.

Certaines opérations de connecteurs dans la référence de l'API utilisent des jetons bearer ou une authentification propre au fournisseur. Respectez le schéma de sécurité indiqué pour chaque opération ; ne supposez pas qu'une clé API Giftpack permet d'appeler un endpoint de connecteur.

Pratiques opérationnelles

• Renouvelez les identifiants conformément à la politique de sécurité de votre organisation.
• Limitez l'accès à la clé au seul service qui en a besoin.
• Masquez X-API-KEY dans les journaux de requêtes et d'erreurs.
• Consignez l'opération, l'identifiant de ressource, le statut HTTP et l'horodatage pour faciliter les diagnostics du support.
• Validez les signatures de webhook indépendamment de l'authentification des requêtes API.

Le contrat public ne garantit ni une limite de débit universelle ni une politique de nouvelle tentative unique pour toutes les opérations. Utilisez les en-têtes propres à l'endpoint et la référence de l'API lorsqu'ils sont disponibles, et contactez Giftpack avant de planifier des pics de trafic importants.

Erreurs et reprise

Les opérations Giftpack utilisent les codes de statut HTTP standard. Les réponses d'erreur documentées dans la référence de l'API utilisent application/problem+json.

Réponse de type problème

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

Champs

• type : URI identifiant le type de problème. Sa valeur peut être about:blank.
• title : résumé stable et lisible du problème.
• status : statut HTTP associé à cette réponse.
• detail : explication de cet échec précis.
• instance : URI identifiant cette occurrence, lorsqu'elle est fournie.
• errors : informations facultatives au niveau des champs, avec location, message et value.

La présence de tous les champs n'est pas garantie pour chaque erreur. Concevez des parseurs capables de gérer l'absence de champs facultatifs et l'ajout futur de champs inconnus.

Reprise selon le statut

La référence de l'API fait autorité pour les réponses documentées de chaque opération.

Sécurité des nouvelles tentatives

Les requêtes GET peuvent normalement être relancées avec un backoff exponentiel plafonné. Les requêtes qui modifient l'état exigent davantage de précautions :

• Ne relancez pas aveuglément des requêtes POST ou PATCH après un délai d'attente dépassé.
• Vérifiez d'abord si l'opération documente l'idempotence ou renvoie une ressource permettant un rapprochement.
• Conservez les identifiants renvoyés avant de commencer l'étape suivante.
• Utilisez vos propres champs de référence métier lorsque l'endpoint les prend en charge.
• Empêchez plusieurs workers d'envoyer simultanément la même opération logique.

Un délai d'attente dépassé au niveau du transport signifie que le client n'a pas reçu de réponse ; cela ne prouve pas que le serveur n'a pas terminé la requête.

Informations de diagnostic pour le support

Lors de l'escalade d'un incident, fournissez l'endpoint, la méthode, l'horodatage UTC, le statut HTTP, les identifiants de ressource pertinents et une réponse de type problème dont les données sensibles ont été masquées. N'incluez jamais de clé API ni de données destinataire non masquées.

Webhooks et événements asynchrones

Les webhooks signalent les transitions liées aux destinataires et à l'exécution qui surviennent après la réponse à une requête API. Utilisez-les comme signal principal du cycle de vie et utilisez les opérations GET pour le rapprochement.

Catalogue des événements

Récupérez le catalogue actuel au lieu de coder en dur une liste obsolète :

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

Le catalogue actuel comprend deux familles de ressources.

giftee

Événements du cycle de vie des destinataires pour les commandes Smart Gifting, notamment les campagnes lancées via des intégrations, les programmes planifiés et les parcours de récompense automatisés.

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

Événements du cycle de vie des destinataires pour les commandes passées directement dans Gift Mall ou le Merchandise Catalog, en dehors des parcours de campagne Smart Gifting.

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

Contrat de payload

Chaque livraison est un objet JSON. data est un instantané structuré de la ressource, et non une chaîne JSON échappée.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id est l'identifiant durable de l'occurrence de l'événement et doit servir de clé de déduplication.
• type identifie la famille de ressources et la transition.
• data capture l'état de la ressource au moment de l'événement. Les champs varient selon la famille de ressources et l'étape du cycle de vie.
• created_at indique l'heure de l'occurrence. Les livraisons pouvant arriver dans le désordre, utilisez cette valeur pour ordonner les transitions.
• Les événements de suppression conservent le dernier instantané stocké après la suppression de la ressource active.

Vérification de la signature

Giftpack envoie dans X-Giftpack-Signature le condensat HMAC-SHA256 en hexadécimal minuscule calculé à partir du corps brut de la requête.

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

Vérifiez la signature avant d'analyser ou de traiter le payload. Stockez les secrets de webhook dans un gestionnaire de secrets côté serveur.

Livraison et nouvelles tentatives

• Giftpack envoie une requête HTTP POST avec un corps JSON.
• Toute réponse 2xx marque la livraison comme réussie.
• Une requête peut rester ouverte jusqu'à 60 secondes.
• Les livraisons en échec sont relancées après environ 1, 5 et 15 minutes, avec au maximum quatre tentatives de livraison, requête initiale comprise.
• Une livraison peut être dupliquée. Traitez l'id de manière idempotente.
• L'ordre de livraison n'est pas garanti.

Renvoyez rapidement une réponse 2xx après avoir validé et accepté durablement l'événement. Transférez les traitements coûteux vers une file d'attente.

Statut des journaux d'événements

Les journaux d'événements et de requêtes webhook utilisent les statuts numériques suivants :

• -1 : échec
• 0 : traitement en cours
• 1 : réussite

La réponse détaillée de l'événement comprend les données structurées webhook_event_data, le nombre de tentatives et les enregistrements de chaque requête, afin de faciliter le diagnostic.

Liste de controle pour la production

• Abonnez-vous uniquement aux familles d'événements générées par votre parcours.
• Vérifiez X-Giftpack-Signature à partir du corps brut non modifié.
• Dédupliquez les événements selon leur id.
• Stockez created_at et acceptez les arrivées dans le désordre.
• Ne renvoyez 2xx qu'après avoir accepté l'événement de manière sûre.
• Surveillez les événements qui atteignent le statut d'échec.
• Utilisez l'action de test du tableau de bord avant d'activer un endpoint de production.

Scénarios d'implémentation

Choisissez la famille de ressources correspondant à la manière dont le destinataire reçoit la récompense. La référence de l'API fait autorité pour chaque champ obligatoire et chaque modèle de réponse.

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

Avant la mise en production

• Validez les champs obligatoires par rapport à la référence de l'API actuelle.
• Effectuez les tests avec des destinataires et des identifiants hors production.
• Conservez chaque identifiant de ressource renvoyé.
• Configurez la famille de webhooks correspondante.
• Vérifiez les signatures et dédupliquez les événements.
• Définissez la manière dont votre système effectue le rapprochement après un délai d'attente dépassé, avant de relancer une requête qui modifie l'état.