Guide d'intégration

L'API Airbnb : comment fonctionne l'accès, et ce qu'elle permet vraiment

Écrit pour le développeur ou le fondateur technique à qui on a demandé de « juste connecter Airbnb ». On y explique comment l'accès partenaire est accordé, ce que l'API peut et ne peut pas modifier, et les pannes précises qui font qu'une intégration Airbnb a l'air saine sans rien faire. Tout ce qui est écrit ici vient de l'exploitation de cette intégration en production.

Ce qu'est l'API Airbnb

Il n'existe pas une seule “API Airbnb” publique. Ce qui existe, c'est une API partenaires : une surface REST qu'Airbnb ouvre à des éditeurs de logiciels approuvés pour que leurs clients — hôtes et gestionnaires de locations — puissent gérer leurs annonces en dehors d'airbnb.com. Elle n'est pas ouverte à n'importe qui avec une carte bancaire, et il n'y a aucune sandbox à laquelle s'inscrire un mardi après-midi.

La surface elle-même est large. Une connexion avec une autorisation complète peut lire et écrire le contenu de l'annonce, les photos, les chambres et les lits, les équipements, le calendrier, le prix par nuit, les paramètres de réservation, la messagerie voyageurs, les réservations, les avis, les offres spéciales, les modifications de réservation et les transactions de versement. Les limites ne sont presque jamais “l'endpoint n'existe pas”. Elles portent sur qui a autorisé quoi, et pour quelle annonce.

Comment obtenir l'accès à l'API Airbnb ?

Trois conditions doivent être réunies avant ta première écriture réussie, et elles sont accordées par trois acteurs différents.

1. Airbnb approuve ton entreprise comme partenaire logiciel.Tu candidates, tu décris le produit que tu construis, et tu es évalué dans une catégorie de produit : logiciel de gestion de biens, outil de messagerie, outil de tarification. L'approbation t'apporte un client OAuth (un client id et un secret) limité à cette catégorie. C'est un examen commercial et de conformité de ton entreprise, pas une inscription de développeur, et ça se compte en semaines ou en mois.
2. Chaque hôte autorise ton app.L'approbation te donne le droit de demander ; elle ne te donne pas de données. Chaque hôte passe par un écran de consentement OAuth, choisit ce que ton app peut gérer et t'accorde des tokens pour son compte. Un hôte, une autorisation.
3. Chaque annonce est ouverte à l'API.C'est l'étape qui surprend tout le monde, elle a donc sa propre section plus bas. Autoriser le compte n'autorise pas les annonces qu'il contient.

Côté Repull, tout ce flux tient en une seule session hébergée : ton serveur la crée, tu rediriges l'hôte et tu récupères une connexion. Le fonctionnement, paramètres de redirection compris, est dans le guide de connexion Airbnb.

curl -X POST 'https://api.repull.dev/v1/connect/airbnb' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "redirectUrl": "https://yourapp.com/connected", "accessType": "full_access" }'

Quel périmètre ton app doit-elle demander ?

L'écran de consentement n'est pas un simple oui. L'hôte accorde un niveau, et le niveau que tu demandes décide à la fois de ce que tu peux faire et de la possibilité même de te connecter.

• Gestion de biens (accès complet) : lecture, plus écriture des annonces, du calendrier et des prix. Ce dont un PMS ou un channel manager a besoin.
• Messagerie : lecture de tout, plus envoi de messages aux voyageurs. Pas de gestion des annonces, du calendrier ni des prix.
• Lecture seule: annonces, réservations, calendriers, messages et avis. Le bon niveau pour l'analytique, le reporting et la BI.

Les niveaux plus étroits convertissent aussi mieux, parce que l'écran de consentement affiche moins de permissions, et des permissions moins inquiétantes. Vois Connecter Airbnbpour fixer un niveau par session ou laisser l'hôte choisir.

Pourquoi un compte connecté refuse encore toutes les écritures

Airbnb autorise la synchronisation API annonce par annonce, pas compte par compte. Chaque annonce a sa propre catégorie de synchronisation. Une annonce dont la catégorie est noneest fermée à l'API et Airbnb refuse toute écriture dessus, quel que soit l'état du compte.

Les catégories qui comptent :

• sync_all: le contenu, les tarifs et la disponibilité sont gérés via l'API.
• sync_rates_and_availability: les écritures de calendrier et de prix fonctionnent ; le contenu de l'annonce reste à l'hôte.
• none : toute écriture est refusée.

Puis-je mettre à jour les prix et la disponibilité via l'API Airbnb ?

Oui, sur une annonce ouverte à l'API et avec une autorisation de gestion de biens. C'est la partie d'Airbnb qui se comporte comme on l'espère : des écritures par date, appliquées au calendrier de l'annonce et visibles sur l'annonce.

