Guide Affiliés¶

Qu'est-ce qu'un affilié Funbooker ?¶

Un affilié est un partenaire qui affiche le catalogue d'activités Funbooker sur son propre site web. Lorsqu'un visiteur découvre une activité via le site de l'affilié et finalise une réservation sur Funbooker, l'affilié perçoit une commission sur la transaction.

Comment fonctionne la rémunération ?¶

sequenceDiagram
    participant Visiteur
    participant Site Affilié
    participant Funbooker

    Visiteur->>Site Affilié: Découvre une activité
    Site Affilié->>Funbooker: Redirige le visiteur (avec utm_source)
    Visiteur->>Funbooker: Réserve et paye l'activité
    Funbooker->>Site Affilié: Commission sur la réservation

L'affilié affiche les activités Funbooker sur son site via l'API catalogue ou le widget.
Les liens de réservation incluent un paramètre utm_source identifiant l'affilié.
Lorsqu'un visiteur réserve via ce lien, la réservation est attribuée à l'affilié.
L'affilié perçoit une commission selon les conditions définies dans son contrat de partenariat.

Les conditions de rémunération (taux de commission, fréquence de versement, etc.) sont définies dans votre contrat de partenariat avec Funbooker.

Accéder au catalogue¶

Parcourir les catégories¶

Les activités Funbooker sont organisées en catégories hiérarchiques. Chaque catégorie appartient à une occasion (anniversaire, team-building, etc.).

Lister toutes les catégories :

curl -X GET 'https://www.funbooker.com/api/partner/v1/categories?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json'

Réponse :

[
  {
    "id": 1,
    "name": "Anniversaire",
    "parentId": null,
    "occasion": "birthday"
  },
  {
    "id": 42,
    "name": "Saut en parachute",
    "parentId": 1,
    "occasion": "birthday"
  }
]

parentId: null indique une catégorie racine (occasion).
Les catégories avec un parentId sont des sous-catégories.

Détail d'une catégorie :

curl -X GET 'https://www.funbooker.com/api/partner/v1/categories/42?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json'

Les catégories supportent aussi le format JSON-LD via Accept: application/ld+json pour une intégration sémantique (SKOS).

Lister les activités¶

Liste paginée des activités publiées :

curl -X GET 'https://www.funbooker.com/api/partner/v1/listings?apikey=VOTRE_CLE_API&page=1&perPage=25' \
  -H 'Accept: application/json'

Paramètres de requête :

Paramètre	Type	Défaut	Description
`page`	integer	`1`	Page courante
`perPage`	integer	`25`	Nombre de résultats par page
`search`	string	`""`	Recherche libre dans les titres
`occasion`	string	`""`	Filtrer par slug d'occasion

Détail d'une activité par slug :

curl -X GET 'https://www.funbooker.com/api/partner/v1/listing/saut-en-parachute-paris?apikey=VOTRE_CLE_API' \
  -H 'Accept: application/json'

Réponse (extrait) :

{
  "id": 12345,
  "slug": "saut-en-parachute-paris",
  "title": "Saut en parachute à Paris",
  "atHome": false,
  "isInstant": true,
  "pictureUrl": "https://res.cloudinary.com/funbooker/image/upload/.../photo.jpg",
  "description": "Vivez une expérience de chute libre inoubliable...",
  "minPerson": 1,
  "maxPerson": 15,
  "averageRating": 4.8,
  "ratingCount": 127,
  "address": {
    "city": "Paris",
    "country": "FR",
    "route": "Rue de Rivoli",
    "streetNumber": "10",
    "zip": "75001"
  },
  "categories": [
    {
      "id": 1,
      "name": "Anniversaire",
      "parentId": null,
      "occasion": "birthday"
    },
    {
      "id": 42,
      "name": "Saut en parachute",
      "parentId": 1,
      "occasion": "birthday"
    }
  ],
  "duration": {
    "hours": 1,
    "minutes": 0,
    "real_time": 60
  },
  "minAge": 12,
  "maxAge": 0,
  "isTopSales": true,
  "isNew": false,
  "latitude": 48.8566,
  "longitude": 2.3522,
  "funpro": {
    "id": 789,
    "name": "ParaChute Aventure",
    "pictureUrl": "https://res.cloudinary.com/funbooker/image/upload/.../avatar.jpg"
  },
  "listingItems": [
    {
      "id": 111,
      "listingId": 12345,
      "label": "Saut tandem - 1 personne",
      "description": "Prix par personne",
      "isOption": false,
      "price": 29900,
      "priceType": "per_person",
      "minCapacity": 1,
      "maxCapacity": 10,
      "numberOfPersons": 1,
      "durationTime": 60
    },
    {
      "id": 112,
      "listingId": 12345,
      "label": "Vidéo souvenir",
      "isOption": true,
      "price": 4900,
      "priceType": "option",
      "minCapacity": 1,
      "maxCapacity": 1,
      "numberOfPersons": 1
    }
  ],
  "checkoutLinks": [
    {
      "href": "https://www.funbooker.com/checkout/booking/new/saut-en-parachute-paris",
      "shortLabel": "Réserver"
    }
  ],
  "cancellationPolicy": {
    "count": 48,
    "timeUnit": "hour"
  },
  "updated": "2024-11-15T14:30:00+00:00"
}

