Guia de integração

A API do Booking.com: como funciona o acesso e o que te permite mesmo fazer

Escrito para o programador ou fundador técnico a quem apontaram as APIs de conectividade do Booking.com. Explica como funcionam a designação como parceiro e a ligação por propriedade, o modelo de dados de que tudo o resto depende, e os dois ou três comportamentos que fazem uma atualização de tarifas no Booking.com resultar no papel e não mudar nada na prática.

O que é a API do Booking.com

As APIs do Booking.com são feitas para fornecedores de conectividade: os channel managers e os sistemas de gestão de propriedades que mantêm o alojamento sincronizado em nome de muitas propriedades ao mesmo tempo. Não são APIs para consumidores, não há uma superfície pública de pesquisa ou reserva para terceiros e não há um portal de programadores onde te registares.

Na prática são várias superfícies de produto debaixo de uma mesma parceria: disponibilidade e tarifas, reservas, configuração de propriedades e quartos, conteúdo, mensagens, avaliações e encargos. Comportam-se de forma diferente entre si, são concedidas separadamente e partes da superfície mais antiga são XML e não JSON. Vindo do Airbnb, quase nenhum dos teus pressupostos se mantém.

Como obtenho acesso à API do Booking.com?

Três camadas, concedidas por três partes diferentes, tal como no Airbnb, mas com outra forma.

1. O Booking.com designa a tua empresa como fornecedor de conectividade. Candidatas-te, és avaliado a nível comercial e técnico, e há um passo de certificação para as superfícies que pretendes usar. É uma relação ao nível da empresa que se mede em meses.
2. Recebes credenciais para uma conta de máquina. Ao contrário dos tokens OAuth por anfitrião do Airbnb, uma única conta de máquina atua por todas as propriedades ligadas a ti. Essa única credencial é o raio de impacto de todo o teu negócio, e muda a forma como lês os erros — vê a nota abaixo.
3. Cada propriedade liga-te a partir da sua própria Extranet. O anfitrião entra na Extranet do Booking.com, abre a lista de fornecedores de conectividade, procura o teu fornecedor pelo nome e clica em Ligar. Até o fazer, a tua conta de máquina não consegue ver essa propriedade. Também vai precisar do Hotel ID numérico à mão.

Com a Repull, a parte do lado do anfitrião é uma única sessão alojada com a tua marca; o anfitrião faz o passo na Extranet e cola o Hotel ID, e tu recebes uma ligação. O passo a passo está em Ligar o Booking.com.

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

Propriedades, quartos e planos tarifários

Percebe isto e o resto do Booking.com encaixa. Percebe mal e cada endpoint parece arbitrário.

Booking.com property   "hotel_id": 5432505        ← the building
└── room               "roomBookingId": 543250501 ← what a guest books
    └── rate plan      "rateId": 98765            ← the terms it sells on
        └── price at an occupancy                ← what you actually write

Uma propriedade é um edifício. Os quartos são o que os hóspedes reservam. Os planos tarifários são as condições comerciais com que um quarto é vendido, e um preço pertence a uma combinação (quarto, plano tarifário, data, ocupação), não a uma noite. Uma moradia com um quarto é o caso simples; um apart-hotel com vinte unidades é uma única propriedade com vinte quartos, e isso é o normal, não um caso raro.

A mesma unidade também pode aparecer em mais do que uma propriedade do Booking.com, normalmente porque foi republicada ao longo do tempo, e um quarto que não está associado a um dos teus anúncios não pertence a nada — as suas reservas não têm onde cair. Associa os quartos durante o fluxo de ligação, não depois.

Posso atualizar tarifas através da API do Booking.com?

Sim, e é a superfície mais usada de toda a parceria. Escreves um preço para um quarto num plano tarifário ao longo de um intervalo de datas, opcionalmente com restrições de estadia e de chegada na mesma chamada.

curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "rates",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "price": 210,
      "currency": "USD",
      "occupancy": 4
    }]
  }'

