Integração personalizada (API própria)

Se o seu hotel trabalha com um sistema desenvolvido sob medida, ou com um PMS ou motor que a WeSpeak ainda não integra, você pode conectá-lo por API. A sua equipe técnica publica dois endpoints no formato da WeSpeak e, a partir daí, o assistente consulta preços e disponibilidade ao vivo no seu sistema e cadastra nele as reservas fechadas pelo chat.

ℹ️ Não é o mesmo que WeSpeak Rates sem PMS nem Channel Manager: lá, a WeSpeak é o seu sistema. Aqui, o seu sistema continua no comando e a WeSpeak o consulta.

Neste artigo

O que você precisa
Como conectar, passo a passo
O contrato: disponibilidade (GET)
O contrato: reservas (POST)
Antes de abrir as vendas
O que não faz
Erros frequentes
Perguntas frequentes

O que você precisa

O quê	Obrigatório?	Para que serve
Um endpoint GET de disponibilidade e preços, com HTTPS e acessível pela internet	✅ Sim	O assistente cota com os dados do seu sistema
Um endpoint POST de criação de reservas	Só para reservar	A reserva do chat entra no seu sistema. Requer o WeSpeak Payments
Uma API key	Recomendada	O seu sistema sabe que a chamada vem da WeSpeak. Chega no cabeçalho `X-API-Key`
Os seus quartos cadastrados na WeSpeak, com o mesmo nome que o seu sistema devolve	✅ Sim	A WeSpeak junta os seus preços com as fotos, descrições e capacidades de cada quarto

💡 Se o seu PMS ou Channel Manager já está integrado com a WeSpeak, você não precisa disto: peça ao seu consultor a conexão nativa. Veja Conheça o WeSpeak Rates.

Como conectar, passo a passo

Peça a ativação ao seu consultor. A equipe da WeSpeak ativa a Integração personalizada na sua propriedade e a seção aparece no seu painel.
Cadastre os seus endpoints em Configurações → Integração personalizada: a URL de disponibilidade, a URL de reservas e a API key. Cada campo é salvo sozinho quando você sai dele.
Teste na mesma tela. Testar disponibilidade consulta o seu endpoint ao vivo e aponta, campo por campo, o que não cumpre o formato. Testar criação de reserva envia uma reserva de teste que o seu sistema não deve criar.
Faça uma cotação real pelo chat e compare os preços com os do seu sistema.
Valide as reservas com a lista de Antes de abrir as vendas.

Na mesma tela, Ver formato esperado mostra o contrato com exemplos: é o mesmo deste artigo.

🛠️ Dúvidas técnicas sobre o contrato? A sua equipe de desenvolvimento pode escrever diretamente para a nossa em tecnologia@wespeak.pro.

O contrato: disponibilidade (GET)

Sempre que o assistente precisa cotar, a WeSpeak chama a sua URL acrescentando estes parâmetros:

GET https://api.seuhotel.com/wespeak/availability?channel=custom&username=seu-hotel&channelPass=&checkinDate=2026-11-10&checkoutDate=2026-11-12&currency=USD&persons=2&adults=2&kids=1&childrenAge=8
X-API-Key: sua-api-key

Parâmetro	O que é
`checkinDate`, `checkoutDate`	Datas da estadia, no formato `YYYY-MM-DD`
`adults`, `kids`	Quantidade de adultos e de crianças
`childrenAge`	Idades das crianças separadas por vírgula (`4,8`). Só chega se houver crianças
`currency`	Moeda que o hóspede pediu, código ISO de 3 letras
`username`	Identificador da sua propriedade, combinado com o seu consultor. Serve quando um mesmo endpoint atende vários hotéis
`persons`, `channel`, `channelPass`	São enviados por compatibilidade; você pode ignorá-los. `persons` repete a quantidade de adultos

O seu endpoint responde com este JSON:

