SuperHote
Documentation technique Juin 2026

API publique V2

Connectez votre application tierce à SuperHote : lisez les hébergements et les réservations, mettez à jour les disponibilités et les prix. Cette documentation couvre tout ce qu'il faut pour intégrer l'API en moins d'une heure.

Base URL
connect.superhote.com/api/v2/public
Authentification
Bearer token
Format
JSON
Ressources
3 (rentals · calendar · reservations)
Sommaire
  1. 1 Démarrage rapide (5 min) p. 1
  2. 2 Authentification & scopes p. 2
  3. 3 Format des réponses p. 2
  4. 4 Endpoints — lecture p. 3
  5. 5 Endpoints — écriture calendrier p. 4
  6. 6 Réservations & synchro p. 4
  7. 7 Schémas des objets p. 5
  8. 8 Erreurs courantes p. 6
  9. 9 Limites & bonnes pratiques p. 6
  10. 10 Checklist d'intégration p. 6

· Comment ça marche

👤
Hôte SuperHote
crée un token API depuis
Plateformes → API
→
🔑
Token Bearer
affiché une seule fois,
avec des permissions (scopes)
→
🔌
Votre application
appelle l'API avec le token
en en-tête Authorization
→
🔄
SuperHote synchronise
Airbnb, Booking, PriceLabs…
automatiquement
i

Sécurité multi-comptes. Chaque token est limité au périmètre de son propriétaire (ses hébergements, ses réservations). Tout accès hors périmètre renvoie 404 — jamais 403, pour ne pas révéler l'existence d'une ressource.

API publique V21 / 6

1 Démarrage rapide — votre 1ʳᵉ requête en 5 minutes

1

Récupérez un token

Dans SuperHote : Plateformes → API → Créer un token. Cochez les permissions nécessaires, copiez le token immédiatement — il ne sera plus jamais affiché.

2

Testez la connexion

Listez vos hébergements pour vérifier que le token fonctionne :

curl -H "Authorization: Bearer VOTRE_TOKEN" \ "https://connect.superhote.com/api/v2/public/rentals"
3

Vous devez recevoir

"success": true, "result": { "rentals": […vos hébergements…] }

Si vous recevez 401 → token mal copié. Si 403 → permission manquante (cf. §2).

2 Authentification & scopes

Chaque requête doit porter l'en-tête :

Authorization: Bearer <votre-token>

Un token possède une ou plusieurs permissions (scopes). Chaque endpoint en exige une précise :

ScopeCe qu'il permetLectureÉcriture
public-api:rentals.readVoir les hébergements✓—
public-api:calendar.readVoir dispo, prix, restrictions✓—
public-api:calendar.writeModifier dispo, prix, restrictions—✓
public-api:reservations.readVoir les réservations✓—
public-api:allTout (raccourci wildcard)✓✓
!

Lecture seule par conception : il n'existe pas de scope d'écriture pour les hébergements ni les réservations. Seul le calendrier est modifiable via l'API.

3 Format des réponses

Toutes les réponses ont la même enveloppe — testez toujours success en premier :

✓ Succès

{ "success": true, "message": null, "result": { …données… } }

✗ Erreur

{ "success": false, "message": "Hébergement introuvable", "error_code": 1 }
CodeSignificationQue faire
200Succès—
401Token absent / invalide / expiréVérifier l'en-tête, régénérer le token
403Scope manquantRecréer un token avec la bonne permission
404Ressource hors périmètre ou inexistanteVérifier l'ID et le compte propriétaire du token
422Paramètres invalidesLire message — il détaille le champ fautif
API publique V22 / 6

4 Endpoints — lecture

Vue d'ensemble des 5 endpoints. public-api:all remplace n'importe quel scope.

MéthodeCheminUsageScope
GET/rentalsLister les hébergementsrentals.read
GET/rentals/{id}Détail d'un hébergementrentals.read
GET/rentals/{id}/calendarLire le calendriercalendar.read
PATCH/rentals/{id}/calendarModifier le calendriercalendar.write
GET/reservationsLister les réservationsreservations.read
GET/rentals public-api:rentals.read

Liste vos hébergements, triés par nom, paginés.

ParamètreTypeDéfautNote
per_pageint25maximum 100
pageint1—

Réponse

{ "success": true, "result": { "rentals": [ { "id": "12345", "name": "Loft Marais", "city": "Paris", … } ], "meta": { "total": 42, "per_page": 25, "current_page": 1, "last_page": 2 } } }
GET/rentals/{id} public-api:rentals.read

Détail d'un hébergement. Renvoie l'objet Rental complet (§7.1). 404 si l'ID n'existe pas ou n'appartient pas au compte du token.

GET/rentals/{id}/calendar public-api:calendar.read

Calendrier nuit par nuit entre deux dates incluses : disponibilité, prix, min/max nights, restrictions check-in/out.

ParamètreRequisFormat
from✓YYYY-MM-DD
to✓YYYY-MM-DD, ≥ from

Exemple

curl -H "Authorization: Bearer VOTRE_TOKEN" \ "…/rentals/12345/calendar?from=2026-07-01&to=2026-07-07"

Réponse — un objet par nuit

{ "date": "2026-07-01", "available": true, "price": 135.5, "min_nights": 3, "max_nights": null, "no_checkin": false, "no_checkout": false, "reservation_id": null }

Sans restriction définie, les défauts sont : available = true, le reste null / false.

API publique V23 / 6

5 Modifier le calendrier

PATCH/rentals/{id}/calendar public-api:calendar.write

Applique les champs fournis à toutes les nuits de la plage [from, to]. La synchro vers Airbnb, Booking et PriceLabs est automatique — rien d'autre à faire.