Le prix par nuit, l'ouverture ou la fermeture, les nuits minimum et maximum, l'arrivée et le départ interdits sont tous modifiables par date, avec des règles de disponibilité au niveau de l'annonce comme le minimum de nuits par défaut, le délai de réservation et les jours de battement.

# Block a range on Airbnb, saying why it is blocked
curl -X PUT 'https://api.repull.dev/v1/channels/airbnb/listings/4118/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "calendar",
    "operations": [{
      "dates": ["2026-07-01:2026-07-04"],
      "availability": "unavailable",
      "busy_subtype": "OUTSIDE_RESERVATION"
    }]
  }'

Le détail des paramètres est dans Envoyer la disponibilité à Airbnb et Mettre à jour les prix Airbnb. Si tu veux qu'une seule écriture arrive sur tous les canaux connectés à la fois et pas seulement sur Airbnb, c'est PUT /v1/availability/{propertyId} — vois Mettre à jour les prix.

Puis-je modifier le contenu d'une annonce ?

En partie, et c'est là qu'une intégration Airbnb échoue le plus souvent sans bruit. Deux règles expliquent presque tout.

Publier, ce n'est pas un seul appel

Envoyer le contenu d'une annonce à Airbnb représente jusqu'à huit appels indépendants — détails, description, équipements, chambres, règles, photos, prix, tâches de départ — et chacun peut échouer de son côté. Une publication partielle, c'est le résultat normal, et il n'y a pas de retour arrière : les sections passées restent appliquées. Tout modèle d'état qui traite la publication comme un seul booléen sera faux en une semaine. Rends compte section par section.

Un 200 ne prouve pas que la modification a été appliquée

Sur une annonce établie, Airbnb considère une partie du contenu comme gérée par l'hôte et n'accepte aucune modification via une API. Il ne répond pas par une erreur. La requête renvoie 200, la réponse liste les attributs verrouillés et rien n'est appliqué pour eux. Les plus souvent verrouillés : le titre, le résumé et le texte du logement, la catégorie de type de logement, l'option d'arrivée, les champs d'adresse et les équipements individuels.

Lis l'ensemble verrouillé à l'avance au lieu de le découvrir par comparaison. GET /v1/channels/airbnb/listings/{id}/details renvoie lockedFieldspour l'annonce, et chaque écriture renvoie blockedFieldspour ce que ta requête a touché. Le contrat complet — quelles sections sont envoyées, ce que signifie chaque code d'erreur, à quoi ressemble une publication partielle — est dans le contrat de publication Airbnb.

Au-delà de la publication, la surface de contenu détaillée est réelle et utile : photos (envoyer, réordonner, choisir la couverture), chambres et lits, équipements, descriptions par langue, numéros d'enregistrement, informations de sécurité pour les voyageurs et le guide d'arrivée.

Messagerie, réservations, avis et modifications

• Messagerie: lire les fils et les messages, envoyer, modifier, réagir, marquer comme lu. Disponible au niveau messagerie comme en accès complet, et c'est ce qui rend viable un produit de communication voyageurs à côté d'un PMS déjà en place. Messagerie voyageurs.
• Réservations : lister et lire, avec des actions sur un code de réservation. Réservations.
• Modifications: Airbnb est le seul grand canal avec un vrai flux de modification par API : créer une modification, la lire, l'accepter, la refuser ou l'annuler. Les changements de dates et de prix sur une réservation Airbnb passent par là, pas par une édition directe. Modifications.
• Avis : lister, répondre et modifier une réponse. Avis.
• Offres spéciales et pré-approbations: créer et retirer, c'est comme ça que tu réponds à une demande avec un prix. Offres spéciales.
• Transactions : versements et données financières, lecture et actualisation. Transactions.

Pour voir canal par canal ce qui est pris en charge, partiel ou non pris en charge, la matrice des capacités est la version honnête, et elle indique le partiel comme partiel.

Les pièges qui coûtent des jours aux intégrateurs

Chacun nous a coûté du temps en production. Ils sont listés dans l'ordre où ils mordent en général.

Les ids à 19 chiffres deviennent sans bruit le mauvais compte

Les ids modernes des hôtes et des annonces Airbnb font 19 chiffres, au-delà de 2⁵³, le plus grand entier que JavaScript représente exactement. Au-dessus, les doubles sont espacés de 256, donc JSON.parse ramène la valeur sur un id voisin, tout à fait plausible :

JSON.parse('{"user_id":1693389202618766851}').user_id
// → 1693389202618766800   ← a different account

Les requêtes s'authentifient toujours, parce que l'authentification, c'est le bearer token. Mais chaque appel basé sur cet id — liste des annonces, réservations, disponibilité, messages — interroge un compte qui n'existe pas, et Airbnb répond par un résultat vide plutôt que par une erreur. Six hôtes de cinq clients sont restés dans cet état chez nous, tous les health checks au vert, sans jamais rien importer.

