Référence API

Cette page documente tous les endpoints de la Partner API avec leurs paramètres, formats de requête et de réponse.

Documentation interactive

Explorez et testez l'API directement depuis le Swagger UI.

URL de base : https://www.funbooker.com/api/partner/v1

Authentification : paramètre apikey requis sur chaque requête (voir Accueil).

---

Catalogue

GET /categories

Liste toutes les catégories d'activités.

curl "https://www.funbooker.com/api/partner/v1/categories?apikey=VOTRE_CLE_API"

Réponse 200 :

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

---

GET /categories/{categoryId}

Détail d'une catégorie.

Paramètre	In	Type	Requis	Description
categoryId	path	integer	Oui	ID de la catégorie

curl "https://www.funbooker.com/api/partner/v1/categories/42?apikey=VOTRE_CLE_API"

Réponse 200 : objet Category.

---

GET /listings

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

Paramètre	In	Type	Défaut	Description
page	query	integer	1	Page courante
perPage	query	integer	25	Nombre de résultats par page
search	query	string	-	Recherche libre dans les titres
occasion	query	string	-	Filtrer par occasion

curl "https://www.funbooker.com/api/partner/v1/listings?apikey=VOTRE_CLE_API&page=1&perPage=10"

Réponse 200 :

{
  "data": [
    { "...": "objet Listing" }
  ],
  "pagination": {
    "page": 1,
    "pageCount": 7,
    "totalItems": 158,
    "perPage": 10
  }
}

---

GET /listing/{slug}

Détail d'une activité par son slug.

Paramètre	In	Type	Requis	Description
slug	path	string	Oui	Slug de l'activité

curl "https://www.funbooker.com/api/partner/v1/listing/saut-en-parachute-paris?apikey=VOTRE_CLE_API"

Réponse 200 : objet Listing.

Réponse 404 :

{
  "errors": [
    { "status": "404", "title": "Listing not found" }
  ]
}

---

POST /search

Recherche d'activités par mots-clés et/ou zone géographique.

Paramètre	In	Type	Requis	Description
query	body	string	Non	Mots-clés de recherche
categories	body	integer[]	Non	Filtrer par IDs de catégories
lat	body	number	Non	Latitude du centre de recherche
lng	body	number	Non	Longitude du centre de recherche
radius	body	integer	Non	Rayon de recherche en mètres
minY / maxY	body	number	Non	Bounding box latitude
minX / maxX	body	number	Non	Bounding box longitude
hitsPerPage	body	integer	Oui	Nombre de résultats par page
page	body	integer	Oui	Page courante

Tip

Recherche par rayon (lat/lng + radius) ou par bounding box (minX/maxX/minY/maxY), mais pas les deux en même temps.

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

Réponse 200 : objet SearchResponse.

Réponse 400 : paramètres invalides.

Réponse 503 : moteur de recherche indisponible.

---

Cartes cadeaux

POST /giftcard/create

Crée une carte cadeau monétaire.

Paramètre	In	Type	Requis	Description
amount	body	integer	Oui	Montant en centimes (min: 1, max: 30000 soit 300 EUR)
partnerReference	body	string	Oui	Votre référence unique de vente

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

Réponse 200 : objet GiftCardItem.

Réponse 400 : paramètres invalides.

Réponse 401 : clé API manquante ou invalide.

---

DELETE /giftcard/{id}

Annule une carte cadeau.

Paramètre	In	Type	Requis	Description
id	path	string	Oui	Code de la carte cadeau (ex: CF9Y-8XCS-SMV1)

curl -X DELETE "https://www.funbooker.com/api/partner/v1/giftcard/CF9Y-8XCS-SMV1?apikey=VOTRE_CLE_API"

Réponse 200 : objet GiftCardItem avec status: "canceled".

Réponse 400 : carte non trouvée ou statut incompatible (seules les cartes available peuvent être annulées).

---

Bons d'activité

POST /voucher/create

Crée un bon d'activité lié à un listing spécifique.

Paramètre	In	Type	Requis	Description
listingId	body	integer	Oui	ID de l'activité
listingItems	body	VoucherItem[]	Oui	Options sélectionnées
giftName	body	string	Non	Nom de la personne qui offre
giftReceiverName	body	string	Non	Nom du bénéficiaire
giftMessage	body	string	Non	Message personnalisé

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

Réponse 200 : objet VoucherResponse.

Réponse 400 : paramètres invalides.

---

Modèles de données

Category

Champ	Type	Description
id	integer	Identifiant unique
name	string	Nom de la catégorie
parentId	integer | null	ID de la catégorie parente. null = catégorie racine (occasion)
occasion	string	Type d'occasion : entertainment, gift, birthday, business, bachelor-party, internship, b2b_location

---

Listing