Points clés sur la réponse Listing :

listingItems : les variantes tarifaires de l'activité. Chaque item a un price en centimes et un priceType (per_person, plan, option).
checkoutLinks : les liens de réservation pré-construits vers Funbooker. Utilisez ces liens pour rediriger vos visiteurs.
isInstant : si true, la réservation est confirmée immédiatement. Sinon, le prestataire doit valider manuellement.
cancellationPolicy : conditions d'annulation (ex : annulation gratuite jusqu'à 48h avant).
categories : les catégories associées à l'activité, avec leur hiérarchie et occasion.
duration : durée de l'activité décomposée en heures, minutes et temps total en minutes (real_time). null si non renseignée.
minAge / maxAge : tranche d'âge recommandée. 0 signifie non renseigné.
isTopSales : true si l'activité fait partie des meilleures ventes.
isNew : true si l'activité est récente sur la plateforme.

Rechercher des activités¶

La recherche permet de trouver des activités par mots-clés et/ou par zone géographique.

curl -X POST 'https://www.funbooker.com/api/partner/v1/search?apikey=VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "parachute",
    "hitsPerPage": 10,
    "page": 1,
    "lat": 48.8566,
    "lng": 2.3522,
    "radius": 50000
  }'

Paramètres de la requête :

Champ	Type	Requis	Description
`query`	string	Non	Recherche textuelle
`hitsPerPage`	integer	Oui	Nombre de résultats par page
`page`	integer	Oui	Page courante
`categories`	integer[]	Non	Filtrer par IDs de catégories
`lat` / `lng`	float	Non	Coordonnées du centre de recherche
`radius`	integer	Non	Rayon de recherche en mètres
`minY` / `maxY` / `minX` / `maxX`	float	Non	Bounding box pour la recherche cartographique

Réponse (extrait) :

{
  "hits": [
    {
      "id": "12345",
      "title": "Saut en parachute à Paris",
      "slug": "saut-en-parachute-paris",
      "price": 29900,
      "image_name": "photo.jpg",
      "categories": ["Anniversaire", "Sport extrême"],
      "averageRating": 4.8,
      "commentCount": 127,
      "duration": 60,
      "home": false,
      "_geoloc": { "lat": 48.8566, "lng": 2.3522 }
    }
  ],
  "nbHits": 42,
  "page": 1,
  "nbPages": 5,
  "hitsPerPage": 10,
  "query": "parachute"
}

Le widget de réservation est un composant iframe que vous pouvez intégrer directement sur votre site. Il permet à vos visiteurs de démarrer le processus de réservation sans quitter votre page.

Intégration¶

Ajoutez ce code HTML à votre page :

<div
  data-funbooker-widget
  data-product-slug="saut-en-parachute-paris"
  data-utm-source="votre-site"
></div>

<script src="https://www.funbooker.com/assets/checkout-widget/mainV1.js"></script>

Attributs :

Attribut	Requis	Description
`data-funbooker-widget`	Oui	Active le widget sur l'élément
`data-product-slug`	Oui	Le slug de l'activité (obtenu via l'API catalogue)
`data-utm-source`	Non	Identifiant de votre site pour le suivi des conversions

Le widget génère automatiquement une iframe de 350x600px pointant vers le formulaire de réservation Funbooker.

sequenceDiagram
    participant V as Visiteur
    participant A as Site Affilié
    participant W as Widget (iframe)
    participant F as Funbooker

    V->>A: Visite la page activité
    A->>W: Charge le widget (slug + utm_source)
    W->>F: Affiche le formulaire de réservation
    V->>W: Sélectionne date, participants, options
    W->>F: Redirige vers le checkout Funbooker
    V->>F: Finalise le paiement
    F-->>A: Attribution via utm_source

Si vous préférez rediriger vos visiteurs plutôt qu'intégrer un widget, utilisez les checkoutLinks fournis dans la réponse de l'API listing :

https://www.funbooker.com/checkout/booking/new/saut-en-parachute-paris?utm_source=votre-site

Ajoutez le paramètre utm_source pour que la réservation soit attribuée à votre compte affilié.

Bonnes pratiques¶

Mettez en cache les catégories : elles changent rarement. Un rafraîchissement quotidien suffit.
Utilisez la pagination : ne chargez pas tout le catalogue d'un coup. Utilisez page et perPage pour paginer.
Privilégiez le slug : pour afficher une activité, utilisez GET /listing/{slug} plutôt qu'une recherche.
Incluez utm_source : sans ce paramètre, les réservations ne pourront pas être attribuées à votre compte.
Utilisez les checkoutLinks : ne construisez pas les URLs de réservation manuellement. Les checkoutLinks de la réponse listing gèrent les différents types d'activités (standard, ticketing, cadeau).