Hotelaria - Front Office - Configuração do Plugin de Integração MturV2 no VHF

Dúvida
Como configurar e integrar as Fichas dos hospede com o Ministério de Turismo (Mtur)
Como configurar o Plugin MturV2

Ambiente
Front Office - VHF (v12.01.2603.3)
Plugin MturV2 (6.26.04.06)

Integração MTur v2

Esse documento contém informações do processo de integração da Ficha Nacional de Registro de Hóspede (FNRH) com Ministério do Turismo (MTur), se ainda não realizou o cadastro do hotel, acesse o link abaixo, para obter maiores informações

Ficha Nacional de Registro de Hóspedes — Ministério do Turismo

Processo

Integrar as informações da ficha de hóspedes em hotéis e pousadas no Brasil, informando o tempo de permanência, números de acompanhantes, meio de transporte e motivo de viagem, para acompanhamento e controle dos hóspedes no país.

A integração requer que o hóspede tenha uma conta Gov.br para realização da transação.

Descrição: Guia passo a passo para instalação, parametrização e monitoramento da integração com o Ministério do Turismo (MturV2).

1. Pré-requisitos e Instalação Base

O sucesso da integração depende da estabilidade do ambiente.

• Ambiente: Instale o Robô e o Monitor em uma máquina que permaneça ligada (preferencialmente o servidor).
• Versão do Plugin: No VHF e Plugin estão na versão a partir  
  VHF (12.01.2601.10) e do Plugin (6.26.03.00)

Instalação do plug-in MTur v2

Para download e atualização do plug-in, siga as instruções clicando aqui.

*Obs: se seu ambiente for Totvs Cloud, consulta nossa equipe se tem possibilidade de configuração no ambiente cloud.

2. Parametrização no VHF

Acesse o menu: VHF → Plug-in → Integração MTur v2 → Parâmetros

1. Credenciais: Insira o Hash e o CPF do solicitante (fornecidos pelo hotel/Ministério).
2. API Key (Secret): Insira a chave fixa. Atenção: Se a chave for renovada pelo Ministério, ela deve ser atualizada manualmente aqui.
3. Tipo de Ambiente: Produção Certifique-se de que a flag esteja definida para Produção.
4. URL de Produção: Utilize exatamente o endereço: https://fnrh.turismo.serpro.gov.br/FNRH_API/rest/v2
5. Serviços: Habilite todos os serviços disponíveis. O nome do hotel será preenchido automaticamente pelo sistema.

Ao incluir um parâmetro é necessário o preenchimento dos campos conforme os dados informados pela MTur.

Hotel	Nome do hotel em que o usuário encontra-se logado e se o mesmo encontra-se ativo na aplicação.
Tipo de ambiente	Indica o tipo de conexão a ser feita no processo de integração. Os campos a seguir tem seus valores conforme o tipo Hash ID = USUÁRIO Secret ID = CHAVE
Habilitar serviço	Se marcado, habilita os serviços para as transações: Registrar hospedagem.
CPF Solicitante	Tela para obter o Hash e Secret ID https://fnrh.turismo.serpro.gov.br/FNRH_SRH
Reservas check-in	O processo de envio das fichas de hóspedes para reservas em check-in considerará apenas as reservas incluídas no período definido por esse parâmetro. Legenda - Limites por cor / mensagem Até 30 dias Acima 30 dias Acima 180 dias
	Link para consulta da documentação do plug‑in.

Dados de autenticação nos serviços da MTur para cada hotel. Dados disponível no Sistema de Registro de Hóspede. Contacte o supervisor do sistema para obtenção dos dados. A seguir o link de acesso ao sistema.

3. Configuração do Robô de Transmissão Automática dos Registros

Atenção: Caso o hotel execute algum aplicação REMOTA, o mesmo deve ser executado na maquina servidora

O robô é o motor que envia as reservas ao Governo.

Executar o Plugin Robo qu fica na mesma estrutura das pastas Padrão do Pacote Front-Office (C:\Totvs\Hotel\PluginRobo.exe)

1. Criação da Tarefa: No gerenciador do robô, crie uma nova tarefa baseada na documentação (item 4.1).
2. Identificação: Informe o arquivo BPL e a Classe correspondente,
3. Conexão: Configure o Alias e o Esquema.
   • Importante: Utilize as credenciais de um usuário do sistema (VHF), e não o usuário do banco de dados (SGBD), ao final Testar a Conexão.
     Base SQL Server - Configuração do plug-in robô > Seguir a Documentação > TDN SQL
4. Agendamento: Defina o intervalo de execução (ex: a cada 30 ou 60 minutos).
5. Instalação do Serviço: Clique no botão "Instalar o serviço" para que ele passe a ser gerido pelo Windows, após instalar o serviço, fechar o plugin para que ele não fique rodando como app.
   

6. Caso contrário, apresentará o erro abaixo, para isso não ocorrer, realizar a saída conforme explicado no ítem 5.

   
   

Recomendamos que o usuário indicado para a conexão, seja usuário do SISTEMA, para não ocorrer problemas de permissão de acesso ao Banco e apresentar falhas na execução da Terefa e atualização dos Registros.

