Histórico da Página

Informações Gerais

Objetivo

Ajustar e criar novas mensagens únicas, relacionadas a controladoria, em prol de atender as necessidades na integração do backoffice Protheus com o software de gestão de hotelaria da Bematech, CMNet.

Definição da Regra de Negócio

O backoffice Protheus será responsável pelo controle financeiro, fiscal e contábil das operações de hotelaria realizadas através do software CMNet.

Para tais fins, os seguintes processos serão integrados com o uso de mensagem única:

• Cadastro de cliente (pessoa física e jurídica, nacional e internacional).
• Cadastro de fornecedor (para empresa comissionada, nacional e internacional)
• Cadastro de vendedor (para empresa comissionada)
• Inclusão de recebimento antecipado (RA)
• Inclusão de provisionamento de reserva (PR a receber)
• Inclusão de adiantamento com cartão (CC / CD + NCC)
• Cancelamento de adiantamento
• Devolução de adiantamento
• Cancelamento de devolução de adiantamentos
• Alteração de valores provisionados em prol da reserva (alteração de PR a receber)
• Análise de crédito de empresas (cliente pessoa jurídica)
• Inclusão de bloco F100
• Cadastro de Produtos
• Inclusão de cupom fiscal
• Cancelamento de cupom fiscal
• Inclusão de recibo provisório de serviço (RPS)
• Cancelamento de RPS
• Redução Z
• Geração de Danfe sobre cupom
• Sincronização de RPS transmitida (envio dos números eletrônicos após transmissão ao SEFAZ)
• Cadastro de Comissões
• Faturas de Hotelaria
• Cancelamento de Faturas de Hotel
  
  

Os itens marcados em negrito são processos do loja e não serão tratados nessa especificação.

Para que todos esses processos sejam adequadamente integrados, serão necessárias algumas melhorias nas rotinas de Controladoria e Loja. Esta especificação tratará apenas as alterações necessárias voltadas a controladoria.

Na hotelaria existe a possibilidade de uma empresa ter um contrato com o hotel, de forma a permitir que seus funcionários fiquem hospedados em um período e, ao fazer checkout, as despesas da estadia desse hóspede podem ser faturadas contra a empresa em questão, gerando títulos para recebimentos futuros dos valores referentes aos serviços e produtos consumidos (RPS e Cupons Fiscais). Ou seja, nesse exemplo o hóspede não paga nada ao sair do hotel e a empresa é quem paga isso em um momento futuro, conforme regras estabelecidas em seu contrato.

Esse processo precisará ser integrado ao Protheus, pois o mesmo gera títulos financeiros que estão associados a determinados Recibos Provisórios de Serviços (RPS) e Cupons Fiscais. Para isso, serão necessários os seguintes pontos:

• Criação de duas novas tabelas: FO8 - Cabeçalho da Fatura e FO9 - Amarração da Fatura x Notas (RPS/Cupom);
• Criação de uma nova mensagem única para recebimento das informações de Faturas de Hotel (HotelInvoice);
• Criação de uma nova rotina de menu no Protheus (FINA791), para apenas visualização das informações de Faturas (Não haverá opção de Inclusão, Alteração e Exclusão no Protheus);
• Criação de um adapter para tratar o recebimento da mensagem única de Faturas (FINI791);
• Criação de novo parâmetro para definição de Natureza dos títulos gerados no processo de faturas de hotel: MV_HTLNAFT;

Detalhes técnicos:

• A rotina de faturas de hotelaria, no Protheus, será apenas para visualização dos registros e estará divida em três partes, conforme proposto no Protótipo 01 - Tela de Faturas de Hotelaria. As três partes são: Cabeçalho da Fatura (tabela FO8), Notas (Tabela FO9) e Títulos a Receber. Essa rotina deverá ser codificada em MVC;
  
  
• O adapter (FINI791) deverá ser codificado seguindo o padrão de gravação MVC com os modelos de dados da rotina FINA791, ao invés de utilizar ExecAuto. Também deverá ser utilizado a classe mais atual para manipulação de XML, tXmlManager, ao invés de XMLParser;
  
  
• Para criação dos títulos da fatura, na mensagem trafegará apenas os valores e data de vencimento de cada título. Portanto, o adapter deverá complementar a chave para inclusão do título via ExecAuto da rotina FINA040, seguindo os seguintes critérios:
  
  
  • Prefixo: Pegar do parâmetro MV_HTLPREF;
  • Número: Será o número da Fatura (tag Code);
  • Parcela: Se houver apenas um título (na tag ListOfAccountReceivableInformation), poderá ficar em branco. Se houver mais de um título, então será um sequencial conforme o número de títulos. Ou seja, se houver três informações de títulos no XML, então haverá a parcela 01, 02 e 03, respectivamente.
  • Tipo: Pegar do parâmetro MV_HTLFT, que por padrão terá o valor FT (Fatura).
  • Natureza: Esse campo não faz parte da chave, mas o mesmo deverá ter seu valor definido através do parâmetro MV_HTLNAFT.
    
    
