Guia de integração

A API do Airbnb: como funciona o acesso e o que te permite mesmo fazer

Escrito para o programador ou fundador técnico a quem pediram para «ligar o Airbnb e pronto». Explica como é concedido o acesso de parceiro, o que a API pode e não pode alterar, e as falhas concretas que fazem uma integração com o Airbnb parecer saudável sem fazer nada. Tudo o que aqui está vem de operar esta integração em produção.

O que é a API do Airbnb

Não existe uma única “API do Airbnb” pública. O que existe é uma API de parceiros: uma superfície REST que o Airbnb abre a empresas de software aprovadas para que os seus clientes — anfitriões e gestores de alojamento local — possam gerir anúncios fora do airbnb.com. Não está aberta a qualquer pessoa com um cartão de crédito, e não há nenhuma sandbox onde te possas registar numa terça-feira à tarde.

A superfície em si é ampla. Uma ligação com autorização total pode ler e escrever o conteúdo do anúncio, fotos, quartos e camas, comodidades, o calendário, o preço por noite, as definições de reserva, as mensagens com hóspedes, reservas, avaliações, ofertas especiais, alterações de reservas e transações de pagamentos. As limitações quase nunca são “o endpoint não existe”. Têm a ver com quem autorizou o quê, e para que anúncio.

Como obtenho acesso à API do Airbnb?

Antes da tua primeira escrita bem-sucedida têm de se cumprir três coisas, e são concedidas por três partes diferentes.

O Airbnb aprova a tua empresa como parceira de software. Envias a candidatura, descreves o produto que estás a construir e és avaliado dentro de uma categoria de produto: software de gestão de propriedades, ferramenta de mensagens, ferramenta de preços. A aprovação traz um cliente OAuth (um client id e um secret) limitado a essa categoria. É uma análise comercial e de conformidade da tua empresa, não um registo de programador, e mede-se em semanas ou meses.
Cada anfitrião autoriza a tua app. A aprovação dá-te a possibilidade de pedir; não te dá dados. Cada anfitrião passa por um ecrã de consentimento OAuth, escolhe o que a tua app pode gerir e concede-te tokens para a sua conta. Um anfitrião, uma autorização.
Cada anúncio é aberto à API. É o passo que apanha toda a gente de surpresa, por isso tem uma secção própria mais abaixo. Autorizar a conta não autoriza os anúncios que ela contém.

Não existe um nível self-service

Se o teu plano contava com um portal de programadores, uma chave de teste e uma sandbox, reescreve o plano. Ou passas tu pela aprovação de parceiro, ou integras através de uma empresa que já a tem. A Repull é a segunda opção: chamas uma única API REST e os anfitriões ligam-se a nós.

Do lado da Repull, todo esse fluxo é uma única sessão alojada: o teu servidor cria-a, redireciona o anfitrião e recebes uma ligação de volta. O funcionamento, incluindo os parâmetros de redirecionamento, está no guia para ligar o 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" }'

Que âmbito deve a tua app pedir?

O ecrã de consentimento não é um único sim. O anfitrião concede um nível, e o nível que pedes decide tanto o que podes fazer como se a ligação é sequer possível.

Gestão de propriedades (acesso total): leitura e ainda escrita de anúncios, calendário e preços. O que um PMS ou channel manager precisa.
Mensagens: leitura de tudo e envio de mensagens a hóspedes. Sem gestão de anúncios, calendário ou preços.
Só leitura: anúncios, reservas, calendários, mensagens e avaliações. O nível certo para analytics, relatórios e BI.

A gestão de propriedades é exclusiva: uma app por conta de anfitrião

A conta Airbnb de um anfitrião só pode conceder gestão de propriedades a uma app de cada vez. Se já sincroniza com outro PMS ou channel manager, a tua ligação de acesso total falha, e falha no consentimento, à frente do cliente que estás a integrar.