Lis l'id dans le texte brut de la réponse avant que quoi que ce soit ne le parse, garde-le en chaîne dans toute ta stack et compare-le comme du texte en base. Repull renvoie partout les ids Airbnb sous forme de chaînes pour cette raison ; vois Identifiants et identifiants externes.

Un 200 qui n'a rien appliqué

Expliqué plus haut. La règle à coder : le succès, c'est un blockedFields vide, pas un 2xx.

Un compte sain avec des annonces non modifiables

Également expliqué plus haut. Modélise l'état de synchronisation par annonce, pas par compte, sinon ton tableau de bord affichera connecté pendant que trois annonces dérivent sans bruit.

Découvrir l'exclusivité en pleine démo client

Renseigne-toi sur l'outil qu'utilise ton futur client avant de concevoir le flux de consentement. Demander la gestion de biens alors que l'hôte l'a déjà accordée ailleurs, c'est une connexion ratée devant le client, et la solution est un changement de produit, pas une nouvelle tentative.

Tokens, limites de débit et ce qui ne s'arrête jamais

Les tokens d'accès expirent et se renouvellent, les hôtes révoquent, des annonces arrivent et disparaissent, Airbnb limite le débit et la forme de l'API évolue. Une intégration Airbnb n'est pas un projet avec une date de fin ; c'est un service que tu opères désormais. Prévois le budget de la supervision, des demandes de reconnexion et des astreintes, parce qu'ils représentent la majeure partie du coût dans la durée.

Ce que coûte une intégration maison

Honnêtement, dans l'ordre :

1. L'approbation partenaire.Des semaines à des mois, avec un vrai risque de refus. Tant qu'elle n'est pas là, tu ne peux développer que sur la documentation, et tu ne peux promettre aucune date à un client.
2. Le cycle de vie OAuth et des connexions. Consentement, tokens, renouvellement, niveaux de périmètre, révocation, demandes de réautorisation, et une interface qui explique un périmètre exclusif à un hôte non technique.
3. La surface elle-même.Annonces, photos, chambres, équipements, descriptions, paramètres, calendrier, prix, messagerie, réservations, avis, offres, modifications et transactions, chacun avec sa propre forme, son propre comportement en cas d'échec partiel et sa propre normalisation dans le modèle que ton produit utilise vraiment.
4. Un travail de fiabilité invisible jusqu'au jour où il ne l'est plus. Ids en chaînes, champs verrouillés, état de synchronisation par annonce, sous-types de blocage, résultats de publication par section.
5. La casse permanente. Changements en amont, fonctions retirées, limites de débit qui bougent, hôtes qui révoquent, annonces qui disparaissent. Ça ne tombe jamais à zéro.

C'est tout à fait raisonnable à construire si la connectivité Airbnb estton produit. C'est une mauvaise façon d'utiliser une année d'une petite équipe si Airbnb n'est qu'une brique d'autre chose que tu construis, et ça empire quand le deuxième canal arrive, parce que Booking.com ne partage presque aucune de ces hypothèses. Le guide de l'API Booking.com sert de comparaison.

Où se situe Repull

Repull, c'est une seule API REST et une seule clé pour Airbnb, Booking.com, Vrbo, Plum Guide et les logiciels de gestion que les hôtes utilisent déjà. On gère les relations partenaires ; tes utilisateurs se connectent eux-mêmes via un flux hébergé à tes couleurs ; tu ne manipules jamais leurs identifiants.

• Un flux de connexion par canal. POST /v1/connect/{provider} crée une session hébergée et te renvoie une connexion. Connect.
• Une écriture de calendrier pour tous les canaux. PUT /v1/availability/{propertyId}envoie le prix et la disponibilité à tous les canaux auxquels un bien est connecté ; les routes par canal servent aux réglages qui n'existent que sur un seul canal.
• Les échecs sont montrés, pas maquillés.Champs verrouillés, état de synchronisation par annonce et résultats de publication par section reviennent sous forme de données que tu peux montrer à un utilisateur, parce que faire croire qu'une écriture est passée est pire que dire qu'elle ne l'est pas.
• Des webhooks avec historique de livraison et rejeu. Webhooks.

Commence par le démarrage rapide, ou lis la présentation des canaux pour voir la forme de la surface par canal. Si tu es une plateforme qui intègre tout ça pour ses propres clients plutôt que pour elle-même, le guide pour les plateformes couvre ce modèle question par question.

Si les biens que tu intègres sont déjà dans un logiciel de gestion, c'est un deuxième problème, distinct : un PMS te donne sa propre vision d'une réservation, pas l'API du canal. Les guides Guesty, Hostaway, Hospitable, Lodgify et OwnerRez expliquent ce que chacun expose, et la matrice de couverture les liste tous. Une seule clé couvre à la fois une connexion PMS et une connexion directe à un canal.

Questions fréquentes