Guía de integración

La API de Airbnb: cómo funciona el acceso y qué te permite hacer de verdad

Escrita para el ingeniero o el fundador técnico al que le han pedido que «simplemente conecte Airbnb». Explica cómo se concede el acceso de partners, qué puede y qué no puede cambiar la API, y los fallos concretos que hacen que una integración con Airbnb parezca sana sin hacer nada. Todo lo que dice viene de operar esta integración en producción.

Qué es la API de Airbnb

No existe una única “API de Airbnb” pública. Lo que existe es una API de partners: una superficie REST que Airbnb abre a empresas de software aprobadas para que sus clientes — anfitriones y gestores de alquiler vacacional— puedan gestionar anuncios desde fuera de airbnb.com. No está abierta a cualquiera con una tarjeta de crédito, y no hay ningún sandbox en el que te puedas registrar un martes por la tarde.

La superficie en sí es amplia. Una conexión con autorización completa puede leer y escribir el contenido del anuncio, las fotos, las habitaciones y camas, los servicios, el calendario, el precio por noche, la configuración de reservas, los mensajes con huéspedes, las reservas, las reseñas, las ofertas especiales, las modificaciones de reservas y las transacciones de pagos. Las limitaciones casi nunca son “el endpoint no existe”. Tienen que ver con quién autorizó qué, y para qué anuncio.

¿Cómo consigo acceso a la API de Airbnb?

Antes de tu primera escritura con éxito tienen que cumplirse tres cosas, y las conceden tres partes distintas.

1. Airbnb aprueba a tu empresa como partner de software. Envías la solicitud, describes el producto que estás construyendo y te evalúan dentro de una categoría de producto: software de gestión de propiedades, herramienta de mensajería, herramienta de precios. La aprobación trae un cliente OAuth (un client id y un secret) limitado a esa categoría. Es una revisión comercial y de cumplimiento de tu empresa, no un registro de desarrollador, y se mide en semanas o meses.
2. Cada anfitrión autoriza tu app. La aprobación te da la posibilidad de pedir acceso; no te da datos. Cada anfitrión pasa por una pantalla de consentimiento OAuth, elige lo que tu app puede gestionar y te concede tokens para su cuenta. Un anfitrión, una autorización.
3. Cada anuncio se abre a la API. Este es el paso que pilla a todo el mundo por sorpresa, así que tiene su propia sección más abajo. Autorizar la cuenta no autoriza los anuncios que contiene.

En Repull todo ese flujo es una única sesión alojada: tu servidor la crea, rediriges al anfitrión y recibes una conexión de vuelta. El funcionamiento, incluidos los parámetros de redirección, está en la guía para conectar 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" }'

¿Qué alcance debe pedir tu app?

La pantalla de consentimiento no es un único sí. El anfitrión concede un nivel, y el nivel que pidas decide tanto lo que puedes hacer como si la conexión es posible siquiera.

• Gestión de propiedades (acceso completo): lectura más escritura de anuncios, calendario y precios. Lo que necesita un PMS o un channel manager.
• Mensajería: lectura de todo, más envío de mensajes a huéspedes. Sin gestión de anuncios, calendario ni precios.
• Solo lectura: anuncios, reservas, calendarios, mensajes y reseñas. El nivel adecuado para analítica, informes y BI.

Los niveles más limitados además convierten mejor, porque la pantalla de consentimiento muestra menos permisos y menos alarmantes. Consulta Conectar Airbnb para ver cómo fijar un nivel por sesión o dejar que elija el anfitrión.

Por qué una cuenta conectada sigue rechazando todas las escrituras

Airbnb autoriza la sincronización por API anuncio por anuncio, no cuenta por cuenta. Cada anuncio tiene su propia categoría de sincronización. Un anuncio con categoría none está cerrado a la API y Airbnb rechaza cualquier escritura en él, sea cual sea el estado de la cuenta.

Las categorías que importan:

• sync_all: el contenido, las tarifas y la disponibilidad se gestionan por la API.
• sync_rates_and_availability: las escrituras de calendario y precios funcionan; el contenido del anuncio sigue en manos del anfitrión.
• none: se rechaza cualquier escritura.

¿Puedo actualizar precios y disponibilidad con la API de Airbnb?

Sí, en un anuncio abierto a la API y con un permiso de gestión de propiedades. Esta es la parte de Airbnb que se comporta como cabría esperar: escrituras por fecha, aplicadas al calendario del anuncio y reflejadas en el anuncio.

