Espera e retomada de reserva

Com o recurso Espera e retomada da Rapid API, você pode adotar um modelo de reserva em duas etapas.

Como parte do modelo de reserva em duas etapas, se um parceiro ou viajante deseja cancelar ou abandonar o quarto sem finalizar a reserva, pode colocar um único quarto em espera sem cobrança imediata e sem incorrer em multas por cancelamento.

Se o viajante ou parceiro deseja confirmar o quarto em um determinado período, ele pode concluir a reserva como uma segunda etapa. Se a reserva for abandonada, ela será cancelada de maneira automática e o inventário selecionado será desbloqueado.

Visão geral

Quais alterações são necessárias?

O recurso Espera e retomada usa APIs da Rapid existentes com novas indicações de solicitação e novos links de token em resposta. Não é necessário integrar novos métodos discretos de API. Para integrar o recurso Espera e retomada, será necessário atualizar o tratamento da solicitação ou resposta para:

1. Tratamento de criação da reserva
2. Tratamento de recuperação da reserva
3. Retomada: novo tratamento de link de token da resposta de recuperação
4. Cancelamento: novo tratamento de link de token da resposta de criação

Para que você possa entender melhor todo o processo de espera e retomada, revise esta página com atenção antes de consultar os nossos documentos de API individuais da integração. As opções específicas documentadas nessa página também estão disponíveis nas respectivas páginas de documentação dedicadas das nossas APIs de reserva e gerenciamento de reserva.

Como criar uma reserva em espera

A solicitação de reserva agora tem um novo campo booleano chamado hold. Enviar o valor de true coloca a propriedade em estado de espera.

Reservas em espera só devem ser deixadas no estado em espera pelo mínimo de tempo necessário para a sua aplicação específica. A reserva será cancelada de maneira automática se for deixada no estado de espera sem confirmação.

Uma resposta de reserva em espera bem-sucedida retorna um link com token adicional que é usado para retomar, confirmar e pagar a reserva em espera. Ela também omite a gama de quartos que costuma ser usada para fornecer links de cancelamento, já que ainda não há quartos para cancelar.

Exemplo de resposta de reserva para uma reserva em espera

{
    "itinerary_id": "2667552437552",
    "links": [
        {
            "rel": "retrieve",
            "method": "GET",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "resume",
            "method": "PUT",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "cancel",
            "method": "DELETE",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    ]
}

Se a indicação hold for usada para reservar, nenhum pagamento será cobrado na reserva A reserva será concluída e o pagamento cobrado apenas quando o link do método PUT na resposta de reserva em espera for usado dentro do período de reserva.

Como recuperar uma reserva em espera

Recupere uma reserva em espera usando o link retrieve disponível na resposta da reserva em espera. O método para retomar uma reserva de Espera ou retomada não é diferente de uma recuperação regular de uma reserva de 1 etapa e não requer um corpo de solicitação.

Situações de respostas:

• Recuperar uma reserva em espera que ainda está em espera vai retornar uma resposta com dados limitados, incluindo links para fazer a retomada e o cancelamento automáticos da reserva.
• Recuperar uma reserva em espera que foi cancelada (cancelada por solicitação) ou expirou (cancelada de maneira automática) vai retornar um erro "itinerário não encontrado".
• A recuperação de uma reserva em espera que foi concluída e confirmada em outra etapa vai se comportar do mesmo modo que a recuperação de itinerário padrão e retornar com os detalhes completos da reserva.

Exemplo de resposta de recuperação para uma reserva em espera

{
    "itinerary_id": "8701934321257",
    "creation_date_time": "2018-03-09T14:42:58.159Z",
    "links": {
        "resume": {
            "method": "PUT",
            "href": "/v3/itineraries/8701934321257?token=QldfCGlcUA…{example trimmed for length}="
        },
        "cancel": {
            "method": "DELETE",
            "href": "/v3/itineraries/9700934721257?token=QldfCGlcUA…{example trimmed for length}="
        }
    }
}

Exemplo de resposta de recuperação para uma reserva em espera que foi cancelada ou expirou

{
    "type": "resource_not_found",
    "message": "Itinerary was not found with provided request."
}

Como retomar uma reserva em espera

Para confirmar uma reserva que foi colocada em espera e para finalizar o pagamento, a reserva deve ser retomada.

A retomada de uma reserva em espera é feita usando o link resume fornecido na resposta da reserva em espera original e não requer um corpo de resposta.

Situações de respostas:

• Retomar uma reserva em espera que ainda está em espera vai concluir a reserva e retornar uma resposta HTTP 204 - nenhum conteúdo para indicar uma conclusão bem-sucedida. Use o link GET da resposta inicial da reserva em espera para recuperar o itinerário completo.
• Concluir uma reserva em espera que foi cancelada (cancelada por solicitação) ou expirou (cancelada de maneira automática) vai retornar um erro "itinerário não encontrado" detalhado na seção de recuperação anterior.
• Retomar uma reserva em espera que já foi retomada vai retornar um erro indicando que a reserva já foi realizada.

Exemplo de resposta de retomada de uma reserva que já foi retomada

{
    "type": "resume.already_resumed",
    "message": "Booking has already been resumed."
}

Como cancelar uma reserva em espera (cancelar)

O link com token cancel fornecido nas respostas de criação e recuperação da reserva age no nível do itinerário. Quando usado, o link libera a propriedade solicitada da espera e cancela o itinerário em espera. Os links de cancelamento de quarto só serão disponibilizados na resposta de recuperação depois que uma reserva for retomada.

Realizar uma operação de cancel também vai retornar um código de status HTTP 204, o mesmo que uma resposta de conclusão bem-sucedida. HTTP 204 é usado em ambos os estados para indicar que o servidor preencheu a solicitação e que não há conteúdo extra para enviar no corpo de carga da resposta.

Solicitar o cancelamento de uma reserva em espera resulta na mesma situação final, como se o seu cancelamento fosse permitido de maneira automática.

Situações de respostas:

• Cancelar uma reserva em espera que ainda está em espera vai liberar o inventário da espera e retornar um status HTTP 204.
• Cancelar uma reserva em espera que já foi cancelada (cancelada por solicitação) ou expirou (automaticamente cancelada) vai retornar um erro "itinerário não encontrado" documentado antes nesta página.
• Cancelar uma reserva em espera que já foi concluída com sucesso vai retornar uma mensagem de erro "cancelamento de nível de itinerário sem suporte". Faça uma chamada de recuperação e use os links de quarto disponibilizados na resposta para cancelar quartos individuais.

Exemplo de resposta de cancelamento de uma reserva que já foi retomada

{
    "type": "resume.itinerary_level_cancel_not_supported",
    "message": "Itinerary level cancel on confirmed booking is not supported."
}