É a maior limitação de qualquer estratégia de integração com o Airbnb, e é uma decisão de produto, não técnica. Se estás a construir algo que convive com um PMS já instalado — um produto de comunicação com hóspedes, uma ferramenta de avaliações, um painel de analytics —, pede mensagens ou só leitura e ligas-te sem problemas ao lado dele. Pede acesso total por hábito e tornaste o teu produto incompatível com a ferramenta que o teu cliente já paga.

O nível fica ainda fixado no momento do consentimento. Mudá-lo obriga o anfitrião a passar por uma nova autorização.

Os níveis mais restritos também convertem melhor, porque o ecrã de consentimento mostra menos permissões, e menos alarmantes. Vê Ligar o Airbnb para fixares um nível por sessão ou deixares o anfitrião escolher.

Porque é que uma conta ligada continua a recusar todas as escritas

O Airbnb autoriza a sincronização por API anúncio a anúncio, não conta a conta. Cada anúncio tem a sua própria categoria de sincronização. Um anúncio com categoria none está fechado à API e o Airbnb recusa qualquer escrita nele, seja qual for o estado da conta.

As categorias que importam:

sync_all: conteúdo, tarifas e disponibilidade são geridos pela API.
sync_rates_and_availability: as escritas de calendário e preços funcionam; o conteúdo do anúncio fica com o anfitrião.
none: qualquer escrita é recusada.

Voltar a ligar a conta não resolve

O ticket de suporte diz “ligámos o Airbnb mas os preços não sincronizam em três dos quarenta anúncios”. O instinto é mandar o anfitrião outra vez pelo OAuth. Não muda nada: a autorização da conta já é válida, e os outros trinta e sete anúncios estão a ser escritos neste momento. O interruptor que está desligado é o do anúncio, dentro do Airbnb, e só alguém com acesso a esse anúncio o pode ligar.

Mostra-o como um estado por anúncio na tua própria interface desde o primeiro dia, ou vais descobri-lo pelos clientes. A Repull devolve syncCategory e writable para cada anúncio em GET /v1/channels/airbnb/listings, e recusa a escrita antes de qualquer coisa chegar ao Airbnb — vê listing_not_api_connected.

Posso atualizar preços e disponibilidade através da API do Airbnb?

Sim, num anúncio aberto à API e com uma autorização de gestão de propriedades. É a parte do Airbnb que se comporta como seria de esperar: escritas por data, aplicadas ao calendário do anúncio e refletidas no anúncio.

O preço por noite, aberto ou fechado, as noites mínimas e máximas, e as restrições de chegada e de saída podem ser escritos por data, juntamente com regras de disponibilidade ao nível do anúncio, como as noites mínimas por defeito, a antecedência de reserva e os dias de preparação.

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

O Airbnb recusa uma data bloqueada que não diz porque está bloqueada

Quando marcas uma data como indisponível, o Airbnb quer o motivo junto: BLOCKED_BY_HOST para um bloqueio do anfitrião, ou OUTSIDE_RESERVATION para uma data ocupada por uma reserva feita noutro canal. Envia o bloqueio sem ele e a escrita é recusada.

A distinção não é mera contabilidade. Uma data marcada como ocupada por uma reserva externa é lida pelo Airbnb de forma diferente de uma data que o anfitrião simplesmente fechou, e um channel manager que comunica cada reserva de outro canal como bloqueio do anfitrião está a dizer ao Airbnb algo falso sobre o anúncio. Decide a que subtipo corresponde cada um dos teus motivos de bloqueio antes de escreveres o primeiro.

Todos os parâmetros estão em Enviar disponibilidade para o Airbnb e Atualizar preços no Airbnb. Se queres que uma só escrita chegue a todos os canais ligados de uma vez e não apenas ao Airbnb, isso é PUT /v1/availability/{propertyId} — vê Atualizar preços.

Posso alterar o conteúdo do anúncio?

Em parte, e é aqui que uma integração com o Airbnb mais vezes falha em silêncio. Duas regras explicam quase tudo.

Publicar não é uma só chamada