El precio por noche, abierto o cerrado, las noches mínimas y máximas, y las restricciones de llegada y salida se pueden escribir por fecha, junto con reglas de disponibilidad a nivel de anuncio como las noches mínimas por defecto, la antelación de reserva y los días de preparación.

# 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"
    }]
  }'

Todos los parámetros están en Enviar disponibilidad a Airbnb y Actualizar precios en Airbnb. Si quieres que una sola escritura llegue a todos los canales conectados a la vez y no solo a Airbnb, eso es PUT /v1/availability/{propertyId}; consulta Actualizar precios.

¿Puedo cambiar el contenido del anuncio?

En parte, y aquí es donde una integración con Airbnb suele fallar en silencio. Dos reglas lo explican casi todo.

Publicar no es una sola llamada

Enviar el contenido de un anuncio a Airbnb son hasta ocho llamadas independientes —detalles, descripción, servicios, habitaciones, políticas, fotos, precios, tareas de salida— y cada una puede fallar por su cuenta. Una publicación parcial es lo normal, y no hay vuelta atrás: las secciones que entraron se quedan aplicadas. Cualquier modelo de estado que trate la publicación como un único booleano estará mal en una semana. Infórmalo por sección.

Un 200 no prueba que el cambio se haya aplicado

En un anuncio ya establecido, Airbnb considera parte del contenido como gestionado por el anfitrión y no acepta cambios en él a través de ninguna API. No responde con un error. La petición devuelve 200, la respuesta indica los atributos bloqueados y no se aplica nada sobre ellos. Lo que más se bloquea: el título, el resumen y el texto del espacio, la categoría de tipo de propiedad, la opción de check-in, los campos de dirección y los servicios individuales.

Lee el conjunto bloqueado por adelantado en lugar de descubrirlo comparando. GET /v1/channels/airbnb/listings/{id}/details devuelve lockedFields para el anuncio, y cada escritura devuelve blockedFields con lo que ha tocado tu petición. El contrato completo —qué secciones se envían, qué significa cada código de error, cómo es una publicación parcial— está en el contrato de publicación de Airbnb.

Más allá de la publicación, la superficie de contenido detallada es real y útil: fotos (subir, reordenar, elegir portada), habitaciones y camas, servicios, descripciones por idioma, licencias turísticas, avisos de seguridad para huéspedes y la guía de llegada.

Mensajes, reservas, reseñas y modificaciones

• Mensajería: leer hilos y mensajes, enviar, editar, reaccionar, marcar como leído. Disponible en el nivel de mensajería además de en el de acceso completo, que es lo que hace viable un producto de comunicación con huéspedes junto a un PMS ya instalado. Mensajes con huéspedes.
• Reservas: listar y leer, con acciones sobre un código de reserva. Reservas.
• Modificaciones: Airbnb es el único gran canal con un flujo real de modificaciones por API: crear una modificación, leerla, aceptarla, rechazarla o cancelarla. Los cambios de fechas y de precio en una reserva de Airbnb pasan por ahí y no por una edición directa. Modificaciones.
• Reseñas: listar, responder y editar una respuesta. Reseñas.
• Ofertas especiales y preaprobaciones: crear y retirar, que es como respondes a una consulta con un precio. Ofertas especiales.
• Transacciones: registros de pagos y financieros, lectura y actualización. Transacciones.

Para ver canal por canal qué está soportado, qué es parcial y qué no, la matriz de capacidades es la versión honesta, y marca lo parcial como parcial.

Trampas que cuestan días a quien integra

Cada una de estas nos costó tiempo en producción. Están en el orden en que suelen morder.

Los ids de 19 dígitos se convierten en silencio en la cuenta equivocada

Los ids modernos de anfitriones y anuncios de Airbnb tienen 19 dígitos, más de 2⁵³, el mayor entero que JavaScript representa con exactitud. Por encima de eso, los doubles van de 256 en 256, así que JSON.parse ajusta el valor a un id vecino que parece totalmente válido:

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

Las peticiones se siguen autenticando, porque la autenticación es el bearer token. Pero cada llamada que usa ese id —listado de anuncios, reservas, disponibilidad, mensajes— pregunta por una cuenta que no existe, y Airbnb responde con un resultado vacío en lugar de un error. Seis anfitriones de cinco clientes estuvieron así en nuestro sistema, con todos los health checks en verde y sin importar nada nunca.

Lee el id del texto de la respuesta antes de que nada lo convierta, mantenlo como texto en todo tu stack y compáralo como texto en la base de datos. Repull devuelve los ids de Airbnb como texto en todas partes por este motivo; consulta IDs e IDs externos.