• Os títulos gerados no processo de faturas de hotel, deverão ser gravados com origem na rotina FINI791 (E1_ORIGEM = FINI791);
  
  
• Os títulos gravados no recebimento da mensagem de Fatura de Hotel, não terão seus IDs retornados na resposta do processamento dessa mensagem. O único InternalId que será retornado é o da própria fatura.
  
  
• Na visualização da tela deverá haver um grid com os títulos da fatura em questão. Para filtrar esses títulos, considerar a lógica de chave acima informada;
  
  
• O adapter possuirá apenas tratamentos para o recebimento da mensagem em questão, visto que o detentor da lógica de geração de faturas é o sistema de hotelaria (CMNet);
  
  
• Se uma fatura precisar ser alterada ou excluída, a mesma deverá ser cancelada e uma nova será incluída. Para isso haverá a mensagem de cancelamento de faturas de hotel (abordada no próximo tópico dessa especificação).
  
  
• Criar uma função no adapter (FINI791) para encontrar a chave do registro de fatura de hotel no Protheus, à partir da chave externa recebida na mensagem.
  
  
• Criar uma função no adapter (FINI791) para criar o valor de InternalId com a chave da fatura no Protheus.
  
  

Detalhes da Mensagem (XSD):

Nome da Mensagem: HotelInvoice

Versão: 1.000

Tipo: Event

Estrutura:

Assim como a mensagem de inclusão de faturas, apenas o sistema de hotelaria irá solicitar a operação de cancelamento. Ou seja, não será possível cancelar uma fatura direto no backoffice Protheus. Será necessário criar uma nova mensagem única para receber a solicitação de cancelamento de faturas de hotel (HotelInvoiceCancellation). Essa mensagem será do tipo Request e o Protheus irá apenas tratar o recebimento da mesma,

O adapter no Protheus será a rotina FINAI791 e essa deverá possuir uma IntegDef inclusa no próprio adapter, pois não há uma rotina de menu representando a funcionalidade de cancelamento de faturas. Um exemplo desse tipo de tratamento pode ser visto na rotina LOJAI700.

Detalhes técnicos:

• Ao receber a solicitação de cancelamento, o adapter deverá possuir uma inteligência de buscar os títulos relacionados à fatura e verificar se os mesmos já não tiveram nenhum tipo de baixa. Caso algum desses títulos esteja baixado, então o adapter deverá retornar um erro informando que não foi possível cancelar a fatura, pois existem títulos baixados para a mesma. Do contrário, o campo FO8_STATUS deverá ter seu valor alterado para "2" (Fatura Cancelada) e o adapter deverá retornar "true", indicando que o processo obteve sucesso;
  
  
• A fatura a ser cancelada será recebida no XML com seu InternalId. Utilizar a função criada no FINI791 para encontrar o ID de fatura de hotel do Protheus à partir de um InternalId;
  
  
• Codificar o adapter utilizado a classe mais atual para manipulação de XML, tXmlManager, ao invés de XMLParser;
  
  

Detalhes da Mensagem (XSD):

Nome da Mensagem: HotelInvoiceCancellation

Versão: 1.000

Tipo: Request

Estrutura:

Nesta integração o detentor da regra de negócio para cálculo de comissões é o CMNet, que atende as regras especificas para a hotelaria. Portanto, o Protheus precisará estar preparado para receber essas comissões já calculadas. Para isso, será criada uma nova mensagem única: SalesCharge. 

A rotina de Atualização de Comissões (MATA490) deverá ser alterada para trabalhar com mensagem única, ou seja, passará a ter uma IntegDef e será necessário criar o Adapter dessa rotina (MATI490). O Protheus terá tratamentos para recebimento e para envio também. Embora o envio, partindo do Protheus, não seja utilizado nessa integração com hotelaria, o adapter já ficará preparado para trabalhar com envio para quando se fizer necessário.

Ao receber as informações, o Protheus irá gravar a comissão (SE3) através da Execauto da rotina MATA490. Caso grave com sucesso, deverá também gravar o de/para na XXF, relacionando as chaves dos registros dos dois sistemas e deverá retornar um ListOfInternalId padrão de mensagens do tipo Event (cadastro). Para gravação da tabela XXF, deve-se utilizar a seguinte função de Framework: CFGA070Mnt.