{
  "available": true,
  "rooms": [
    {
      "name": "Duplo Superior",
      "code": "DBL",
      "currency": "USD",
      "bookable": true,
      "unitsLeft": 3,
      "minStay": 2,
      "maxStay": 14,
      "rates": [
        { "name": "Tarifa Flexível", "code": "FLEX", "totalPrice": "300.00" },
        { "name": "Não Reembolsável", "code": "NR", "totalPrice": "260.00" }
      ]
    }
  ]
}

Campo	Obrigatório?	Regra
`available`	✅	`true` se há pelo menos um quarto reservável para essas datas
`rooms[].name`	✅	Igual ao nome do quarto na WeSpeak. Não diferencia maiúsculas, mas o texto precisa bater: "Duplo Superior" não é "Superior"
`rooms[].currency`	✅	Código ISO de 3 letras. Use a mesma moeda em todos os quartos
`rooms[].rates[].totalPrice`	✅	Preço total da estadia nesse quarto, não por noite
`rooms[].code`, `rates[].code`	Para reservar	Códigos estáveis do seu sistema. Devolvemos tal como vieram ao criar a reserva
`rooms[].bookable`, `unitsLeft`	Recomendados	Se pode ser reservado e quantas unidades restam
`minStay`, `maxStay`	Opcionais	Noites mínimas e máximas, como dado informativo

Regras que vale a pena seguir desde o primeiro dia:

"Sem disponibilidade" não é um erro. Responda 200 com available: false. Deixe os códigos 4xx e 5xx para falhas reais, como uma chave inválida ou o seu sistema fora do ar.
Aplique as suas restrições às datas pedidas. Se um quarto não pode ser reservado, devolva-o com bookable: false em vez de omiti-lo. Se nenhum pode ser reservado, responda available: false.
Responda na moeda do seu sistema. Se o hóspede pediu outra, a WeSpeak converte o preço.
O preço precisa corresponder à ocupação pedida, crianças incluídas.
Devolva só as tarifas que você quer vender pelo chat. O assistente oferece todas as que vierem em rates, e o hóspede vê rates[].name: se duas tarifas diferem em reembolso ou forma de pagamento, o nome deve dizer isso, por exemplo "Não reembolsável" ou "Flexível, pagamento no hotel".
Cada tarifa precisa aceitar a forma de cobrança que você configurou no WeSpeak Payments. Se uma tarifa exige o pagamento total e o hotel cobra sinal ou pagamento no hotel, a reserva vai falhar.
Cada consulta chega ao vivo. Não guardamos em cache, e antes de cobrar consultamos de novo para confirmar preço e disponibilidade. Se uma consulta falhar, tentamos de novo.
Responda rápido. O ideal é menos de 5 segundos. O teste do painel corta em 15.
Responda sempre um JSON válido. Se o seu endpoint falhar ou responder outro formato, o assistente para de cotar e avisa a equipe da WeSpeak, para não passar ao hóspede um preço errado.
Deixe passar as chamadas da WeSpeak. Se você usa Cloudflare ou outro firewall com bloqueio de bots, libere estas rotas: a WeSpeak chama a partir de servidores, não de um navegador.

O contrato: reservas (POST)

Quando o hóspede confirma a reserva com o WeSpeak Payments, seja com pagamento online, transferência ou pagamento no hotel, a WeSpeak envia a reserva para a sua URL:

{
  "weSpeakReservationId": "8f2c1a7e-4b1d-4c55-9a51-2f6c0d9e1b3a",
  "username": "seu-hotel",
  "checkinDate": "2026-11-10",
  "checkoutDate": "2026-11-12",
  "currency": "USD",
  "currencyConversion": null,
  "rooms": [
    {
      "name": "Duplo Superior",
      "code": "DBL",
      "rateName": "Tarifa Flexível",
      "rateCode": "FLEX",
      "adults": 2,
      "kids": 1,
      "kidAges": [8],
      "priceAmount": "300.00"
    }
  ],
  "totalPrice": 300,
  "amountPaid": 90,
  "amountToPay": 210,
  "depositAmount": 90,
  "paymentMethod": "...",
  "paymentDetails": {
    "orderId": "...",
    "gateway": { "name": "..." }
  },
  "customerName": "Ana",
  "customerSurname": "Pérez",
  "customerEmail": "ana@example.com",
  "customerPhone": "+5491100000000",
  "customerCountry": "AR",
  "reservationNote": "Chega tarde, por volta das 23 h"
}