Un 200 que no aplicó nada

Explicado más arriba. La regla que tienes que programar: el éxito es un blockedFields vacío, no un 2xx.

Una cuenta sana con anuncios en los que no se puede escribir

También explicado más arriba. Modela el estado de sincronización por anuncio, no por cuenta, o tu panel dirá conectado mientras tres anuncios se desvían en silencio.

Descubrir la exclusividad en plena demo con un cliente

Averigua qué herramienta usa tu posible cliente antes de diseñar el flujo de consentimiento. Pedir gestión de propiedades cuando el anfitrión ya la concedió a otra app es una conexión fallida delante del cliente, y la solución es un cambio de producto, no un reintento.

Tokens, límites de uso y lo que nunca se acaba

Los tokens de acceso caducan y se renuevan, los anfitriones revocan permisos, se añaden y se quitan anuncios, Airbnb aplica límites de uso y la forma de la API cambia. Una integración con Airbnb no es un proyecto con fecha de fin; es un servicio que ahora operas tú. Presupuesta la monitorización, los avisos de reconexión y las guardias, porque son la mayor parte del coste a lo largo del tiempo.

Lo que cuesta construirlo por tu cuenta

Con honestidad, y por orden:

1. La aprobación como partner. De semanas a meses, con una posibilidad real de que digan que no. Hasta que llega solo puedes desarrollar contra la documentación, y no puedes prometerle una fecha a ningún cliente.
2. El ciclo de OAuth y de conexión. Consentimiento, tokens, renovación, niveles de alcance, revocación, avisos de reautorización y una interfaz que explique un alcance exclusivo a un anfitrión que no es técnico.
3. La superficie en sí. Anuncios, fotos, habitaciones, servicios, descripciones, configuración, calendario, precios, mensajes, reservas, reseñas, ofertas, modificaciones y transacciones, cada uno con su propia forma, su propio comportamiento ante fallos parciales y su propia normalización al modelo que use de verdad tu producto.
4. Trabajo de corrección que no se ve hasta que se ve. Ids como texto, campos bloqueados, estado de sincronización por anuncio, subtipos de bloqueo, resultados de publicación por sección.
5. Roturas continuas. Cambios en origen, funciones retiradas, cambios en los límites de uso, anfitriones que revocan, anuncios que dejan de responder. Esto nunca llega a cero.

Es algo totalmente razonable de construir si la conectividad con Airbnb es tu producto. Es un mal uso del año de un equipo pequeño si Airbnb es solo una pieza de otra cosa que estás construyendo, y empeora cuando llega el segundo canal, porque Booking.com no comparte casi ninguna de estas premisas. La guía de la API de Booking.com es la comparación.

Dónde encaja Repull

Repull es una API REST y una sola clave para Airbnb, Booking.com, Vrbo, Plum Guide y los sistemas de gestión de propiedades que los anfitriones ya usan. Nosotros tenemos las relaciones con los partners; tus usuarios se conectan solos a través de un flujo alojado con tu marca; tú nunca manejas sus credenciales.

• Un flujo de conexión por canal. POST /v1/connect/{provider} crea una sesión alojada y te devuelve una conexión. Connect.
• Una escritura de calendario para todos los canales. PUT /v1/availability/{propertyId} envía precio y disponibilidad a todos los canales a los que está conectada una propiedad; las rutas por canal están para los ajustes que solo existen en un canal.
• Los fallos se muestran, no se maquillan. Los campos bloqueados, el estado de sincronización por anuncio y los resultados de publicación por sección vuelven como datos que puedes enseñar a un usuario, porque fingir que una escritura entró es peor que decir que no.
• Webhooks con historial de entregas y reenvío. Webhooks.

Empieza por la guía de inicio rápido, o lee el resumen de canales para ver la forma de la superficie por canal. Si eres una plataforma que integra esto para sus propios clientes, y no para ti, la guía para plataformas cubre ese modelo pregunta por pregunta.

Si las propiedades que estás integrando ya están en un sistema de gestión de propiedades, ese es un segundo problema distinto: un PMS te da su propia visión de una reserva, no la API del canal. Las guías de Guesty, Hostaway, Hospitable, Lodgify y OwnerRez explican lo que expone cada uno, y la matriz de cobertura los tiene todos. Una sola clave cubre a la vez una conexión con un PMS y una conexión directa con un canal.

Preguntas frecuentes