Enviar o conteúdo de um anúncio para o Airbnb são até oito chamadas independentes — detalhes, descrição, comodidades, quartos, políticas, fotos, preços, tarefas de saída — e cada uma pode falhar sozinha. Uma publicação parcial é o resultado normal, e não há volta atrás: as secções que entraram ficam aplicadas. Qualquer modelo de estado que trate a publicação como um único booleano estará errado numa semana. Reporta por secção.

Um 200 não prova que a alteração foi aplicada

Num anúncio estabelecido, o Airbnb trata parte do conteúdo como gerida pelo anfitrião e não aceita alterações através de nenhuma API. Não responde com um erro. O pedido devolve 200, a resposta indica os atributos bloqueados e nada é aplicado neles. Os que mais se bloqueiam: o título, o resumo e o texto do espaço, a categoria do tipo de propriedade, a opção de check-in, os campos da morada e as comodidades individuais.

É o caso comum, não um caso raro

1180 dos 5917 anúncios do Airbnb sincronizados através da Repull têm pelo menos um atributo bloqueado. Se a tua integração deduz o sucesso a partir do código HTTP, mais ou menos um anúncio em cada cinco vai dar por boa uma atualização de conteúdo enquanto mostra o texto antigo aos hóspedes.

Um bloqueio também não é um erro para voltar a tentar. Não há backoff, nem endpoint alternativo, nem permissão que o contorne: ou alguém edita o campo no Airbnb, ou fica assim. Trata-o como informação para mostrar ao teu utilizador, nunca como uma falha para voltar a pôr na fila.

Lê o conjunto bloqueado antecipadamente em vez de o descobrires por comparação. GET /v1/channels/airbnb/listings/{id}/details devolve lockedFields para o anúncio, e cada escrita devolve blockedFields com o que o teu pedido atingiu. O contrato completo — que secções são enviadas, o que significa cada código de erro, como é uma publicação parcial — está no contrato de publicação do Airbnb.

Para além da publicação, a superfície de conteúdo detalhada é real e útil: fotos (carregar, reordenar, definir capa), quartos e camas, comodidades, descrições por idioma, números de registo, avisos de segurança para hóspedes e o guia de chegada.

Mensagens, reservas, avaliações e alterações

Mensagens: ler conversas e mensagens, enviar, editar, reagir, marcar como lida. Disponível no nível de mensagens, além do acesso total, e é isso que torna viável um produto de comunicação com hóspedes ao lado de um PMS já instalado. Mensagens com hóspedes.
Reservas: listar e ler, com ações sobre um código de reserva. Reservas.
Alterações: o Airbnb é o único grande canal com um verdadeiro fluxo de alterações por API: criar uma alteração, lê-la, aceitá-la, recusá-la ou cancelá-la. As mudanças de datas e de preço numa reserva do Airbnb passam por aí e não por uma edição direta. Alterações.
Avaliações: listar, responder e editar uma resposta. Avaliações.
Ofertas especiais e pré-aprovações: criar e retirar, que é como respondes a um pedido com um preço. Ofertas especiais.
Transações: pagamentos e registos financeiros, leitura e atualização. Transações.

Para veres canal a canal o que é suportado, parcial ou não suportado, a matriz de capacidades é a versão honesta, e marca o parcial como parcial.

Armadilhas que custam dias a quem integra

Cada uma custou-nos tempo em produção. Estão na ordem em que costumam aparecer.

Os ids de 19 dígitos transformam-se em silêncio na conta errada

Os ids modernos de anfitriões e anúncios do Airbnb têm 19 dígitos, acima de 2⁵³, o maior inteiro que o JavaScript representa com exatidão. A partir daí os doubles estão espaçados de 256 em 256, por isso o JSON.parse encaixa o valor num id vizinho, com ar perfeitamente válido:

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

Os pedidos continuam a autenticar, porque a autenticação é o bearer token. Mas cada chamada baseada nesse id — lista de anúncios, reservas, disponibilidade, mensagens — pergunta por uma conta que não existe, e o Airbnb responde com um resultado vazio em vez de um erro. Seis anfitriões de cinco clientes estiveram assim do nosso lado, com todos os health checks a verde e sem nunca importar nada.

