Índice

A Plataforma de Integração de Hotelaria da Oracle (OHIP) oferece um conjunto de APIs de hotelaria e gestão para qualquer unidade hoteleira alojada em servidores Oracle, às quais se pode subscrever aplicações/soluções criadas por qualquer parceiro Oracle, devidamente registado como tal, e que tenha solicitado acesso ao APIs OHIP.

Este conjunto de endpoints oferece ao software de terceiros a possibilidade de comunicar praticamente todas as operações de gestão hoteleira realizadas através dele à propriedade do cliente/hoteleiro, de forma direta e sem necessidade de software interposto.

Ao contrário de outros esquemas, como o esquema Opera On Premise, o conteúdo das comunicações com o OHIP, é enviado e recebido em formato JSON e não em formato SOAP XML, o que facilita muito o processamento de órgãos de solicitação e resposta dadas as circunstâncias do nosso ambiente de desenvolvimento.

Desta forma, os clientes Golfmanager que tenham conta de gestão hoteleira na Oracle terão a possibilidade de instalar este módulo de integração e centralizar os aspectos mais básicos da gestão quotidiana da propriedade hoteleira, como cobranças de quarto, devoluções, envio manual e automático configurável de cobranças, etc.

Hoje, no momento da redação deste artigo, as funcionalidades de gestão hoteleira implementadas no plugin Oracle são as seguintes:

- Despesas de quarto : Inclui a possibilidade de reembolso, bem como a possibilidade de efetuar cobranças negativas.

- Envio de cobranças de outros meios de pagamento configurados para serem enviadas aos servidores do imóvel.

volte para cima

O fluxo básico do esquema de solicitação e resposta utilizado no plugin baseia-se exclusivamente na utilização de duas operações do conjunto de módulos API que o OHIP oferece, mais especificamente o CSH ( caixa ) e o RSV . ( reservas ).

O primeiro deles, o módulo CSH , oferece as APIs necessárias para notificar o sistema de gestão patrimonial das movimentações e operações de fluxo de caixa realizadas.

O segundo, o módulo RSV , fornece as APIs adequadas para gerenciar reservas, como obtê-las em massa ou filtrar por qualquer critério de pesquisa, bem como para notificar novas reservas, modificá-las, etc...

No nosso caso, todo o sistema gira exclusivamente em torno da operação getHotelReservations do módulo RSV e da operação postBillingCharge do módulo CSH .

Isto porque o padrão de estilo utilizado para comunicar os fluxos de caixa dos meios de pagamento alternativos à tarifa do quarto consiste, perdoem a redundância, em efetuar cobranças a uma pseudo-reserva de um quarto fictício, em que as operações de check- in e check- out servem como abertura e fechamento diário de caixa. Essas salas são identificadas como salas pay master pela sigla PM na terminologia própria do Oracle OHIP.

Em termos de autenticação, a API utilizada não faz parte do conjunto de APIs Oracle OHIP, mas sim do oAuth. Este sistema pode ser contra-intuitivo e até arbitrário em alguns pontos. Abaixo, descrevemos simplesmente o que esta solicitação deve incluir de acordo com a documentação da própria Oracle.

O método utilizado é o basic auth , ou seja, codificação de nome de usuário e senha no cabeçalho Authorization da solicitação. Esses nomes de usuário e senha correspondem ao nosso clientId e clientSecret , que podemos obter através de nosso portal de desenvolvedores Oracle. Adicionalmente, devemos incluir nos cabeçalhos da solicitação a propriedade x-app-key que identifica qual aplicação Oracle Partner, neste caso nós, queremos acessar.

Adicionalmente, no corpo da solicitação de autorização deverão ser incluídas as credenciais do usuário de integração que deverão ter sido previamente solicitadas e criadas na tabela de usuários da propriedade e que na verdade são as que apontam para a propriedade hoteleira do cliente final.

Numa única solicitação de token de acesso, basicamente enviamos duas coisas:

1- Através dos cabeçalhos especificamos quais das aplicações Oracle Market-Place queremos acessar, neste caso, nossa aplicação OHIP de produção, utilizando nossas credenciais de app-publisher no Oracle.

2- No corpo da solicitação forneceremos ao cliente os dados do usuário de integração solicitado através do portal de autoatendimento de identidade de sua conta Oracle Cloud.