Exemplo de retorno de ListOfInternalId:

<ListOfInternalId>
    <InternalId>
        <Name>SalesChargeInternalId</Name>  <- Nome do InternalId
        <Origin>000000001</Origin> <- Chave do registro gerado na origem da mensagem
        <Destination>99|01|COM|TIT001|01|001|VEND01</Destination> <- Chave gerada no Protheus após gravação do registro
    </InternalId>
</ListOfInternalId>

Exemplo de gravação de de/para na XXF:

CFGA070Mnt( "BEMATECH", "SE3", "E3_NUM", "000000001", "99|01|COM|TIT001|01|001|VEND01", .F. )

Após gravadas as informações da SE3, o processo de pagamento das comissões (geração do contas a pagar e baixa do mesmo) seguirá o fluxo padrão do backoffice, de forma manual conforme melhor determinado pelo cliente que utilizará a integração.

Visto que quem possuí a regra de cálculo é o sistema de hotelaria, não será possível fazer o recálculo dos registro de comissão gerados por essa integração. Logo, deverá haver uma trava na rotina de Recalculo de Comissão (FINA440) para não permitir tal processo caso a origem da comissão seja integração (E3_ORIGEM = I). Também deverá haver uma trava para não permitir a alteração e exclusão de registros integrados através da rotina de manutenção de comissão (MATA490).

Detalhes técnicos:

• Toda comissão deve estar associada à um contas a receber. Porém, na hotelaria, a comissão pode nascer de um processo de fatura de hotel e não estará associado à um título a receber, mas sim à fatura em questão. Nesses casos, o número da fatura deverá trafegar na tag onde normalmente trafegaria o número do título a receber. Com essa informação, o adapter deverá buscar a fatura no Protheus e ver qual título foi gerado para a mesma. Então a chave do título encontrado será utilizado no registro de comissão. Caso a fatura tenha mais de um título gerado (fatura parcelada), associar a comissão ao primeiro título dessa fatura (título com a menor data de vencimento). 

• Para toda comissão gravada através de mensagem única, gravar o campo E3_ORIGEM com o novo valor I, indicando integração (rotina MATI490).

IMPORTANTE: Esse novo valor deverá ser documentado na página do TDN:

http://tdn.totvs.com/pages/releaseview.action?pageId=184781116

• Codificar o adapter de forma atualizada, utilizando a classe tXmlManager ao invés de XmlParser.
  
  
• O Adapter deverá tratar os eventos de Inclusão, Alteração e Exclusão. Na inclusão e alteração, deverá retornar o ListOfinternalId na resposta. Na exclusão, deverá apagar o de/para na XXF e não deve retornar ListOfInternalId na resposta. Para saber a operação do cadastro, deve-se olhar a tag "Event", que por sua vez pode ter dois valores: "UPSERT" ou "DELETE". Se for delete, é uma operação de exclusão. Se for upsert, deve-se primeiramente buscar a chave externa (recebida na tag InternalID) no de/para do Protheus. Se encontrar algum registro, deve-se considerar que é uma operação de alteração. Do contrário, é um processo de inclusão.
  
  

  Exemplo de exclusão de de/para na XXF:

  CFGA070Mnt( "BEMATECH", "SE3", "E3_NUM", "000000001", "99|01|COM|TIT001|01|001|VEND01", .T. )

   

• Adicionar um tratamento para considerar a rotina MATI490 na função FA440Origem, no fonte FINA440. Para esse caso o retorno deverá ser "I".
  
  
• Criar uma função no adapter (MATI490) para encontrar a chave do registro de comissão no Protheus, à partir da chave externa recebida na mensagem.
  
  
• Criar uma função no adapter (MATI490) para criar o valor de InternalId com a chave da comissão no Protheus.

Detalhes da Mensagem (XSD):

Nome da Mensagem: SalesCharge

Versão: 1.000

Tipo: Event

Estrutura:

Anexos:

XSD - SalesCharge_1_000

XML - SalesCharge_1_000

XSD - HotelInvoice_1_000

XML - HotelInvoice_1_000

XSD - HotelInvoiceCancellation_1_000

XML - HotelInvoiceCancellation_1_000

Exemplo - ExecAuto de Comissões

Tabelas Utilizadas

• SA1 – Clientes
• SA2 – Fornecedores
• SA3 – Vendedores
• SE1 – Títulos a receber
• SE3 – Comissão de Vendas
• AI0 – Complementos de Clientes
• FLY – RPS x NFe
• SF3 – Livros Fiscais
• SFT – Livro Fiscal por Item de NF
• CF8 – Demais Docs. Pis Cofins
• FO8 – Fatura Hotel 
• FO9 – Fatura Hotel x Notas

