Fluxo de reserva

O fluxo típico de um motor de reservas: obter um token, listar os quartos para as datas e a ocupação pesquisadas pelo hóspede, aplicar a tarifa escolhida e um eventual cupom, concluir a etapa de pagamento e gravar a reserva no HMS com BookingPushRQ. Este guia percorre cada etapa com requisições e respostas reais.

1Login/external/public/login

2Lista de quartos/external/online/roomType

3Cupom · Pacotescoupon/search · stock/packages

4Pagamentopayment/type/{type}

5Enviochannel/booking

1. Obtenha um token#

Faça login uma vez quando o servidor iniciar ou quando o token expirar, e guarde o token junto com o ID do hotel. Detalhes: Autenticação.

2. Liste os quartos#

Solicite a lista de quartos com os valores do formulário de busca do hóspede. Se houver crianças, envie as idades; o preço para crianças é calculado pela idade.

Terminal

curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "startDate=2026-08-18" -d "endDate=2026-08-20" \
  -d "adultCount=2" -d "childCount=1" -d "childAges[]=7" -d "language=en"

O que exibir para cada tipo de quarto da resposta:

Campo	Na tela
`name`, `images[]`, `detail`, `roomFeatures[]`	Card do quarto
`roomCount`	Quartos restantes. 0 significa “indisponível para venda” — o motivo está em `roomRestrictionMessage`.
`accommodationTypes[].title`	Opção de regime (Café da manhã incluído, Meia pensão…)
`accommodationTypes[].prices{}`	Opções de tarifa: padrão e não reembolsável

As chaves do objeto prices têm o formato "<persons>-<1|0>". O sufixo 1 indica a tarifa padrão (reembolsável) e 0, a tarifa não reembolsável; a opção não reembolsável traz nonRefundable: "[NR]". Com preço por quarto (priceType: 1), a chave é 1-1 / 1-0, independentemente da ocupação.

accommodationTypes[0].prices

{
    "2-1": {
        "total": 2,
        "title": 2,
        "nonRefundable": "",
        "price": "1930.00",
        "currency": "TRY",
        "id": "2/2",
        "prices": [
            {
                "price": "965.00",
                "tarih": "18.08.2026"
            },
            {
                "price": "965.00",
                "tarih": "19.08.2026"
            }
        ]
    },
    "2-0": {
        "total": 2,
        "title": 2,
        "nonRefundable": "[NR]",
        "price": "1737.00",
        "currency": "TRY",
        "id": "2-0/2",
        "prices": [
            {
                "price": "868.50",
                "tarih": "18.08.2026"
            },
            {
                "price": "868.50",
                "tarih": "19.08.2026"
            }
        ]
    }
}

3. Cupons e pacotes#

Se o hóspede informar um cupom, valide-o e aplique o desconto do seu lado:

Terminal

curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"

Resposta · 200

{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Com change 0, rate é um desconto percentual (10%); com 1, é um valor fixo (10,00 na moeda do hotel). Aplique o desconto ao valor do quarto e envie os totais com desconto na reserva.

Para vender extras, exiba a lista de pacotes. Os pacotes escolhidos entram na reserva em extras[], com o id do pacote em stockID. Os totais após cupons e pacotes vão no Total da reserva.

4. Etapa de pagamento#

Liste os tipos de pagamento que o hotel aceita e siga de acordo com a escolha do hóspede. No tipo 10 (pagamento online), uma sessão de pagamento é iniciada e o hóspede é levado ao provedor; após o pagamento, ele volta para a sua returnUrl. Todos os tipos são explicados no guia Fluxo de pagamento.

5. Envie a reserva#

Assim que o resultado do pagamento for conhecido, grave a reserva no HMS. ID é o código único gerado por você; informe o mesmo código ao hóspede. Os IDs de tipo de quarto e de regime de alimentação vêm da lista de quartos.

Requisição

curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @booking.json

const booking = {
  hotelID: "1000",
  ID: orderNo,                      // seu código de reserva único
  type: "Book",
  createDateTime: new Date().toISOString(),
  checkinDate: "2026-08-18",
  checkoutDate: "2026-08-20",
  RoomStays: [{
    roomTypeID: "2", roomName: "Standard Room",
    ratePlanID: "2", ratePlanName: "Bed & Breakfast",
    type: "Book", NumberOfUnits: "1",
    checkinDate: "2026-08-18", checkoutDate: "2026-08-20",
    GuestCount: { adult: 2, child: 1 },
    PerDayRates: { currency: "TRY", PerDayRate: [
      { stayDate: "2026-08-18", baseRate: "965.00", hotelServiceFees: "0" },
      { stayDate: "2026-08-19", baseRate: "965.00", hotelServiceFees: "0" }
    ]},
    Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", currency: "TRY" }
  }],
  PrimaryGuests: [{ name: "Ayşe", surname: "Demir", PhoneNumber: "+905551112233", email: "[email protected]", CountryCode: "TR" }],
  ChildGuests: [{ age: 7 }],
  SpecialRequest: [{ text: "Late check-in, around 23:00." }],
  extras: [],
  Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", extraTotal: "0.00", currency: "TRY" }
};

const res = await fetch("https://test.hms.gen.tr/external/online/channel/booking", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.HMS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ BookingPushRQ: { Bookings: [booking] } })
});
const { BookingPushRS } = await res.json();
if (BookingPushRS.Error) throw new Error(BookingPushRS.Error);
const hmsId = BookingPushRS.BookingConfirmNumbers[0].HMS_ID;