Lê o id a partir do texto bruto da resposta antes de qualquer coisa o converter, mantém-no como texto em toda a tua stack e compara-o como texto na base de dados. A Repull devolve os ids do Airbnb como texto em todo o lado por este motivo; vê IDs e IDs externos.

Um 200 que não aplicou nada

Explicado acima. A regra a programar: sucesso é um blockedFields vazio, não um 2xx.

Uma conta saudável com anúncios onde não se pode escrever

Também explicado acima. Modela o estado de sincronização por anúncio, não por conta, ou o teu painel vai dizer ligado enquanto três anúncios se desalinham em silêncio.

Descobrir a exclusividade a meio de uma demo com o cliente

Descobre que ferramenta o teu potencial cliente usa antes de desenhares o fluxo de consentimento. Pedir gestão de propriedades quando o anfitrião já a concedeu noutro lado é uma ligação falhada à frente do cliente, e a solução é uma mudança de produto, não uma nova tentativa.

Tokens, limites de utilização e o que nunca acaba

Os tokens de acesso expiram e renovam-se, os anfitriões revogam, anúncios são adicionados e removidos, o Airbnb impõe limites de utilização e a forma da API muda. Uma integração com o Airbnb não é um projeto com data de fim; é um serviço que agora operas. Orçamenta a monitorização, os avisos de nova ligação e as escalas de piquete, porque são a maior parte do custo ao longo do tempo.

O que custa construir isto por conta própria

Com honestidade, por ordem:

A aprovação de parceiro. De semanas a meses, com uma possibilidade real de um não. Até chegar só podes desenvolver com base na documentação, e não podes prometer uma data a nenhum cliente.
O ciclo de vida do OAuth e da ligação. Consentimento, tokens, renovação, níveis de âmbito, revogação, pedidos de nova autorização e uma interface que explique um âmbito exclusivo a um anfitrião que não é técnico.
A superfície em si. Anúncios, fotos, quartos, comodidades, descrições, definições, calendário, preços, mensagens, reservas, avaliações, ofertas, alterações e transações, cada um com a sua forma, o seu comportamento perante falhas parciais e a sua normalização para o modelo que o teu produto usa de facto.
Trabalho de correção que ninguém vê até ver. Ids como texto, campos bloqueados, estado de sincronização por anúncio, subtipos de bloqueio, resultados de publicação por secção.
Falhas contínuas. Mudanças na origem, funcionalidades descontinuadas, novos limites de utilização, anfitriões a revogar, anúncios a desaparecer. Isto nunca chega a zero.

É perfeitamente razoável construir isto se a conectividade com o Airbnb é o teu produto. É um mau uso do ano de uma equipa pequena se o Airbnb é só uma peça de outra coisa que estás a construir, e piora quando chega o segundo canal, porque o Booking.com não partilha quase nenhum destes pressupostos. O guia da API do Booking.com é a comparação.

Onde entra a Repull

A Repull é uma API REST e uma só chave para Airbnb, Booking.com, Vrbo, Plum Guide e os sistemas de gestão de propriedades que os anfitriões já usam. Nós tratamos das relações com os parceiros; os teus utilizadores ligam-se sozinhos através de um fluxo alojado com a tua marca; tu nunca lidas com as credenciais deles.

Um fluxo de ligação por canal. POST /v1/connect/{provider} cria uma sessão alojada e devolve-te uma ligação. Connect.
Uma escrita de calendário para todos os canais. PUT /v1/availability/{propertyId} envia preço e disponibilidade para todos os canais a que uma propriedade está ligada; as rotas por canal servem para as definições que só existem num canal.
As falhas são mostradas, não disfarçadas. Campos bloqueados, estado de sincronização por anúncio e resultados de publicação por secção voltam como dados que podes mostrar a um utilizador, porque fingir que uma escrita entrou é pior do que dizer que não.
Webhooks com histórico de entregas e reenvio. Webhooks.