Protótipo de Tela

Protótipo 01 - Tela de Faturas de Hotelaria

Dicionário de Dados

Arquivo: FO8 – Fatura de Hotel

Arquivo: FO9 – Fatura Hotel x Notas

Arquivo: FOA – Fatura Hotel x Titulo

Parâmetros

Estrutura de Menu

Casos de Uso

UC 001 - Inclusão de Comissão vinculada à um título- Integração

Objetivo: Incluir registro de comissão (tabela SE3) vinculado à um contas a receber.

Pré-condição:

• Cadastro do adapter MATI490, para habilitar o recebimento da mensagem única SalesCharge (SigaCFG > Ambiente > Schedule > Adapter E.a.i.).
• Cadastro do de/para de empresa e filial utilizada na integração entre os sistemas Protheus e CMNet (SigaCFG > Ambiente > Schedule > Emp Filial mensagem única).
• Cadastro de Cliente integrado ao CMNet (UC XXX);
• Cadastro de Título a Receber integrado ao CMNet (UC XXX);
• Cadastro de Vendedor integrado ao CMNet (UC XXX);

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de geração de comissão vinculada à um movimento de contas a receber;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de comissões;

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.)..

2.1 Verificar na tela de Manutenção de Comissão se o registro foi gravado com sucesso (SigaFIN > Atualizações > Comissões > Manutenção das comissões)..

2.2 Verificar se o de/para foi gravado com sucesso, relacionando os códigos de ambos os sistemas na rotina De/Para de mensagem única (SigaCFG > Ambiente > Schedule > De/Para de mensagem única).

Fim do caso de uso

UC 002 - Inclusão de Comissão vinculada à Fatura de hotel - Integração

Objetivo: Incluir registro de comissão (tabela SE3) vinculado à uma Fatura de hotel.

Pré-condição:

• Cadastro do adapter MATI490, para habilitar o recebimento da mensagem única SalesCharge (SigaCFG > Ambiente > Schedule > Adapter E.a.i.).
• Cadastro do de/para de empresa e filial utilizada na integração entre os sistemas Protheus e CMNet (SigaCFG > Ambiente > Schedule > Emp Filial mensagem única).
• Cadastro de Cliente integrado ao CMNet (UC XXX);
• Cadastro de Fatura de Hotel integrado ao CMNet (UC XXX);
• Cadastro de Vendedor integrado ao CMNet (UC XXX);

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de geração de comissão vinculada à uma fatura;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de comissões;

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.);

2.1 Verificar na tela de Manutenção de Comissão se o registro foi gravado com sucesso e se está vinculado a um título a receber (SigaFIN > Atualizações > Comissões > Manutenção das Comissões);

2.2 Verificar se o de/para foi gravado com sucesso, relacionando os códigos de ambos os sistemas na rotina De/Para de mensagem única (SigaCFG > Ambiente > Schedule > De/Para de mensagem única).

Fim do caso de uso

UC 003 - Alteração de Comissão - Integração

Objetivo: Alterar dados do registro de comissão já integrado.

Pré-condição:

• Execução do caso de uso UC 001 ou UC 002.

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de alteração de comissão;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de comissões;

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.);

2.1 Verificar na tela de Manutenção de Comissão se as alterações do registro foram gravadas com sucesso (SigaFIN > Atualizações > Comissões > Manutenção das Comissões).

Fim do caso de uso

UC 004 - Alteração de Comissão Manualmente no backoffice

Objetivo: Validar bloqueio de alteração de dados do registro de comissão, já integrado, de forma manual no Protheus através da rotina de manutenção de comissões.

Pré-condição:

• Execução do caso de uso UC 001 ou UC 002.

Inicializador:

• Protheus Financeiro.

Fluxo Básico de Eventos:

1.0 Acessar a rotina de Manutenção de Comissões (SigaFIN > Atualizações > Comissões > Manutenção das Comissões);

 1.1 Selecionar um registro de comissão que tenha sido gerado no CMNet e integrado ao Protheus;

1.2 Clicar em Alterar;

1.3 Deverá ser exibido um alerta informando que não será possível alterar esse registro, pois sua origem é externa ao sistema (integração).

Fim do caso de uso

UC 005 - Exclusão de Comissão - Integração

Objetivo: Excluir registro de comissão já integrado.

Pré-condição:

• Execução do caso de uso UC 001 ou UC 002.

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de exclusão de comissão;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de comissões, com operação DELETE;

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.);