$booking = [
    'hotelID'        => '1000',
    'ID'             => $orderNo,          // seu código de reserva único
    'type'           => 'Book',
    'createDateTime' => date('c'),
    'checkinDate'    => '2026-08-18',
    'checkoutDate'   => '2026-08-20',
    'RoomStays'      => [[
        'roomTypeID' => '2', 'roomName' => 'Standard Room',
        'ratePlanID' => '2', 'ratePlanName' => 'Bed & Breakfast',
        'type' => 'Book', 'NumberOfUnits' => '1',
        'checkinDate' => '2026-08-18', 'checkoutDate' => '2026-08-20',
        'GuestCount'  => ['adult' => 2, 'child' => 1],
        'PerDayRates' => ['currency' => 'TRY', 'PerDayRate' => [
            ['stayDate' => '2026-08-18', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
            ['stayDate' => '2026-08-19', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
        ]],
        'Total' => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'currency' => 'TRY'],
    ]],
    'PrimaryGuests'  => [['name' => 'Ayşe', 'surname' => 'Demir', 'PhoneNumber' => '+905551112233', 'email' => '[email protected]', 'CountryCode' => 'TR']],
    'ChildGuests'    => [['age' => 7]],
    'SpecialRequest' => [['text' => 'Late check-in, around 23:00.']],
    'extras'         => [],
    'Total'          => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'extraTotal' => '0.00', 'currency' => 'TRY'],
];

$ch = curl_init('https://test.hms.gen.tr/external/online/channel/booking');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('HMS_TOKEN'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['BookingPushRQ' => ['Bookings' => [$booking]]]),
]);
$rs = json_decode(curl_exec($ch), true)['BookingPushRS'];
if (isset($rs['Error'])) {
    throw new RuntimeException($rs['Error']);
}
$hmsId = $rs['BookingConfirmNumbers'][0]['HMS_ID'];

Resposta · 200

{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID é o ID da reserva no HMS; guarde-o junto com o seu próprio registro. A reserva aparece no painel no canal “Online”, e o HMS envia ao hóspede um e-mail de confirmação conforme as configurações do hotel.

Vários quartos#

Quando vários quartos do mesmo tipo de quarto e regime de alimentação são vendidos, cada quarto é um item RoomStays separado; NumberOfUnits é "1" no primeiro, "2" no segundo e assim por diante. Tipos de quarto diferentes também são itens separados. O Total da reserva é a soma de todos os quartos e extras.

Alterações e cancelamentos#

Envie a reserva novamente para o mesmo endpoint, com o mesmo ID:

type: "Modify" — datas, quartos ou dados dos hóspedes mudaram. Envie a reserva completa no estado atual; o HMS substitui o registro existente por ela.
type: "Cancel" — a reserva foi cancelada. Os quartos também levam type: "Cancel".

Erros comuns#

Manter a lista de quartos em cache por muito tempo. A disponibilidade e as tarifas mudam o tempo todo; atualize a lista antes que o hóspede chegue à etapa de pagamento.
Enviar um childCount diferente do tamanho de childAges[]: o servidor confia na lista de idades e altera a quantidade de crianças sem avisar.
Enviar seus próprios IDs como roomTypeID / ratePlanID em vez dos IDs da lista de quartos: o retorno é Could not register.
Enviar PaymentCard em tipos de pagamento diferentes de 9: os dados do cartão são transmitidos ao HMS sem necessidade.
Repetir a requisição após um erro de rede com um ID diferente: isso cria uma reserva duplicada. Repita com o mesmo ID.

Última atualização: 21 de setembro de 2026Encontrou um erro? Avise-nos