Cupom de Desconto na API (DiscountCode)

O que é o DiscountCode

O campo DiscountCode é o parâmetro utilizado para aplicar um cupom de desconto em uma reserva de hotel através da API. Ele pode ser enviado em dois pontos diferentes do fluxo de reserva:

Na pesquisa de disponibilidade — método Search

Na validação das condições de reserva — método GetBookingConditions

Isso oferece flexibilidade: o parceiro pode aplicar o cupom já na busca inicial (para que o cliente veja o preço com desconto desde o resultado da pesquisa) ou apenas no momento de confirmar as condições do quarto escolhido, antes de efetivar a reserva.

1. Aplicando o cupom na pesquisa (Search)

Basta incluir o campo DiscountCode dentro do objeto Criteria da requisição:

json

{

    "Credential": {

        "Username": "username",

        "Password": "password"

    },

    "Criteria": {

        "CheckinDate": "2027-01-13",

        "NumNights": 1,

        "Filters": {

            "CheapestRoomOnly": false,

            "MaxPrice": 0.0,

            "MinPrice": 0.0

        },

        "HotelsIds": [1731511],

        "MainPaxCountryCodeNationalite": "BR",

        "ReturnExtendedHotelStaticData": false,

        "DiscountCode": "nomedocupom",

        "ReturnHotelStaticData": true,

        "ReturnOnRequestRooms": false,

        "SearchRooms": [

            { "NumAdults": 2, "Quantity": 1 }

        ],

        "SearchType": "Hotel"

    }

}

Quando o cupom é válido para os quartos retornados, a resposta traz o desconto já refletido em cada quarto elegível, através dos campos:

CouponCode — código do cupom aplicado

CouponDescription — descrição legível do cupom (ex.: "Primeira Compra - 10% de desconto")

CouponPrice — valor do desconto concedido

DiscountCoupon — objeto consolidado com código, descrição e valor do desconto

PriceWithCoupon / TotalPriceWithCoupon — preço final do quarto já com o cupom aplicado

Trecho de exemplo da resposta:

json

{

    "CouponCode": "PRIMEIRAODH10",

    "CouponDescription": "Primeira Compra - 10% de desconto",

    "CouponPrice": { "Currency": "BRL", "Value": 60.49 },

    "DiscountCoupon": {

        "DiscountCoupon": "PRIMEIRAODH10",

        "DiscountCouponDescription": "Primeira Compra - 10% de desconto",

        "DiscountCouponValue": { "Currency": "BRL", "Value": 60.49 }

    },

    "PriceWithCoupon": { "Currency": "BRL", "Value": 544.41 },

    "TotalPriceWithCoupon": { "Currency": "BRL", "Value": 545 }

}

Observação: na resposta do Search, o campo CanBook normalmente vem como false para os quartos, pois a disponibilidade final ainda precisa ser confirmada na etapa seguinte.

2. Aplicando o cupom em GetBookingConditions (Politicas/CheckOut)

O mesmo DiscountCode também pode ser informado diretamente na etapa de confirmação das condições de reserva, quando já se conhece o HotelId e o RoomIds do quarto selecionado (geralmente vindo de uma pesquisa anterior, com ou sem cupom):

json

{

    "Credential": {

        "Username": "username",

        "Password": "password"

    },

    "Token": "m+Jb/PG5CBOqYcquXl0YRCI+HJ2WZgJdC8PkWB28sUaQ...__2",

    "HotelId": "1731511",

    "DiscountCode": "nomedocupom",

    "RoomIds": [33510201]

}

A resposta traz a mesma estrutura de campos vista no Search (CouponCode, CouponDescription, CouponPrice, DiscountCoupon, PriceWithCoupon, TotalPriceWithCoupon), mas agora com CanBook: true, indicando que o quarto está confirmado e pronto para a etapa de reserva (Book).

Dica: independentemente de onde o cupom foi aplicado primeiro, é sempre recomendável confirmá-lo (ou reenviá-lo) em GetBookingConditions, pois é essa etapa que garante o preço final e a disponibilidade real do quarto antes da reserva.