Começa pelo guia de início rápido, ou lê a visão geral dos canais para veres a forma da superfície por canal. Se és uma plataforma a integrar isto para os teus próprios clientes, e não para ti, o guia para plataformas cobre esse modelo pergunta a pergunta.

Se as propriedades que estás a integrar já estão num sistema de gestão de propriedades, esse é um segundo problema, separado: um PMS dá-te a sua própria visão de uma reserva, não a API do canal. Os guias de Guesty, Hostaway, Hospitable, Lodgify e OwnerRez explicam o que cada um expõe, e a matriz de cobertura tem-nos todos. Uma só chave cobre ao mesmo tempo uma ligação a um PMS e uma ligação direta a um canal.

Perguntas frequentes

Como obtenho acesso à API do Airbnb?

O Airbnb não vende chaves de API em self-service. Candidatas-te ao programa de parceiros de software, a tua empresa é avaliada e aprovada para uma área de produto concreta, por exemplo gestão de propriedades ou apenas mensagens. Depois de aprovado recebes um cliente OAuth, e cada anfitrião autoriza a tua app a partir da sua própria conta Airbnb. Conta com meses para a aprovação, não dias, e com a possibilidade de não seres aprovado. A alternativa é integrares através de um parceiro que já tem a aprovação, e é isso que a Repull é.

Posso atualizar preços através da API do Airbnb?

Sim, se o anfitrião concedeu gestão de propriedades e ativou a sincronização por API nesse anúncio concreto. O Airbnb autoriza a sincronização anúncio a anúncio, por isso uma conta ligada pode ter anúncios que recusam qualquer escrita. O preço por noite, a disponibilidade, as noites mínimas e máximas e as restrições por data podem ser escritos em qualquer anúncio aberto à API.

Porque é que a minha escrita no Airbnb devolve 200 mas não muda nada?

O Airbnb bloqueia os campos geridos pelo anfitrião em anúncios já estabelecidos. Uma escrita num campo bloqueado devolve 200, indica que o campo está bloqueado e não aplica nada. O título, o resumo e o texto do espaço, a categoria do tipo de propriedade, a opção de check-in, a morada e as comodidades individuais são os que mais se bloqueiam. Não se resolve a tentar outra vez: ou alguém edita o campo no Airbnb, ou fica como está.

Duas apps podem gerir a mesma conta Airbnb?

Não para a gestão de propriedades. O Airbnb trata esse âmbito como exclusivo: uma app de cada vez por conta de anfitrião. Se o anfitrião já sincroniza com outro PMS ou channel manager, uma ligação de acesso total vai falhar. Uma ligação só de mensagens ou só de leitura pede um âmbito mais restrito e liga-se ao lado da app que já lá está.

Porque é que a minha integração com o Airbnb devolve resultados vazios sem qualquer erro?

Verifica se converteste um id do Airbnb em número. Os ids modernos de anfitriões e anúncios do Airbnb têm 19 dígitos, acima do maior inteiro que o JavaScript representa com exatidão, por isso o JSON.parse arredonda-os em silêncio para um id vizinho com ar válido. Os pedidos continuam a autenticar, porque isso depende do token, mas cada chamada baseada nesse id pergunta por uma conta que não existe e recebe uma lista vazia em vez de um erro. Lê e guarda esses ids como texto, do início ao fim.

Quanto custa o acesso à API do Airbnb?

O Airbnb não cobra pelo acesso à API de parceiros em si; o custo está no processo de aprovação, no desenvolvimento e em manter a integração viva. Para saberes quanto custa uma integração através da Repull, escreve para hello@repull.dev e fazemos-te uma proposta conforme o teu volume e os canais de que precisas.

Fala connosco sobre o acesso ao Airbnb

Conta-nos o que estás a construir, quantos anúncios prevês e de que canais precisas além do Airbnb. Respondemos com a forma da integração e quanto custa.

Escreve-nos sobre acesso e preços Lê o guia de início rápido

Continua a ler