Champ	Type	Description
id	integer	Identifiant unique
slug	string	Slug URL
title	string	Titre de l'activité
pictureUrl	string	URL de l'image principale
description	string?	Description de l'activité
atHome	boolean	L'activité se déroule au domicile du client
isInstant	boolean	Confirmation immédiate (sans validation du pro)
minPerson	number	Nombre minimum de participants
maxPerson	number	Nombre maximum de participants
displayListingEndTime	boolean	Afficher l'heure de fin
averageRating	number?	Note moyenne
ratingCount	integer?	Nombre d'avis
duration	object?	Durée : hours, minutes, real_time (en minutes)
minAge	integer?	Age minimum. 0 = non renseigné
maxAge	integer?	Age maximum. 0 = non renseigné
isTopSales	boolean?	Fait partie des meilleures ventes
isNew	boolean?	Activité récente sur la plateforme
categories	Category[]	Catégories associées
address	Address?	Adresse de l'activité
latitude	float?	Latitude
longitude	float?	Longitude
funpro	ShortFunpro?	Prestataire
listingItems	ListingItem[]	Variantes tarifaires
cancellationPolicy	CancellationPolicy?	Politique d'annulation
specialCondition	string?	Conditions particulières
checkoutLinks	CheckoutLink[]	Liens de réservation
updated	datetime	Date de dernière mise à jour

---

ListingItem

Champ	Type	Description
id	integer	Identifiant unique
listingId	integer	ID du listing parent
label	string	Libellé (ex: "Adulte", "Enfant", "Groupe de 10")
description	string?	Description
price	integer	Prix en centimes
priceType	string	per_person, plan, ou option
isOption	boolean	Option supplémentaire (ex: pack photo)
isDisabled	boolean	Item désactivé
minCapacity	integer	Quantité minimum
maxCapacity	integer	Quantité maximum
numberOfPersons	integer	Nombre de personnes incluses
durationTime	integer?	Durée en minutes

---

Address

Champ	Type	Description
city	string	Ville
country	string	Pays
route	string?	Rue
streetNumber	string?	Numéro
zip	string?	Code postal

---

ShortFunpro

Champ	Type	Description
id	integer	Identifiant du prestataire
name	string	Nom
pictureUrl	string	URL de la photo de profil

---

CancellationPolicy

Champ	Type	Description
count	integer	Nombre d'heures ou de jours
timeUnit	string?	hour ou days

---

CheckoutLink

Champ	Type	Description
href	string	URL de réservation
shortLabel	string	Libellé du lien (ex: "Réserver", "Offrir un bon cadeau")

---

GiftCardItem

Champ	Type	Description
code	string	Code unique (format XXXX-XXXX-XXXX)
amount	integer	Montant en centimes
expirationDate	string	Date d'expiration (YYYY-MM-DD), 1 an après création
status	string	available, used, expired, ou canceled
partnerReference	string	Votre référence de vente
usageUrl	string	URL d'utilisation pour le bénéficiaire

---

VoucherItem

Objet envoyé dans le body de POST /voucher/create.

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

---

VoucherResponse

Champ	Type	Description
voucherCode	string	Code du bon
bookingUrl	string	URL de réservation pour le bénéficiaire
price	Money	Prix total

---

Money

Champ	Type	Description
amount	number	Montant en euros (ex: 50.00)
currency	string	Devise (EUR)

---

Pagination

Champ	Type	Description
page	integer	Page courante
pageCount	integer	Nombre total de pages
totalItems	integer	Nombre total de résultats
perPage	integer	Résultats par page

---

SearchResponse

Champ	Type	Description
hits	ResponseHit[]	Résultats de recherche
nbHits	integer	Nombre total de résultats
page	integer	Page courante
nbPages	integer	Nombre de pages
hitsPerPage	integer	Résultats par page
query	string	Requête envoyée

---

ResponseHit

Format retourné par le moteur de recherche (diffère du format Listing).

Champ	Type	Description
id	integer	ID du listing
title	string	Titre
slug	string	Slug URL
type	string	Occasion (entertainment, birthday, etc.)
price	integer	Prix en centimes
image_name	string	Nom de l'image (Cloudinary)
teaser	string	Présentation courte
priceFrom	string	Description du prix (ex: "12 enfants")
status	integer	Statut (2 = publié)
averageRating	integer	Note moyenne
commentCount	integer	Nombre d'avis
minAge	integer	Age minimum
maxAge	integer	Age maximum
home	boolean	Activité à domicile
duration	object	Durée : hours, minutes, real_time
_geoloc	object	Géolocalisation : lat, lng, department_code, city, zip
categories	object[]	Catégories avec root, parent, id, name, short_name, occasion, lvl, isLeaf
user	object[]	Prestataire : name, average_offerer_rating

---

Codes d'erreur HTTP

Code	Signification
200	Succès
400	Requête invalide (paramètres manquants ou incorrects)
401	Clé API invalide ou absente
404	Ressource non trouvée
503	Service temporairement indisponible (moteur de recherche)

Format d'erreur :

{
  "errors": [
    { "status": "400", "title": "Description de l'erreur" }
  ]
}