Quando a integração com a API do Governo (FNRH.TURISMO.SERPRO) é bem-sucedida, o sistema grava internamente as colunas HOSPEDEID e RESERVAID, associadas ao registro gerado pelo Ministério do Turismo.
Códigos de Status da Reserva/Hospedagem (controle do fluxo da estada) e de Status do Hóspede/Pessoa (validação cadastral junto ao governo).
Códigos 101 a 104 indicam o ciclo da ficha de hospedagem;
Códigos 200 a 207 referem-se ao cadastro individual do hóspede.
Códigos 400 / 500 refere-se para ambos referencias.
Segue a tabela estruturada conforme solicitado:
Tabela de Status de Integração (FNRH Digital Mtur V2)
| Código Status | Descrição | Referencia | Contexto do Erro/Fluxo | O que representa na API / Motivo |
|---|---|---|---|---|
| 101 | Pendente | Reserva/Hospedagem | A reserva ainda não foi enviada para a API. | Pendente: O registro foi identificado pelo sistema, mas ainda não houve tentativa de envio ou a tentativa falhou antes de chegar à API. |
| 102 | Concluída | Reserva/Hospedagem | Check-out realizado e comunicado com sucesso. | Concluída (Checkout): A estada foi finalizada e o encerramento da ficha foi enviado com sucesso para o Portal Mtur |
| 103 | Criada | Reserva/Hospedagem | Reserva enviada (possui RESERVAID), mas sem check-in. | Criada (Reserva): A reserva foi registrada na API e possui um RESERVAID interno da API. O hóspede ainda não entrou (Check-in pendente na API). |
| 104 | Em Andamento | Reserva/Hospedagem | Hóspede com Check-in ativo e comunicado à API. | Em Andamento (Check-in): O hóspede realizou o Check-in e a API foi atualizada para o status "Hospedado". |
| 105 | Cancelada | Reserva/Hospedagem | Reserva cancelada e sincronizada com o governo. | Cancelada: A reserva foi cancelada no PMS e o comando de cancelamento foi replicado para a API do governo. |
| 106 | No-Show | Reserva/Hospedagem | Reserva não comparecida: O hóspede tinha uma reserva confirmada, mas não realizou o check-in na data prevista e o hotel marcou a reserva como No Show. | No-Show: Encerramento por Não Comparecimento, Indica à API que aquela reserva_id deve ser finalizada sem a existência de um check-in/check-out. É um estado final que "limpa" a pendência da reserva no governo |
| 201 | Pessoa Validada | Hóspede/Pessoa | O cadastro do hóspede foi aceito e possui HOSPEDEID. | Pessoa Validada: O cadastro da pessoa foi aceito pela API (possui HOSPEDEID). É o "sinal verde" para vincular esta pessoa a qualquer hospedagem. |
| 202 | Erro Cadastral | Hóspede/Pessoa | Falha nos dados da pessoa (CPF inválido, Nome, etc). | Erro de Cadastro: A API rejeitou os dados da pessoa (ex: CPF inválido ou Nome vazio). O fluxo da reserva (101-104) fica travado aqui. |
| 203 | Aguardando Envio | Hóspede/Pessoa | Cadastro alterado no PMS, aguardando sincronização. | Aguardando Sincronização: Houve alteração no cadastro do hóspede no PMS e o sistema aguarda a próxima varredura para atualizar na API. |
| 207 | Inconsistência Geográfica | Hóspede/Pessoa | Erro comum: Cidade/Estado/País não batem com o IBGE. | Inconsistência Geográfica: Erro específico de validação de localidade (Cidade, UF ou País não mapeados corretamente com a tabela do IBGE). |
| 400 | Erro de API | Ambas | Bad Request (Erro de Negócio): O sistema enviou os dados, mas o Governo os rejeitou. Geralmente por falta de informação obrigatória (Ex: falta do responsável pelo menor, CPF inválido, CEP inexistente). | Rejeição por Dados Inválidos: A API recebeu a requisição, mas não pôde processá-la porque os dados não atendem às regras de validação do FNRH. O registro trava até ser corrigido manualmente no PMS. |
| 400 | Bad Request | Ambas | Informe o hóspede responsável pelo menor de idade. | Motivo: O hóspede é menor de 18 anos e a API exige um adulto vinculado. Solução: No sistema (VHF), vincule um adulto como responsável na reserva do menor e garanta que este adulto tenha um CPF válido e integrado. |
| 400 | Bad Request | Ambas | Registrar Pré-Check-in: Reserva em check-in não encontrada pelo Plug-in. | Motivo: Quebra de sequência. O sistema tentou registrar um "Pré-Check-in" para uma reserva que o sistema já entende que está em processo de "Check-in Real". Solução: O hotel deve verificar se a reserva não foi enviada anteriormente como Check-in, o pré check-in deve acontecer antes da reserva se tornar uma hospedagem real (Check-in) no Mtur, logo em status CONFIRMADA, sendo o hóspede principal. |
| 403 (ou 401)* | Forbidden / Unauthorized | Ambas | Registrar pre-Checkin: A requisição foi compreendida, mas o usuário não tem permissão para executá-la. | Motivo: O usuário configurado no sistema não possui o perfil de acesso necessário para gerenciar a API de FNRH ou o estabelecimento está com pendência de validação no CADASTUR.
Solução: O hotel deve acessar o portal CADASTUR, verificar se o perfil do usuário está como "Prestador" e se a aba "Responsável pela FNRH" foi devidamente deferida pelo órgão regional de turismo. |
| 400 | Bad Request | Ambas | Situação do hóspede não permite realizar check-out. (PRECHECKIN_PENDENTE) | Motivo: Tentativa de enviar a saída (Check-out) de uma ficha que ainda consta apenas como Pré-Check-in no governo. Solução: É necessário processar o evento de Check-in real no sistema antes de tentar enviar o encerramento da hospedagem. |
| 400 | Bad Request | Ambas | Situação do hóspede não permite realizar check-in. (CHECKIN_REALIZADO) | Motivo: O sistema tentou enviar a entrada (Check-in), mas a API do governo já considera este hóspede como "Hospedado". Solução: O registro já está sincronizado no governo. Nenhuma ação é necessária até o momento do check-out. |
| 400 | Bad Request | Ambas | Código de reserva já existente. | Motivo: Tentativa de criar uma reserva com um ID que já foi utilizado em outro envio anterior para a API. Solução: Verifique se há duplicidade de registros. Se a reserva for nova, pode ser um erro de numeração no PMS que precisa ser ajustado. |
| 400 | Bad Request | Ambas | Não foi encontrada nenhuma pessoa com os dados informados. | Motivo: Tentativa de vincular um hóspede à reserva sem que o cadastro dele (Pessoa) tenha sido validado primeiro. Solução: Verifique se o cadastro do hóspede possui erros (Status 202/207). Corrija-o para que ele obtenha um HOSPEDEID antes de integrar a reserva. |
| 400 | Bad Request | Ambas | Situação do hóspede não permite definir como no-show. (CANCELADO) | Motivo: Tentativa de marcar No-Show em uma reserva que já foi previamente enviada como Cancelada. Solução: Registros cancelados já são considerados encerrados pela API. Não há necessidade de enviar o No-Show para este caso. |
| 401 | Erro de API | Ambas | Não Autorizado: O sistema tentou enviar os dados, mas o servidor do Governo rejeitou a conexão por causa de credenciais inválidas ou expiradas. (Hash ID ou Secret ID) | Bloqueio de Acesso: O fluxo é interrompido imediatamente. Nenhuma informação de reserva ou hóspede é processada porque o sistema não conseguiu "abrir a porta" de comunicação com o MTur. |
| 500 | Erro de API | Ambas | Internal Server Error (Erro de Infraestrutura): O problema não está nos dados do hotel, mas sim no servidor do Ministério do Turismo que está instável ou fora do ar. | Falha Temporária do Receptor: Indica que o serviço do Governo está indisponível ou com erro interno. O fluxo é interrompido, mas o sistema deve tentar o reenvio automaticamente assim que o serviço for restabelecido. |
| 503 | Erro de API | Ambas | Serviço Indisponível: O servidor do Governo está ativo, mas "recusou" a conexão por estar sobrecarregado ou em manutenção. | Indisponibilidade Temporária: O fluxo é pausado. O sistema não consegue entregar os dados porque a "porta" do receptor está fechada. Não há erro nos dados do hotel, apenas na infraestrutura do Governo. |
Obs dos Códigos;
Se o código na Reserva/Hospedagem for 103 ou 104:
O registro não será reenviado como novo pelo botão FNRH porque ele já possui um
RESERVAID. O sistema tentará apenas atualizar os dados caso detecte mudanças. Se o cliente corrigiu algo e não mudou, o sistema entende que não há nada a fazer.
Se o código na Hóspede/Pessoa for 202 ou 207:
Este é o motivo de muitos registros "travarem". Enquanto o status do hóspede não for corrigido para 201 (Validado), a reserva não conseguirá avançar, pois a API exige um hóspede válido para vincular à hospedagem.
Se o código mensagem for (102 ou 105);
Se o registro estiver como Concluído ou Cancelado, o sistema não permite reenvio por questões de integridade da API.
Se os códigos na mensagem 400 e 401 ou 500 e 503
400 e 401 dependem de ação corretiva do hotel (ajuste de dados ou senha), enquanto os erros 500 e 503 são instabilidades externas do Governo que costumam se resolver sozinhas com o tempo
"Importante: O cadastro do hóspede pode (e deve) ser corrigido no sistema para que futuras utilizações ocorram sem erros. No entanto, para reservas que já atingiram o status de Encerrada (Status 102) ou Cancelada (Status 105), o ciclo de comunicação com a API do Ministério do Turismo foi finalizado.
Por questões de segurança e para evitar duplicidade de registros ou conflitos de sincronização na sua conta do FNRH Digital, o sistema não realiza o reenvio automático de dados para fichas já concluídas. Caso seja necessária a retificação de informações para fins de auditoria ou estatística, o ajuste deverá ser realizado diretamente no Portal FNRH Digital (Gov.br)."
"Para garantir que a comunicação dos registros de hospedagens entre o hotel e o Ministério do Turismo ocorra de forma íntegra, ressaltamos a importância do acompanhamento preventivo das transmissões via plugin.
Embora o sistema automatize o envio, a conformidade e a validação dos dados dependem diretamente da precisão das informações inseridas no cadastro e do monitoramento regular dos status de retorno. Orientamos que o hotel realize essa conferência antes do encerramento das reservas (Check-out), assegurando que qualquer inconsistência cadastral seja corrigida em tempo hábil.
Nossa equipe de suporte permanece à disposição para atuar em eventuais falhas técnicas do plugin, garantindo que a ferramenta esteja sempre operacional para que sua gestão de hospitalidade siga os padrões exigidos pelo FNRH Digital."
0 Comentários