Após instalar o Serviço e concluir com o cadastro da Tarefa, sair do app fechamento o mesmo no "X", para que feche o app e deixa apenas o "Modo Serviço" rodando.

3.1 - LOG DO ROBÔ
Caso não apresente nenhuma informação no Plugin, necessário acessar o Log do ROBO para confirmar se o Método está sendo executado sem erros.

Acessar o seguinte diretório: C:\Totvs\Hoteis\PlugIn\Robo

O serviço deve ser executado e em seguida parado, caso apresente erro nesse processo, necessario contaot com suporte.

3.2 Envio de Hospedagem Manual "Enviar 

A tela a seguir, apresenta a funcionalidade de enviar as hospedagens, substituindo o serviço registrar hospedagem agendado do plug‑in robô.

Para habilitar a funcionalidade, consulte a opção "Parâmetros":

• Onde terá a flag: "Habilitar o envio de hospedagem de forma manual".

• 

  O Ministério do Turismo exige o envio diário dos registros das hospedagens. O botão "Enviar FNRH" realiza essa integração com o MTur e pode ser utilizado na frequência que desejar para garantir que os dados estejam sempre atualizados.

• 

  
   

4. Configuração do Hotal Monitor

O Monitor garante que, caso o robô pare por erro de rede ou sistema, ele seja reiniciado automaticamente.

• Acesso: Se o monitor já estiver rodando, pare o serviço no Windows para conseguir abrir a interface de configuração.
• Vínculo: Insira o Service Name exato do robô (copie das propriedades do serviço no Windows).
• Diretório: Aponte o caminho (path) da pasta onde o executável do robô está instalado.

Nome Serviço: HotalPluginRobotService
Diretório Padrão Robo: C:\Totvs\Hoteis\PluginRobot.exe

Caso o serviço ainda não tenha sido instalado, seguir com a instalação do Serviço do Monitor.

5. Mapeamento de Documentos e Regras de Negócio

Para que o documento do hóspede seja reconhecido, o sistema precisa "traduzir" os códigos.

• Associação de Documentos: Vá em VHF → Sistema > Utilitários > Cadastro Associação Tipo Documento.
• Vínculos Obrigatórios:
  • Associe o CPF (Código 7) ao CPF usado no seu hotel.
  • Associe o Passaporte (Código 2) ao seu Documento Passaporte usado no hotel

6. Fluxo de Operação e Monitoramento

Fluxo de Reserva

• Gatilho: A integração inicia no status de Check-in.
• Pré-Check-in: O hóspede pode preencher dados via QR Code do MTur. O recepcionista deve clicar em "Pré-checkin" na ficha simplificada para puxar esses dados.

Painel de Movimento e Logs

• Acesse o Plugin Movimento para ver o status das transmissões.
• Tratamento de Erros:
  • Erro de API/Documento: Verifique a aba de Log para detalhes específicos.
  • BPL não encontrada: Verifique se o arquivo BPL está na pasta do robô ou se há permissão de escrita na pasta.
  • Re-tentativa: O robô tentará reenviar automaticamente reservas que falharam em ciclos posteriores.

O Período da Transação mostrará todas as reservas integradas dentro desse intervalo, considerando todas as reservas em dias conforme os parâmetros definidos no sistema.

Por exemplo, se a integração estiver configurada para 5 dias (D+5), o sistema fará a transação(integração) das reservas check-in do dia atual e de todos os dias anteriores dentro desse período de 5 dias.

Vale lembrar que o Período da Transação se refere ao momento em que a integração foi realizada, e não ao período das reservas em si.

• Log MturV2

7. Fluxo Pré-Checkin - Ficha Simplificada

O que é Pré Check-in

Processo opcional onde o hóspede pode adiantar o preenchimento de seus dados antes de sua chegada física ao hotel, geralmente via QR Code ou link da reserva, agilizando o processo de check-in. 
Que será disponível pelo portal

https://fnrh.turismo.serpro.gov.br/FNRH_SRH

Ao ler o QR Code, cliente será direcionado para o portal Fnrh.Turismo.
Cliente poderá ser conectar com uma Conta "GOV.BT", "Sem Gov.Br" e "Estrangeiros" e seguir com o seu cadastro para o pré-checkin

O botão de Pré Check-in, só estará disponível:

• Se plug-in instalado e habilitado para o hotel;
• Se a reserva estiver em processo de check-in.

A seguir, a tela da ficha de hóspede com os campos destacados, a serem considerados no registro de hospedagem.

Considerações:

Há duas formas de preenchimento do pré check-in no sistema MTur.

1. Não vinculado, o hóspede faz a leitura do QR Code disponível na recepção do hotel, que irá direcioná-lo para a aplicação do MTur.
   1. Essa modalidade não tem o número da reserva para associação ao pré check-in.
2. Vinculado, o hóspede receber um link por e-mail com informações da sua reserva no hotel, que irá direcioná-lo para a aplicação do MTur.
   1. Essa modalidade, permite no preenchimento do pré check-in, a identificação e a associação da reserva.
       

Consulte a seção de instalação e configuração de serviços e mais informações detalhadas em nossa Documentação Oficial Integração MTur v2
https://tdn.totvs.com/pages/releaseview.action?pageId=1033965583