roomId e rateId vêm de GET /v1/channels/booking/properties/{id}/rooms. Tudo o resto do pedido — e há mais do que esperas — está em Atualizar preços no Booking.com.

Porque é que a minha atualização de preço no Booking.com não fez nada?

É a pergunta que traz as pessoas a esta página, e tem duas respostas independentes. As duas parecem um sucesso.

A ocupação faz parte da chave, não é uma preferência

O Booking.com não guarda “o preço desta noite”. Guarda um preço para uma noite para um número de pessoas num plano tarifário. Por isso a ocupação que envias decide que preço estás a substituir. Cada valor vai com uma ocupação, quer a indiques quer não.

• Indica uma ocupação acima do máximo com preço no plano e o Booking.com aceita o pedido e descarta o valor sem dizer nada. A noite fica com o que tinha — muitas vezes 0.00 — e a confirmação é idêntica, byte a byte, à de uma escrita bem-sucedida.
• Indica uma abaixo e recebes um 400. O preço publicado não muda.
• A capacidade do teu próprio anúncio não é o dado que conta. O que manda é o número que o Booking.com tem para esse plano tarifário. Lê-o em vez de o deduzires.

A Repull obtém a ocupação a partir dos próprios dados do Booking.com para o par (quarto, plano tarifário) quando não a indicas, devolve-te o valor usado e de onde veio, e recusa a escrita com um 422 quando não a consegue resolver. Nunca se envia um valor às cegas.

O recibo não é uma confirmação

O Booking.com costuma responder a uma escrita de tarifas com um recibo sem estado por data. O corpo é literalmente:

{"ok": ""}

Intervalos de datas, e a noite que perdes

Por baixo, o XML de disponibilidade e tarifas recebe um intervalo cuja data to não é escrita— é um limite exclusivo, tal como a data de saída exclui a última noite. A maioria dos calendários que já integraste trata as duas pontas como noites. Por isso a leitura natural de “1 a 7 de agosto” são sete noites, mas no pedido são seis, e a noite que perdes sem dares por isso é a última de cada intervalo que escreves.

É uma conversão de uma linha e um bug de uma semana, porque só te custa a última noite: o calendário parece mais ou menos certo, uma verificação rápida passa e a falha aparece como uma reserva perdida em vez de um erro.

O inventário é uma escrita à parte

Pôr preço numa noite não a abre para venda, e abri-la não lhe põe preço. Os quartos à venda e o fecho de vendas são um tipo de atualização próprio; enviá-los numa atualização de tarifas é recusado em vez de ignorado em silêncio.

# Close a night: zero rooms to sell, stop-sell on
curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "availability",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "availableRooms": 0,
      "closed": true
    }]
  }'

Detalhes em Enviar disponibilidade para o Booking.com. Se preferires escrever um calendário uma vez e fazê-lo chegar a todos os canais ligados, isso é PUT /v1/availability/{propertyId}, com PATCH /v1/availability/batch para muitas propriedades de uma vez.

Restrições que existem, e outras que não

Estadia mínima e máxima (por data de estadia e por data de chegada), chegada fechada e saída fechada existem e podem ser definidas por quarto, plano tarifário e intervalo de datas.

Várias restrições que as pessoas esperam simplesmente não estão na notificação que o Booking.com aceita, entre elas uma duração exata de estadia na chegada e a antecedência mínima ou máxima de reserva. O comportamento certo é recusá-las de forma visível. Uma restrição aceite e depois não enviada é a única falha que não consegues ver numa resposta, por isso a Repull responde 422 a indicar o campo em vez de o descartar. Vê restriction_not_supported e Estadia mínima e restrições.

Reservas, mensagens, avaliações e encargos

