Cartes cadeaux¶

Une carte cadeau est un crédit monétaire que le bénéficiaire peut utiliser sur Funbooker pour réserver l'activité de son choix.

Créer une carte cadeau¶

curl -X POST 'https://www.funbooker.com/api/partner/v1/giftcard/create?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "partnerReference": "VENTE-2024-00142"
  }'

Paramètres de la requête :

Champ	Type	Requis	Description
`amount`	integer	Oui	Montant en centimes (min: 1, max: 30000 soit 300 EUR)
`partnerReference`	string	Oui	Votre référence unique de vente pour le suivi comptable

Réponse :

{
  "code": "CF9Y-8XCS-SMV1",
  "amount": 5000,
  "expirationDate": "2027-03-25",
  "status": "available",
  "partnerReference": "VENTE-2024-00142",
  "usageUrl": "https://www.funbooker.com/fr/gift-card/CF9Y-8XCS-SMV1"
}

Détails de la réponse :

Champ	Description
`code`	Code unique de la carte cadeau (format `XXXX-XXXX-XXXX`). C'est le code à transmettre au client.
`amount`	Montant en centimes
`expirationDate`	Date d'expiration (1 an après la création)
`status`	Statut de la carte : `available`
`partnerReference`	Votre référence de vente (écho)
`usageUrl`	URL à communiquer au bénéficiaire pour utiliser sa carte

Annuler une carte cadeau¶

Une carte cadeau peut être annulée tant que son statut est available (non utilisée, non expirée).

curl -X DELETE 'https://www.funbooker.com/api/partner/v1/giftcard/CF9Y-8XCS-SMV1?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json'

Réponse :

{
  "code": "CF9Y-8XCS-SMV1",
  "amount": 5000,
  "expirationDate": "2027-03-25",
  "status": "canceled",
  "partnerReference": "VENTE-2024-00142"
}

Règles d'annulation :

Seules les cartes avec le statut available peuvent être annulées.
Les cartes used, expired ou déjà canceled retournent une erreur 400.

Cycle de vie d'une carte cadeau¶

stateDiagram-v2
    [*] --> available : Création via API
    available --> used : Le bénéficiaire utilise la carte
    available --> expired : Date d'expiration dépassée
    available --> canceled : Annulation via API
    used --> [*]
    expired --> [*]
    canceled --> [*]

Workflow complet¶

sequenceDiagram
    participant C as Client
    participant R as Site Revendeur
    participant API as Partner API
    participant F as Funbooker
    participant B as Bénéficiaire

    C->>R: Achète une carte cadeau de 50 EUR
    R->>API: POST /giftcard/create (amount: 5000, ref: "VENTE-00142")
    API-->>R: {code: "CF9Y-8XCS-SMV1", usageUrl: "...", expirationDate: "2027-03-25"}
    R-->>C: Transmet le code et l'URL d'utilisation
    C->>B: Offre la carte cadeau
    B->>F: Utilise le code sur funbooker.com
    F->>F: Réserve une activité (crédit déduit)