2.1 Verificar na tela de Manutenção de Comissão se o registro foi excluído com sucesso (SigaFIN > Atualizações > Comissões > Manutenção das Comissões).

Fim do caso de uso

UC 006 - Exclusão de Comissão Manualmente no backoffice

Objetivo: Validar bloqueio de exclusão de dados do registro de comissão, já integrado, de forma manual no Protheus através da rotina de manutenção de comissões.

Pré-condição:

• Execução do caso de uso UC 001 ou UC 002.

Inicializador:

• Protheus Financeiro.

Fluxo Básico de Eventos:

1.0 Acessar a rotina de Manutenção de Comissões (SigaFIN > Atualizações > Comissões > Manutenção das Comissões);

1.1 Selecionar um registro de comissão que tenha sido gerado no CMNet e integrado ao Protheus;

1.2 Clicar em Excluir;

1.3 Deverá ser exibido um alerta informando que não será possível excluir esse registro, pois sua origem é externa ao sistema (integração).

Fim do caso de uso

UC 007 - Recálculo de Comissão no backoffice

Objetivo: Validar bloqueio de recálculo dos registros de comissão, já integrados, através da rotina de recálculo de comissões do Protheus.

Pré-condição:

• Execução do caso de uso UC 001 ou UC 002.

Inicializador:

• Protheus Financeiro.

Fluxo Básico de Eventos:

1.0 Acessar a rotina de Recálculo de Comissões (SigaFIN > Miscelanea > Recalculos > Recálculo de Comissão);

1.1 Configurar os parâmetros da rotina com dados coerentes aos registros de comissão que foram integrados;

1.2 Executar o processo de recálculo;

1.3 Validar se não houve nenhuma alteração nos dados das comissões integradas, através da rotina de manutenção de comissões (SigaFIN > Atualizações > Comissões > Manutenção das Comissões).

Fim do caso de uso

UC 008 - Inclusão de Fatura de Hotel - Integração

Objetivo: Incluir registro de fatura de hotel (tabelas FO8, FO9 e SE1).

Pré-condição:

• Cadastro do adapter FINI791, para habilitar o recebimento da mensagem única HotelInvoice (SigaCFG > Ambiente > Schedule > Adapter E.a.i.);
• Cadastro de Cliente integrado ao CMNet (UC XXX);
• Cadastro de RPS ou Cupom Fiscal integrado ao CMNet (UC XXX);
• Definição do prefixo dos títulos a receber, através do parâmetro MV_HTLPREF.
• Definição do tipo de título que será utilizado no processo de fatura de hotel, através do parâmetro MV_HTLFT.
• Definição da natureza financeira que será utilizada nos títulos a receber gerados no processo de fatura de hotel, através do parâmetro MV_HTLNAFT.

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de geração de fatura;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de fatura de hotel (HotelInvoice);

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.);

2.1 Verificar na tela de Fatura de Hotel se o registro foi gravado com sucesso (SigaFIN > Atualizações > Hotelaria > Fatura de Hotel);

2.2 Verificar se o de/para foi gravado com sucesso, relacionando os códigos de ambos os sistemas na rotina De/Para de mensagem única (SigaCFG > Ambiente > Schedule > De/Para de mensagem única);

Fim do caso de uso

UC 009 - Cancelamento de Fatura de Hotel sem baixa de títulos - Integração

Objetivo: Cancelar registro de fatura de hotel (tabelas FO8, FO9 e SE1).

Pré-condição:

• Cadastro do adapter FINAI791, para habilitar o recebimento da mensagem única HotelInvoiceCancellation (SigaCFG > Ambiente > Schedule > Adapter E.a.i.);
• Inclusão de fatura de hotel (UC 008);
• Não ter nenhuma baixa em nenhum dos títulos a receber associados à fatura a ser cancelada.

Inicializador:

• CMNet.

Fluxo Básico de Eventos:

1.0 Acessar o sistema CMNet e realizar o processo de solicitação de cancelamento de fatura;

1.1 O sistema deverá se comunicar com o Protheus, enviando a mensagem única de cancelamento de fatura de hotel (HotelInvoiceCancellation);

2.0 Verificar no Monitor EAI, do Protheus, se a mensagem foi recebida e processada com sucesso (SigaCFG > Ambiente > Schedule > Schedule > Monitor E.a.i.);

2.1 Verificar na tela de Fatura de Hotel se o registro foi cancelado com sucesso (SigaFIN > Atualizações > Hotelaria > Fatura de Hotel);

3.0 Verificar no sistema CMNet se o registro foi cancelado com sucesso;

Fim do caso de uso