ChampTypeRequisContraintes
from / tostring✓YYYY-MM-DD, to ≥ from
availablebool①—
pricenumber①≥ 0
min_nights / max_nightsint①[1, 365] · min ≤ max si les deux fournis
no_checkin / no_checkoutbool①—
①

Au moins un des 6 champs modifiables doit être présent, sinon 422. Les champs omis ne sont pas modifiés.

Exemple — fermer juillet et monter le prix

curl -X PATCH -H "Authorization: Bearer VOTRE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"from":"2026-07-01","to":"2026-07-15","available":true,"price":135.5,"min_nights":3}' \ "…/rentals/12345/calendar"

Réponse

{ "success": true, "message": "Calendrier mis à jour." }

6 Réservations & synchro incrémentale

GET/reservations public-api:reservations.read

Liste paginée des réservations, triées par création (plus récentes d'abord). Tous les filtres sont optionnels et cumulables.

FiltreFormatUsage
updated_sinceISO 8601Synchro incrémentale — ne récupérer que ce qui a changé
created_from / created_toYYYY-MM-DDPlage de création
checkin_from / checkin_toYYYY-MM-DDPlage d'arrivée
statusenumCONFIRMED · UNCONFIRMED · CANCELED
rental_idstringUn seul hébergement
page / per_pageintmax 100, défaut 25
★

Pattern recommandé pour votre synchro : toutes les 5–15 min, appelez /reservations?updated_since=<dernier passage> et stockez l'horodatage de l'appel. Vous ne traitez que le delta — léger et fiable.

Exemple — réservations confirmées modifiées depuis hier

curl -H "Authorization: Bearer VOTRE_TOKEN" \ "…/reservations?status=CONFIRMED&updated_since=2026-06-09T00:00:00Z"
i

Si le token n'a accès à aucun hébergement, la réponse est un tableau vide (meta.total = 0) — jamais une erreur.

API publique V24 / 6

7 Schémas des objets

7.1 — Rental (hébergement)

ChampTypeDescription
idstringIdentifiant unique
namestringNom de l'hébergement
address · city · zip_code · countrystring|nullAdresse complète
latitude · longitudefloat|nullGéolocalisation
capacity · bedrooms · bathrooms · bedsint|nullCapacités
min_nights · max_nightsint|nullRègles par défaut (hors restrictions calendrier)
check_in_time · check_out_timestring|nullHeures, ex. "16:00"
currency_id · timezonemixed|nullDevise et fuseau
enabledboolHébergement actif
created_at · updated_atISO 8601Horodatages

7.2 — CalendarDay (une nuit)

ChampTypeDéfautDescription
datestring—YYYY-MM-DD
availablebooltrueNuit ouverte à la réservation
pricenumber|nullnullPrix de la nuitée
min_nights · max_nightsint|nullnullRestrictions de séjour
no_checkin · no_checkoutboolfalseArrivée / départ bloqués
reservation_idstring|nullnullRéservation occupant la nuit

7.3 — Reservation

ChampTypeDescription
id · rental_idstringIdentifiants
statusenumCONFIRMED · UNCONFIRMED · CANCELED
platformmixedSource (Airbnb, Booking, direct…)
checkin · checkoutstringYYYY-MM-DD
nights · adults_count · children_countint|nullDétails du séjour
guest_first_name · guest_last_namestring|nullVoyageur — uniquement prénom/nom
total_price · currency_idfloat / mixedMontant total
external_idstring|nullID côté plateforme d'origine
created_at · updated_atISO 8601Pour la synchro incrémentale
!

Données personnelles (RGPD). L'email et le téléphone du voyageur ne sont jamais exposés par cette API. Seuls le prénom et le nom sont retournés.

API publique V25 / 6

8 Erreurs courantes — dépannage

SymptômeCause probableSolution
401 UnauthenticatedToken mal copié, espace parasite, ou expiréRe-copier le token ; en générer un nouveau si expiré
403 sur un seul endpointLe token n'a pas le scope de cet endpointCréer un token avec le scope manquant (ou public-api:all)
404 sur un rental qui existeLe rental appartient à un autre compteVérifier que le token vient du bon compte SuperHote
422 sur PATCH calendarAucun champ modifiable fourni, ou min > maxFournir au moins 1 champ ; vérifier les bornes
Tableau rentals videAucun hébergement actif sur le compteVérifier côté dashboard SuperHote
Prix non répercuté sur AirbnbLatence de synchro plateformeLa propagation est automatique mais asynchrone (quelques minutes)

9 Limites & bonnes pratiques

Limites (version actuelle)

  • Hébergements et réservations : lecture seule
  • Pas de batch — 1 hébergement par appel PATCH
  • Pas de webhooks sortants → utiliser updated_since
  • Rate limiting global côté API

Bonnes pratiques

  • Stocker le token chiffré, jamais en clair dans le code
  • Synchro incrémentale via updated_since (5–15 min)
  • Limiter les plages calendrier à ce qui change réellement
  • Toujours tester success avant de lire result

10 Checklist d'intégration

Token créé avec les bons scopes, stocké de façon sécurisée
GET /rentals fonctionne — les hébergements remontent
GET /calendar lu sur une plage de test, valeurs cohérentes avec le dashboard
PATCH /calendar testé sur une plage courte — modification visible dans SuperHote et propagée aux plateformes
Synchro réservations en place avec updated_since + stockage de l'horodatage
Gestion d'erreurs : 401 / 403 / 404 / 422 traités, retries avec backoff sur 5xx
?

Besoin d'aide ? Support intégrateurs : [email protected] — précisez « API publique V2 » en objet, avec votre error_code et l'horodatage de la requête.

API publique V26 / 6