Desta forma, os sistemas Oracle possuem tudo o que é necessário para operar o conjunto de APIs do OHIP contra a propriedade do Clube. Se tudo estiver bem, obteremos um token, que devemos acompanhar o restante das chamadas, desta vez, ao conjunto de APIs Oracle OHIP. Essas chamadas usam o método bearer-token para autenticação, ao contrário da solicitação de token em si, que usa o método auth básico .

O token de acesso é sempre solicitado antes de qualquer outra chamada que o plugin faça. Isto não é tecnicamente necessário, pois é válido por uma hora. Além de ter que escrever mais código para atualizá-lo de vez em quando, obtê-lo com antecedência representa uma primeira barreira contra possíveis interrupções do serviço ou erros de credencial, para que essas possibilidades não tenham que ser tratadas para cada uma das demais chamadas às API's do OHIP. Se a solicitação do token de acesso falhar por qualquer motivo, a operação simplesmente não será tentada e uma mensagem de erro correspondente será lançada.

volte para cima

O fluxo de chamadas que se realiza no momento da cobrança de quartos consiste na solicitação prévia de reservas, utilizando a operação API getHotelReservations com filtro detalhado na seção 4 deste manual, para exibi-las em um seletor ao usuário Admin do PDV.

Uma vez obtidos estes quartos e escolhido um válido, ao clicar em Aceitar, antes de realizar qualquer pedido OHIP, tenta-se efetuar o pagamento internamente no nosso sistema. Se este pagamento falhar, o processo de notificação do OHIP simplesmente não continua. Caso o pagamento pudesse ser feito internamente em nosso software, então fazemos uma solicitação para executar a operação postBillingCharge do módulo CSH das APIs do OHIP. Se, por qualquer motivo fora de nosso controle, a resposta obtida da Oracle for uma rejeição ou erro expresso, nosso software desfará a venda consolidada internamente. Os resultados destas operações serão refletidos na tabela de transações Oracle, bem como as solicitações e respostas obtidas, e as vendas e/ou cobranças envolvidas.

Quanto aos demais métodos de pagamento, o plugin contém uma assinatura do evento onTicketCreated . Desta forma, toda vez que um ticket é criado, a função que trata da inscrição do evento verifica se o mesmo provém de um meio de pagamento que possui um payMasterReservationId configurado , ou seja, o ID de uma pseudo-reserva de uma sala master pagante. Se for esse o caso, esta função passará o ticket recém-criado para a função plugin que realiza a cobrança do quarto, para que seja processado contra o quarto master da reserva configurado na forma de pagamento.

Estas operações, tal como acontece com o Room Charge, são registadas na tabela de transações. No entanto, há uma diferença subtil, mas fundamental, que deve ser destacada: quando cobramos uma sala específica e real, e a Oracle responde com uma resposta de rejeição, obviamente iremos desfazer o pagamento no Golfmanager. No entanto, quando comunicamos o fluxo de caixa de outros métodos de pagamento, se a Oracle responder com uma rejeição, não devemos nos importar internamente. A rejeição do Oracle OHIP será simplesmente registrada na tabela de transações.

Porém, para estes meios de pagamento alternativos, e em casos de interrupções inesperadas ou programadas do serviço, se a comunicação não puder ser realizada por simples falta de conectividade ou porque o serviço foi desabilitado na configuração do plugin, de tal forma que se você conseguiu obter uma resposta positiva ou negativa do serviço em cloud, você pode tentar reenviá-la a partir do botão "reenviar" adicionado à visualização de coleções.

Este botão tentará encaminhar as informações das transações marcadas como falha e que contenham informações do ticket de volta ao servidor Oracle. Desta forma, como as transações falhadas de cobrança para o quarto real não salvam ticket, não serão reenviadas o que não faria sentido, uma vez que o pagamento não foi consolidado em GM. Já no caso de cobrança para o quarto real, a confirmação do pagamento no GM está condicionada à aceitação pelo sistema Oracle OHIP. As transações falhadas que salvam um ticket significam que houve um pagamento consolidado no Golfmanager e, portanto, faz sentido tentar novamente sua comunicação com a Oracle, se esta falhar devido à falta de resposta expressa da Oracle (erros de HTTP).