O seu endpoint responde:

{
  "success": true,
  "reservationId": "ABC123",
  "status": "confirmed",
  "message": "Reserva criada"
}

Regras do POST:

Cada elemento de rooms é um quarto. Uma reserva de dois quartos traz dois elementos, cada um com a sua ocupação e o seu priceAmount.
Ignore os campos que você não usa. O corpo pode ganhar campos novos com o tempo: não rejeite a reserva por causa de um campo que você não conhece.
Os códigos voltam como vieram. rooms[].name, code, rateName e rateCode são os que o seu sistema devolveu no GET. Se você não enviou um código, ele chega como null.
O code é o identificador. Tudo o que o seu sistema precisa para reservar, como uma promoção, tem que poder ser deduzido do code do quarto e da tarifa. O nome viaja como referência.
Não duplique reservas. Se o seu endpoint não responder ou responder com um erro HTTP, tentamos de novo uma vez com o mesmo weSpeakReservationId. Se esse id já existe no seu sistema, devolva a reserva já criada em vez de criar outra. Uma rejeição também precisa se repetir igual, e o mesmo id com dados diferentes é rejeitado.
Modo teste. Se o corpo trouxer "isTest": true, valide o formato e responda normalmente, mas não crie a reserva. É o que o botão de teste do painel usa.
Desconte o estoque na hora. Dois hóspedes podem pagar o último quarto quase ao mesmo tempo: o seu sistema deve aceitar uma única reserva.
Se a reserva foi criada, responda success: true, mesmo que algo secundário falhe, como registrar o pagamento no seu sistema. Esse passo você resolve do seu lado.
Para rejeitar, responda 200 com success: false e uma message explicando o motivo, por exemplo que o preço mudou ou que não há mais disponibilidade. A reserva fica em Reservas da WeSpeak como não sincronizada, para a sua equipe resolver.
Se você não sabe se a reserva foi criada, não responda success: true. Responda success: false explicando e escreva para tecnologia@wespeak.pro, para revisá-la antes de cadastrá-la manualmente e não duplicá-la.
reservationId é o número da reserva no seu sistema. Guardamos para que a sua equipe a encontre.

Valores e moeda:

rooms[].priceAmount é o total da estadia nesse quarto, na moeda de currency.
totalPrice, amountPaid, amountToPay e depositAmount vêm na moeda em que o hóspede pagou. Se for diferente de currency, currencyConversion traz essa moeda e a taxa, por exemplo { "currency": "ARS", "conversionRate": 1450 }. Para passar esses valores para a moeda de currency, divida-os pela taxa.
amountPaid + amountToPay = totalPrice. amountPaid é o que foi cobrado pelo chat e amountToPay o que o hotel cobra conforme a sua política. depositAmount é o sinal que a política pede, não o que foi cobrado.
Impostos: a soma de priceAmount coincide com totalPrice se não houve conversão e os seus preços já incluem impostos. Se na WeSpeak forem configurados impostos que se somam ao preço, totalPrice os inclui e priceAmount não. O mais simples é devolver preços finais e não somar impostos na WeSpeak.
paymentDetails traz as referências do gateway de pagamento e chega vazio se não houve cobrança online. Se paymentDetails.gateway.name for Zru Token, é uma garantia com cartão: nada foi cobrado ainda, mesmo que amountPaid traga um valor.

Antes de abrir as vendas

Foi assim que validamos com os parceiros que já se conectaram. O ideal é começar com as URLs do seu ambiente de testes e uma propriedade de teste, e trocá-las pelas de produção no final:

Disponibilidade: datas com disponibilidade, datas sem, com crianças e para um grupo grande.
Segurança: uma chave inválida e o username de outra propriedade, que o seu endpoint rejeita com 401 ou 403.
Reserva nova, o mesmo envio repetido, que deve devolver a mesma reserva, e o mesmo id com outros dados, que deve ser rejeitado.
Preço que mudou ou disponibilidade que acabou entre a cotação e o pagamento: o seu sistema a rejeita com um motivo claro.
Reserva de vários quartos, com pagamento total, com depósito e sem pagamento.
Última unidade: duas reservas simultâneas, e só uma é confirmada.
Limpeza: cancele as reservas de teste, porque elas ocupam disponibilidade.
Uma reserva controlada em produção numa única propriedade, que você cancela depois, antes de abrir as vendas no resto.

O que não faz

Não envia alterações nem cancelamentos. Se uma reserva muda na WeSpeak, a sua equipe a atualiza no seu sistema manualmente.
Não grava preços nem disponibilidade no seu sistema. Só os consulta e, ao reservar, envia a reserva.
Não traz fotos nem descrições. Elas são cadastradas uma vez na WeSpeak, em cada quarto. O seu endpoint fornece só o que muda: preço, disponibilidade e se pode ser reservado.

Erros frequentes

Sintoma	Causa mais comum	O que fazer
O seu endpoint responde `401` mesmo com a chave correta	Muitas hospedagens descartam o cabeçalho `Authorization` antes de ele chegar ao seu código	Leia a chave do cabeçalho `X-API-Key`, que é o que a WeSpeak envia
O teste passa, mas o assistente não mostra um quarto	O nome não bate com o da WeSpeak	Use em `rooms[].name` o mesmo nome do quarto na WeSpeak
Os preços saem muito mais baixos que no seu site	O seu endpoint devolve o preço por noite	Devolva em `totalPrice` o total da estadia
Foram criadas duas reservas iguais	O seu endpoint não deduplica	Procure o `weSpeakReservationId` antes de criar
As reservas pagas em outra moeda não batem com o seu sistema	`totalPrice` e os valores pagos vêm na moeda de pagamento	Use `currencyConversion` para passá-los para a sua moeda
Algumas tarifas sempre falham ao reservar	A tarifa exige um pagamento diferente do que o WeSpeak Payments cobra	Alinhe a política da tarifa com a configuração de cobrança, ou não a devolva
O hóspede vê várias tarifas com o mesmo nome	`rates[].name` traz o nome de uma promoção e não o do plano	Use nomes que diferenciem reembolso e forma de pagamento
O teste diz que o endpoint não respondeu a tempo	O seu sistema demora mais de 15 segundos	Otimize a consulta ou use cache
Você não consegue cadastrar a URL de reservas	A sua conta não tem o WeSpeak Payments	Peça ao seu consultor que o ative

Perguntas frequentes

Preciso do WeSpeak Payments para cotar?
Não. O Payments só é necessário para a reserva entrar no seu sistema. Sem ele, o assistente cota com os seus preços e a sua equipe cadastra as reservas.

Serve para várias propriedades?
Sim. Cada propriedade tem a sua configuração, e o parâmetro username diz ao seu endpoint de qual hotel se trata.

Posso usar o WeSpeak Rates por cima?
Sim. A disponibilidade vem do seu endpoint e as tarifas que você criar no Rates são aplicadas por cima. Para isso você precisa dos code de quarto e de tarifa.

O que acontece se o meu sistema cair?
O assistente para de cotar e avisa a equipe da WeSpeak, para não passar ao hóspede um preço errado. Quando o seu endpoint volta a responder, tudo segue igual.

Preciso enviar a disponibilidade ou avisos de mudanças?
Não. Consultamos o seu endpoint ao vivo toda vez, e a única coisa que enviamos é a reserva.

Como passo a API key?
Não envie por e-mail: você mesmo a cadastra em Configurações → Integração personalizada e ela não volta a ser exibida.

Posso usar HTTP ou um IP interno?
Não. Só são aceitas URLs com HTTPS que possam ser acessadas pela internet.

Com quem falo se algo não funcionar?
Para dúvidas técnicas do contrato ou dos seus endpoints, com a nossa equipe de desenvolvimento: tecnologia@wespeak.pro. Para ativar a integração ou o WeSpeak Payments, com o seu consultor.