Guide Revendeurs¶

Qu'est-ce qu'un revendeur Funbooker ?¶

Un revendeur est un partenaire qui vend des cartes cadeaux et des bons d'activité Funbooker directement depuis sa propre plateforme (site web, application, point de vente).

Contrairement à l'affilié qui redirige les visiteurs vers Funbooker, le revendeur finalise la vente sur sa plateforme et appelle l'API pour générer le produit (carte cadeau ou bon).

Pourquoi utiliser l'API plutôt que des codes pré-générés ?¶

Certains partenaires (comme Gladdy) fonctionnent historiquement avec des séries de codes pré-générés : Funbooker fournit un lot de codes à l'avance, et le partenaire les distribue au fil des ventes.

Ce modèle a des limites importantes :

	Codes pré-générés	API Partner (temps réel)
Génération	Lot de codes fourni à l'avance	Code généré à chaque vente
Expiration	Date fixe pour tout le lot	1 an à partir de la date d'achat réelle
Stock	Risque de rupture ou de surplus	Pas de stock à gérer
Annulation	Difficile à tracer	Annulation via API (`DELETE`)
Suivi	Manuel	Automatique via `partnerReference`
Montant	Fixe au moment de la génération	Libre à chaque vente (1 à 300 EUR)

graph LR
    subgraph "Ancien modèle : codes pré-générés"
        A1[Funbooker génère N codes] --> A2[Envoi du lot au partenaire]
        A2 --> A3[Le partenaire distribue les codes]
        A3 --> A4["Date d'expiration fixe pour tous"]
    end

    subgraph "Nouveau modèle : API temps réel"
        B1[Client achète sur le site partenaire] --> B2[Appel API /giftcard/create]
        B2 --> B3[Code généré instantanément]
        B3 --> B4["Expiration = date d'achat + 1 an"]
    end

L'API garantit que chaque client reçoit une date d'expiration correcte, calculée à partir du moment exact de son achat.

Carte cadeau (Gift Card)¶

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)

Bon d'activité (Voucher)¶

Un bon d'activité est un bon cadeau lié à une activité spécifique. Contrairement à la carte cadeau monétaire, le bon est pré-configuré pour une activité et des options précises.

Créer un bon d'activité¶

Pour créer un bon, vous devez connaître l'id de l'activité et les id des options tarifaires (obtenus via GET /listing/{slug}).

curl -X POST 'https://www.funbooker.com/api/partner/v1/voucher/create?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "listingId": 12345,
    "listingItems": [
      {
        "listingItemId": 111,
        "quantity": 2,
        "unitPrice": 29900
      }
    ],
    "giftName": "Marie",
    "giftReceiverName": "Pierre",
    "giftMessage": "Joyeux anniversaire !"
  }'

Paramètres de la requête :

Champ	Type	Requis	Description
`listingId`	integer	Oui	ID de l'activité
`listingItems`	array	Oui	Options sélectionnées (voir ci-dessous)
`giftName`	string	Non	Nom de la personne qui offre
`giftReceiverName`	string	Non	Nom du bénéficiaire
`giftMessage`	string	Non	Message personnalisé sur le bon

Structure de listingItems :

Champ	Type	Description
`listingItemId`	integer	ID de l'option tarifaire
`quantity`	integer	Quantité
`unitPrice`	integer	Prix unitaire en centimes

Réponse :

{
  "voucherCode": "XFKDJL456413",
  "bookingUrl": "https://www.funbooker.com/useVoucher/XFKDJL456413",
  "price": {
    "amount": 59800,
    "currency": "EUR"
  }
}

Détails de la réponse :

Champ	Description
`voucherCode`	Code du bon à transmettre au bénéficiaire
`bookingUrl`	URL pour convertir le bon en réservation
`price`	Prix total en centimes (somme des items x quantités)

Workflow du bon d'activité¶

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

    Note over R: 1. Le revendeur consulte le catalogue
    R->>API: GET /listing/saut-en-parachute-paris
    API-->>R: {id: 12345, listingItems: [{id: 111, label: "Saut tandem", price: 29900}]}

    Note over R: 2. Le client achète le bon
    C->>R: Achète un bon "Saut tandem x2"
    R->>API: POST /voucher/create (listingId: 12345, items: [{id: 111, qty: 2}])
    API-->>R: {voucherCode: "XFKDJL456413", bookingUrl: "..."}
    R-->>C: Transmet le code et l'URL de réservation

    Note over B: 3. Le bénéficiaire utilise le bon
    C->>B: Offre le bon d'activité
    B->>F: Utilise le code pour réserver une date
    F->>F: Réservation confirmée

Suivi et réconciliation comptable¶

Avec la référence partenaire¶

Chaque carte cadeau créée via l'API est associée à votre partnerReference. Utilisez cette référence pour réconcilier les ventes entre votre système et Funbooker :

Cartes cadeaux : le partnerReference est retourné dans chaque réponse et identifie la transaction dans votre système.
Bons d'activité : le suivi se fait via le voucherCode retourné à la création.

Organisation automatique¶

Funbooker organise automatiquement vos cartes cadeaux en séries annuelles (ex : "Série PartnerAPI VotreNom - 2025"). Cela facilite le reporting côté Funbooker.

Bonnes pratiques¶

Générez les codes au moment de la vente : n'appelez l'API qu'au moment où le client finalise son achat. Ne pré-générez pas de codes.
Conservez le partnerReference : c'est votre clé de réconciliation. Utilisez un identifiant unique de votre système (numéro de commande, ID de transaction, etc.).
Communiquez l'usageUrl : transmettez au bénéficiaire l'URL d'utilisation fournie par l'API. C'est le moyen le plus simple d'utiliser la carte ou le bon.
Gérez les annulations rapidement : si un client demande un remboursement, annulez la carte cadeau via l'API tant qu'elle est encore available.
Vérifiez les prix : pour les bons d'activité, assurez-vous que le unitPrice envoyé correspond au prix courant du listingItem (obtenu via GET /listing/{slug}). L'API accepte la création même en cas de différence, mais une alerte est générée côté Funbooker.