Se o serviço estiver inativo e não desejar receber mensagens de erro constantemente, é possível desligar o serviço na configuração do plugin. No entanto, as cobranças no quarto não poderão ser feitas. Os demais meios de pagamento continuarão a gerar uma tentativa de comunicação falhada na tabela de transações Oracle, com um código de erro indicando que não puderam ser enviados porque o serviço foi desabilitado, para que possam ser reenviados desde que o o serviço é restaurado usando o botão acima mencionado.

Usar o botão "Reenviar" transações enquanto o serviço estiver desativado irá "redefinir" o status de erro das transações com falha contendo um ticket. Ou seja, aquelas transações com falha que contêm um ticket e que falharam por terem recebido uma resposta de rejeição expressa das APIs Oracle OHIP, atualizarão seu status de erro para o status de “não enviado devido a serviço desabilitado”. Isto pode ser útil, mas apenas num número muito pequeno de casos. Não deve ser usado levianamente. O sistema nos avisará adequadamente sobre isso quando tentarmos reenviar transações com falha quando o serviço estiver desabilitado na configuração do plugin.

volte para cima

Para autorizar a integração entre a empresa e o sistema através de uma API, terá primeiro de enviar o documento preenchido e assinado por ambas as partes para o Golfmanager. Selecione o seguinte documento para baixá-lo:

volte para cima

Do lado do GM, na visualização de configuração do plugin, só teremos que inserir a moeda em que queremos realizar as transações, o endereço URL do gateway Oracle CLOUD para a propriedade do hoteleiro/clube/cliente e o integrador de credenciais do usuário, que já explicámos no ponto anterior. Para obter o referido URL e credenciais, deverá seguir o processo de registo Oracle OHIP, que consiste em registar o ambiente do hotel que pretende integrar e obter credenciais de utilizador para a integração do referido ambiente à nossa aplicação Oracle. O URL é o endereço HOST do gateway do serviço para o qual o GM enviará as solicitações. As rotas/endpoints correspondentes serão adicionadas a esta URL dependendo da operação a ser realizada. As credenciais de usuário e senha são necessárias para a obtenção do token de acesso, que deverá ser incluído nas solicitações subsequentes realizadas. Se o token de acesso não puder ser obtido, seja porque não há conectividade ou resposta do servidor, ou porque as credenciais não são apropriadas, nenhuma operação poderá ser executada.

Adicionalmente, da nossa parte, foram adicionadas três propriedades ao arquivo config.json do servidor , que contém nosso id de cliente, a chave e o identificador de nossa aplicação Oracle (que neste caso é sempre o mesmo, a integração do OHIP).

O plugin também instala os seguintes campos personalizados (todos prefixados com oracle _):

- Na forma de pagamento:

- payMasterReservationId : Este campo representa o ID da pseudo-reserva do quarto fictício designado para receber cobranças pela referida forma de pagamento. Só deverá ser preenchido se desejar que as cobranças efetuadas com o referido meio de pagamento no GM sejam enviadas para o Oracle Cloud. Os métodos de pagamento que possuem este campo vazio não enviarão suas cobranças para o Oracle Cloud .

- Na linha de vendas:

- reserveID - ID da reserva: Se tiver valor, é o id da reserva à qual a referida linha foi cobrada/cobrada. Se uma linha de vendas não paga com o método de pagamento Oracle Charge to Room tiver um valor neste campo, então esse ID representa a reserva fictícia feita para um quarto Master Charge.

- roomChargePaid - Contém um valor verdadeiro/falso. Indica se a linha de vendas foi paga pela tarifa de quarto do Oracle. Permite-nos saber quais linhas foram pagas com este meio de pagamento.

- Na linha de coleta:

- enviado : Verdadeiro ou falso. Indica se o pagamento foi enviado aos servidores Opera Cloud.

volte para cima

Para que o sistema de gestão de propriedades distinga corretamente a origem de cada cobrança/pagamento enviado através do Golfmanager, é necessário fornecer, em cada cobrança/pagamento efetuado, um código de transação que identifique a subfamília do produto em processamento. /pagando e que é único para cada caixa e subfamília.

Foi criada uma nova tabela chamada ohiptxcodemap que pode ser acessada a partir da configuração do Golfmanager, no mesmo menu onde você pode acessar a configuração do plugin.

Nele podemos associar os códigos de transação do sistema de gestão de propriedades às caixas e subfamílias que criamos no Golfmanager.

volte para cima