• Reservas — listá-las e confirmar a receção. A confirmação não é um trâmite opcional: as novas reservas ficam em fila até as confirmares, e um parceiro que nunca confirma continua a ler as mesmas reservas vezes sem conta. Reservas.
• Mensagens — listar conversas e enviar. Mais limitado do que a superfície de conversas do Airbnb; não há edição, nem reações, nem estado de leitura. Mensagens com hóspedes.
• Avaliações — listar e responder. Avaliações.
• Encargos e taxas — leitura e escrita. Encargos e taxas.
• Configuração e entrada em funcionamento — criar a entidade legal, verificar se está tudo pronto, definir contactos e políticas, e abrir uma propriedade para venda. Configuração e entrada em funcionamento.
• Sem alterações. O Booking.com não tem equivalente ao fluxo de alterações do Airbnb. As mudanças de datas e preço numa reserva existente não são uma operação da API.

A matriz de capacidades põe o Airbnb e o Booking.com lado a lado, e marca o parcial como parcial em vez de o arredondar para cima.

Porque é que a Content API devolve 403?

Porque o conteúdo é uma superfície de produto própria, com a sua própria permissão e o seu próprio caminho base, separada da disponibilidade, das tarifas e das reservas. Uma propriedade pode estar totalmente ativa — a receber reservas e a aceitar todas as escritas de tarifas e disponibilidade que envias — enquanto cada chamada de conteúdo para essa mesma propriedade responde 403.

Quando acontece, o instinto é suspeitar do token, depois do id da propriedade e depois das permissões do anfitrião na Extranet. Normalmente não é nada disso. A capacidade não te foi concedida para essa superfície, e voltar a ligar não muda nada. Confirma que capacidades a tua parceria inclui de facto antes de meteres a gestão de fotos ou descrições numa versão.

O conteúdo, onde está disponível, cobre fotos, descrições, comodidades, instalações e políticas, ao nível da propriedade ou do quarto, e o Booking.com revê as alterações de texto antes de as publicar, por isso uma escrita é o início de um processo, não o fim. Conteúdo e fotos.

O que custa construir isto por conta própria

1. Designação como parceiro e certificação. Meses, com análise comercial e uma certificação técnica por superfície. Não podes prometer uma data a nenhum cliente.
2. Um modelo de segurança com credencial partilhada. Uma única conta de máquina para todas as propriedades que serves. Rotação, armazenamento e um classificador de erros cuidadoso o suficiente para que um 401 global durante uma falha não desligue os teus clientes em massa.
3. O modelo e a associação. De propriedades a quartos, a planos tarifários e aos teus próprios anúncios, incluindo propriedades com vários quartos, unidades republicadas e quartos sem associação cujas reservas não têm para onde ir.
4. Verificação das escritas. Como o recibo não prova nada, uma integração correta volta a ler e reconcilia. É mais uma chamada, um tempo de espera e uma máquina de estados, no caminho mais quente que tens.
5. Convenções que não batem certo. Limites de datas exclusivos, preços ligados à ocupação, inventário separado das tarifas, restrições que não existem, XML onde esperavas JSON.
6. Falhas contínuas. Igual a qualquer API de parceiros: nunca chega a zero.

Em resumo, com honestidade: o Booking.com é uma integração mais pesada do que o Airbnb e não partilha quase nenhum dos seus pressupostos — outro modelo de autenticação, outro modelo de dados, outra semântica de datas, outra definição de escrita bem-sucedida. As equipas que acabaram de terminar o Airbnb subestimam-no sempre. O guia da API do Airbnb é a comparação.

Onde entra a Repull

A Repull é uma API REST e uma só chave para Booking.com, Airbnb, 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; as propriedades ligam-se sozinhas através de um fluxo alojado com a tua marca.

• Um único fluxo de ligação alojado. POST /v1/connect/{provider}, com a associação de quartos incluída. Connect.
• Escritas que te dizem a verdade. Verificação por releitura nas tarifas, ocupação resolvida e devolvida, restrições não suportadas recusadas em vez de descartadas, intervalos de datas inclusivos nas duas pontas.
• 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.
• Webhooks com histórico de entregas e reenvio, em vez da canalização de notificações de cada canal. Webhooks.

Começa pelo guia de início rápido, ou lê a visão geral dos canais. 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