| Card |
|---|
| effectDuration | 0.5 |
|---|
| id | Integração via Mensagem única |
|---|
| label | Principais tabelas | 1 - Configuração do Protheus e informações |
|---|
| | Expandir |
|---|
| Tabelas utilizadas na Integração EAI: - De/Para de Empresas/Filiais Mensagem única (XXD)
|
Tabelas:XXF no banco de dados | | XX3 | Transações EAI | | XX4 | Adapters EAI | | Card |
|---|
| default | true |
|---|
| id | Integração Via Mensagem única |
|---|
| label | Adapters |
|---|
| |
| default | true |
|---|
| effectDuration | 0.5 |
|---|
| id | Integração Via Mensagem única |
|---|
label | - de Conteúdos Mensagem Única (XXF)
- Transações E.A.I. (XX3)
- Adapters E.A.I. (XX4)
|
| Expandir |
|---|
| Parâmetros utilizados na Integração EAI: - MV_EAIMETH: Não deve ser alterado
- MV_EAIUSER
- MV_EAIPASS
- MV_EAIURL2: Endereço do WS para comunicação. Podemos informar a Rota da integração neste parâmetro ou através da rotina CFGA020. Saiba mais: Roteamento E.A.I. Protheus (CFGA020 - SIGACFG)
- MV_EAIWS: Não precisa ser alterado
| Dica |
|---|
| title | Integração RM TOP x Protheus |
|---|
| A integração do Top RM com o Protheus envolve o módulo Gestão de Projetos (SIGAPMS), neste módulo não é necessário realizar alguns cadastros de De/Para na tabela XXF e sim configurar alguns parâmetros. Lista dos parâmetros que envolve as integrações deste módulo: Parâmetros da Integração |
|
Adapters: O cadastro de Adapters são rotinas responsáveis por realizar o processamento das mensagens enviadas e recebidas, possibilitando a inclusão, alteração e exclusão | do Adapter no Protheus.Abaixo segue link completo com as lista dos Adapters utilizado na integração EAI Link: http://tdn.totvs.com/download/attachments/254607629/Mensagens_Protheus.xlsx?api=v2 Caminho para cadastrar os Adapters: Configurador Protheus - Schedule - Adapter E.a.i (CFGA020) Modelos de mensagens Síncronas e Assíncronas As integrações via Mensageria.
As integrações via Mensagem Única |
propõem dois modelos de envio e recebimento de mensagens | . O modelo Síncrono e o Assíncrono. No modelo de mensagens Síncronas a - A mensagem é enviada e o sistema que enviou aguarda o processamento da mensagem pelo receptor
| . Já no modelo Assíncrono a mensagem Observações: - A mensagem é enviada e o sistema que a enviou não aguarda o seu processamento. Posteriormente a mensagem será processada no receptor.
|
O modelo de mensagem que será utilizado na integração deve ser avaliado com muito cuidado. Apesar do |
| modelo síncrono modelo síncrono parecer o mais adequado para uma integração, isto não é de todo verdade. Em um |
| modelo síncrono modelo síncrono deve ser levado em consideração o tempo de processamento: O processamento do sistema que envia, a velocidade do trânsito de dados da rede e o tempo de processamento e resposta do receptor. Isto pode acarretar um tempo de resposta ao usuário muito maior do que o normal, o que pode transformar a integração de solução ao problema. Já o modelo |
| assíncrono, por não aguardar o retorno do processamento do receptor torna o processo mais rápido, porém, neste modelo de mensagem deve-se levar em consideração que o dado será gravado no sistema que envia a mensagem e que o processamento no receptor ocorrerá posteriormente.
Desta maneira, em algumas situações os dados irão existir no sistema de envio, mas enquanto não forem processados no receptor eles não existirão lá. |
|
| | Card |
|---|
| | empresas De/Para de : empresa empresas/filiais irá definir quais empresas e filiais serão integradas entre os dois sistemas. | note | Importante: | Deve ser informado a referencia a outra marca. O cadastro está localizado: Configurador/Ambiente/Schedule/Emp. Fil. Msg. única |
Image Removed
No XML para identificar qual a empresa e qual a filias, avalie as seguintes Tags <CompanyId>e <BranchId>. <CompanyId>= Empresa <BranchId> = Filial No XML é necessário identificar a Aplicação de Origem, a Empresa e a Filial para cadastrar o De/Para. As tags a serem verificadas são: - SourceApplication = Aplicação de Origem (XXD_REFER)
- CompanyId = Empresa (XXD_COMPA)
- BranchId = Filial (XXD_BRANCH)
|
| Expandir |
|---|
| title | De/Para de Mensagem Única |
|---|
| Na maioria das vezes, os códigos dos registros utilizados nos sistemas que se comunicam via Mensagem Única não são os mesmos, a XXF é a tabela que ira guardar os códigos para relacionar os registros, por exemplo um cliente pode possuir o código no Protheus, e no RM esse mesmo cliente possui o código C0100001. Por isso o sistema realiza o cadastro de um "De/Para de Mensagem Única". Ao realizar a inclusão de um cadastro, o sistema verifica se já existe um "De/Para de Mensagem Única", caso já exista, o sistema entende que trata-se de uma alteração, caso não exista, trata-se de uma inclusão, então ele cria automaticamente o "De/Para de Mensagem Única" (XXF). | Dica |
|---|
| Veja o vídeo do processo de cadastro do De/Para de Mensagem Única (XXF): De Para de Mensagem Única O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no navegador Google Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo para superior qualidade. |
Caso trate-se de uma inclusão que referencia códigos de outros cadastros, esses códigos necessitam de um "De/Para de Mensagem Única", por exemplo, ao incluir um Pedido de Vendas você precisa referenciar um código de Produto e um código de cliente, mas, nesse momento, você não está incluindo o cliente ou o produto, você está incluindo o Pedido, portanto o cliente e o produto precisam ter um "De/Para de Mensagem Única" (XXF) cadastrado. |
| Expandir |
|---|
| title | Fontes de Integração |
|---|
| Todos os fontes de integração contém a letra "I" no final do nome da rotina, fontes com processamento a parte em JSON possuem a letra "O" ou "Json" no final. Exemplos: - A rotina de Pedidos de Venda tem seu fonte com nome "MATA410";
- Na integração de Pedido de Venda via XML, o fonte que trata a integração chama-se "MATI410";
- Na integração de Pedido de venda via JSON o fonte que trata a integração chama-se "MATI410O"
- A movimentação do Estoque tem seu fonte com nome "MATA240";
- Na integração da Movimentação via XML, o fonte que trata a integração chama-se "MATI241"
- Na integração da Movimentação via JSON o fonte que trata a integração chama-se "MATI241JSON"
|
| Expandir |
|---|
| title | Extrair Xml-Json Envio e Resposta |
|---|
| Para realizar os testes e analises de ocorrências envolvendo integração EAI, é necessário validar o Xml/Json de envio e de resposta, para extrair os arquivos para análise, realise os passos abaixo: - Acesse o ambiente SIGACFG: Ambiente > Schedule > Adapter EAI
Na integração do Software com o Protheus, são criados os arquivos de transações. - Selecione o arquivo que integrou e para extrair clique na lupa
Image Added . Será exibido as opções para extrair- ENVIO: Visualizar mensagem original: Xml/Json com os dados que o sistema tentou integrar;
- RESPOSTA: Visualizar mensagem de resposta: Xml/Json com a resposta da tentativa de integração.
| Nota |
|---|
| title | Identificando o XML: |
|---|
| Através da Tag <Product> consegue visualizar o Software que esta recebendo ou enviando. Exemplo: XML de envio (original): <Product version="12.1.18.0" name="RM"/> XML de recebimento (resposta): <Product version="12" name="PROTHEUS"/> |
|
| Expandir |
|---|
| Durante a análise de ocorrências no processo de integração, pode ser necessário gerar o Profile para analise das funções executadas ou do tempo de processamento. Para gerar o Profiler no processo de integração é necessário: - Em seu appserver.ini na chave/bloco que carrega o nome do JOB do WebServices [JOB_WS_XXXX]
- Inclua uma linha: "PROFILE=1" e depois salve o arquivo (Atalho: CTRL + S)
| Bloco de código |
|---|
| [JOB_WS_9901]
TYPE=WEBEX
ENVIRONMENT=12.1.2310
INSTANCES=1,1
SIGAWEB=WS
INSTANCENAME=ws
ONSTART=__WSSTART
ONCONNECT=__WSCONNECT
PREPAREIN=99,01
PROFILE=1 <-------- Insira essa chave
SECURITY=0 |
| Aviso |
|---|
| - Para desabilitar a geração do log, basta alterar para "PROFILE=0"
|
Ao integrar/tentar integrar, será gerado um arquivo .txt de log na pasta protheus > protheus_data > wsprofiler: Image Added
|
|
| Card |
|---|
| label | 2 - Configurando o serviço, WebService (caso XML) ou REST (caso JSON) |
|---|
| | Deck of Cards |
|---|
| | Card |
|---|
| label | Configuração RESTful |
|---|
| Para realizar a integração EAI utilizando arquivos Json, é necessário ter um REST funcionando no ambiente. Para configurar o REST siga as orientações do vídeo: Configuração do REST
Exemplo de configuração do REST: Exemplo de REST |
| <CompanyId>15</CompanyId> <BranchId>1</BranchId>| Card |
|---|
| default | true |
|---|
| effectDuration | 0.5 |
|---|
| id |
|---|
|
|
| Integração Mensagem única| Testes de Integrações via XML | | label | Configuração WebServices |
|---|
| Configurando Web Services
A configuração inicia-se habilitando o serviço HTTP e configurando a porta que todos os outros serviços dependentes deste irão utilizar para a publicação das informações: - Acesse o Wizard de configuração dos Serviços;
- Em Servidor Internet (HTTP/FTP), verifique se o serviço de HTTP já existe, confirme se está habilitado e para qual porta está configurada. Pois estas são informações indispensáveis para o correto funcionamento dos WebServices e Portais.
- Caso não tenha o Servidor Internet <HTTP> criado, é necessário seguir o procedimento abaixo:
| Expandir |
|---|
| title | Configurando HTTP/FTP |
|---|
| - Realize o Download dos Arquivos de Portais (web_files) do Portal do Cliente
- Inclua uma pasta web dentro da Protheus Data do Sistema e insira os web_files
- Selecionar a opção: <HTTP> e clicar na barra superior <Editar> conforme exemplo
- O sistema apresentará a tela para Configuração da Seção onde os principais campos são:
- Flag para Habilitar o Protocolo
- Path de Arquivos = Caminho da Pasta Web
- Ambiente = Nome do Ambiente
- Porta de Conexão = Porta de configuração dos Serviços
| Dica |
|---|
| Na configuração da Seção, inserimos como exemplo a porta 92, porém ela pode ser alterada caso prefira. Caso definida a porta padrão do serviço HTTP que é a 80, não é necessário especificá-la na configuração do WS e Portais. |
Basta confirmar e gravar as configurações
|
| Expandir |
|---|
| title | WS TOTVS Linha Protheus Web Services |
|---|
| - Realize as configurações básicas, campos importantes:
- Módulo Web = WS - TOTVS Linha Protheus Web Services
- Nome da Instância = ws
- Diretório Raiz das Imagens (Web Path) = Diretório da Pasta Web onde o sistema irá criar a pasta "ws"
- Selecione o Environment = Nome do Ambiente
- Flag para habilitar processos na inicialização do Servidor
- Realize a Configuração de Host x Empresas/Filiais, campos importantes:
- Host = Server e porta dos Web Services (Deve ser informada a porta informada na Configuração HTTP/FTP)
- Selecione a Empresa/Filial = Empresa e Filial de acesso (Para configuração Multifilial, consulte a respectiva aba)
- Clique em "Relacionar" e em "Avançar"
- Realize a Configuração de Usuários, onde irá definir o número mínimo e máximo de usuários para acesso
Finalizar e confirmar a configuração. |
Após as configurações acima, o sistema irá inserir as informações de acesso aos Web Services no arquivo AppServer.ini do Protheus, verifique se as informações estão de acordo com o exemplo abaixo, caso não estejam realize ajustes (Lembrando que a Porta e o Nome do Ambiente serão os que preencheu durante a configuração):
| Expandir |
|---|
| [HTTP] ENABLE=1 PORT=81
[localhost:92/ws] ENABLE=1 PATH=c:\seuambiente\Protheus_Data\web\ws ENVIRONMENT=12.1.025 INSTANCENAME=ws RESPONSEJOB=JOB_WS_9901 DEFAULTPAGE=wsindex.apw
[JOB_WS_9901] TYPE=WEBEX ENVIRONMENT=12.1.025 INSTANCES=1,1 SIGAWEB=WS INSTANCENAME=ws ONSTART=__WSSTART ONCONNECT=__WSCONNECT LOGPROFILE = 0 PREPAREIN=99,01 SECURITY=0 |
| Dica |
|---|
| Veja o vídeo do processo de configuração dos Web Services: Configurando os Web Services O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no Navegador do Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo e a qualidade será bem melhor. A partir da release 12.1.33, torna-se obrigatório o uso da chave SECURITY = 0 na configuração dos WebServices no appserver.ini do AppServer: https://tdn.totvs.com/x/aiErI |
| Aviso |
|---|
| Fique atento ao utilizar o parâmetro de configuração com a chave Security=0, pois isso fará com que as integrações (APIs) não exijam autenticação, consequentemente dados do seu ambiente poderão ser consultados sem qualquer controle de autorização. |
|
|
|
| Card |
|---|
| label | 3 - Escolha sua ferramenta favorita (SOAP ou POSTMAN) |
|---|
| | De/Para XXF | De/Para XXF: A XXF é a tabela que ira guardar os códigos da mensagem para os casos onde os códigos são diferentes nas marcas, por exemplo um cliente pode ser o 00001/01 no Protheus e no RM C0100001. Para que consigamos efetuar a integração é necessário efetuar o De/Para do cadastro. Image Removed O cadastro está localizado: configurador/Ambiente/DE/PARA Msg. única | | Card |
|---|
| default | true |
|---|
| id | Integração Mensagem única |
|---|
| label |
|---|
|
|
| Soap UI | Ferramenta Soap: É uma ferramenta de mercado onde conseguimos |
| realizar testes de Web Service. Utilizamos o Soap para integrar o XML gerado por um ERP(RM/Logix) e enviar para o Protheussimular o envio do Xml/Json na integração via Mensagem Única, simulando o envio de outros sistemas para o Protheus. Ou seja, ao invés de termos que instalar o outro sistema e aprender como fazer o processo neles, nós pegamos um Xml/Json de modelo enviamos para o Protheus usando esta ferramenta.
Link para baixar o Soap: https://www.soapui.org/downloads/latest-release/ |
|
Integração WS protheus X Soap Ui: 1° No Ini do Appserver, busque o caminho do WS. WEBSERVICELOCATION=http://localhost:92/ws 2° Acesse o WS via browser 3° Busque o EAISERVICE , e clique sobre. 4°Clique sobre a descrição do serviço; Image Removed
5° Copie o endereço do Image Removed. Image Removed
6° Abra o Soap UI - Clique em File - New SOAP Project Image Removed
7° Cole o endereço do WSDL no campo Initial WSDL, clique em OK. Pronto o Soap está integrado com o Web Service do Protheus. Image Removed 8° Cole o XML entre as seguintes Tags: <soapenv:Envelope
| Dica |
|---|
| Veja o vídeo do processo de configuração do SOAPUI: Configurando a ferramenta SoapUI O vídeo está no Google Drive do Suporte FAT / SERV / JUR, caso execute no navegador Google Chrome, a qualidade do vídeo pode ficar mais baixa, sendo esse o caso, é possível fazer o Download do arquivo para superior qualidade. |
| Nota |
|---|
| Caso a integração seja via arquivo Xml, a seguinte Tag deve ser acrescentada:
| Bloco de código |
|---|
| <![CDATA[
(XML Conteúdo que irá dentro da TAG)
]]> |
|
|
| Card |
|---|
| label | Configuração do POSTMAN |
|---|
| | Expandir |
|---|
| title | Testando XML - WebServices no POSTMAN |
|---|
| 1 - Instalar o POSTMAN
2 - Crie um "Request" Image Added
3 - Dê o nome da integração EAI que irá realizar, exemplo: STEPPROJECT, PROJECT ou ORDER Image Added Image Added
4 - Mude o tipo da requisição para "POST" e cole o caminho (http://localhost:xx/ws/EAISERVICE.apw), de acordo com sua porta realizada no WebServices e mude no final, em azul, o tipo do arquivo para "XML" Image Added
5 - Em "Headers" informe conforme abaixo Image Added
6 - Em "Body", cole a requisição (já configurada com o '<![CDATA[]>' dentro de '<tot:INMSG>'), exemplo: | Bloco de código |
|---|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tot="http://www.totvs.com/"> |
|
|
|
<![CDATA[Cole aqui o XML ]]> </tot:INMSG> </tot:RECEIVEMESSAGE> </soapenv:Body> </soapenv:Envelope> | Nota |
|---|
| | - A seguinte Tag tem que ser acrescentada:
<![CDATA[ ]]> - Não esqueça de salvar o Novo Projeto, caso feche o sistema perde inclusive a integração.
| Card |
|---|
| id | Integração Mensagem única |
|---|
| label | Parâmetros |
|---|
| Parâmetros: - MV_EAIMETH (não deve ser alterado)
- MV_EAIUSER
- MV_EAIPASS
- MV_EAIURL2 (Endereço do WS para comunicação) - Podemos informar a Rota da integração através deste parâmetro ou da rotina CFGA020. Saiba mais: Roteamento EAI Protheus (CFGA020 - SIGACFG)
- MV_EAIWS(Não Precisa ser alterado).
|
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<TOTVSMessage>
<MessageInformation version="2.001">
<UUID>a0092a8f-e14e-41b6-a2f9-83076af60a17</UUID>
<Type>BusinessMessage</Type>
<Transaction>PROJECT</Transaction>
<StandardVersion>1.000</StandardVersion>
<SourceApplication>RM</SourceApplication>
<CompanyId>99</CompanyId>
<BranchId>01</BranchId>
<Product name="RM" version="12.1.28.0"/>
<GeneratedOn>2020-11-09T20:25:03</GeneratedOn>
<DeliveryType>Sync</DeliveryType>
</MessageInformation>
<BusinessMessage>
<BusinessEvent>
<Entity>PROJECT</Entity>
<Event>upsert</Event>
</BusinessEvent>
<BusinessContent>
<CompanyId>99</CompanyId>
<BranchId>01</BranchId>
<CompanyInternalId>99|01</CompanyInternalId>
<ShortCode>PMS</ShortCode>
<Code>PROJETO</Code>
<InternalId>PMS</InternalId>
<Description>PROJETO INCLUIDO VIA EAI</Description>
</BusinessContent>
</BusinessMessage>
</TOTVSMessage>
]]>
</tot:INMSG>
</tot:RECEIVEMESSAGE>
</soapenv:Body>
</soapenv:Envelope> |
7 - Para mandar a requisição, aperte em "Send" (certifique-se pelo navegador que seu WebServices está ativando, jogando na URL 'http://localhost:XX/ws')
8 - Resultado típico esperado | Bloco de código |
|---|
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<RECEIVEMESSAGERESPONSE xmlns="http://www.totvs.com/">
<RECEIVEMESSAGERESULT><?xml version="1.0" encoding="utf-8"?><TOTVSMessage><MessageInformation version="2.001"><UUID>c64217f6-fc34-85eb-a1c2-df709e8c20b3</UUID><Type>Response</Type><Transaction>PROJECT</Transaction><StandardVersion>1.000</StandardVersion><SourceApplication>12.1.2310RENOMEAR99</SourceApplication><CompanyId>99</CompanyId><BranchId>01</BranchId><Enterprise></Enterprise><BusinessUnit></BusinessUnit><Product name="PROTHEUS" version="12"></Product><GeneratedOn>2025-02-28T12:01:10Z</GeneratedOn><DeliveryType>Sync</DeliveryType></MessageInformation><ResponseMessage><ReceivedMessage><SentBy>RM</SentBy><UUID>a0093a8f-e14e-41b6-a2f9-83076af60a17</UUID><Event>upsert</Event><MessageContent><![CDATA[<TOTVSMessage><MessageInformation version="2.001"><Product version="12.1.28.0" name="RM"/><UUID>a0093a8f-e14e-41b6-a2f9-83076af60a17</UUID><Type>BusinessMessage</Type><Transaction>PROJECT</Transaction><StandardVersion>1.000</StandardVersion><SourceApplication>RM</SourceApplication><CompanyId>99</CompanyId><BranchId>01</BranchId><GeneratedOn>2020-11-09T20:25:03</GeneratedOn><DeliveryType>Sync</DeliveryType></MessageInformation><BusinessMessage><BusinessEvent><Entity>PROJECT</Entity><Event>upsert</Event></BusinessEvent><BusinessContent><CompanyId>99</CompanyId><BranchId>01</BranchId><CompanyInternalId>99|01</CompanyInternalId><ShortCode>PMS</ShortCode><Code>PROJETO</Code><InternalId>PMS</InternalId><Description>PROJETO INCLUIDO VIA EAI</Description></BusinessContent></BusinessMessage></TOTVSMessage>]]></MessageContent></ReceivedMessage><ProcessingInformation><ProcessedOn>2025-02-28T12:01:10Z</ProcessedOn><Status>error</Status><ListOfMessages><Message type="error" code=""><![CDATA[
--------------------------------------------------------------------------------
Id do formulario de erro: [AF8MASTER]
Id do campo de origem: [VLDDATA_OBRIGAT]
Id do campo de erro: [AF8_CALEND]
Id do erro: [OBRIGAT]
Mensagem do erro: [O campo Calendario (AF8_CALEND) não foi preenchido]
]]>
</Message></ListOfMessages></ProcessingInformation><ReturnContent></ReturnContent></ResponseMessage></TOTVSMessage></RECEIVEMESSAGERESULT>
</RECEIVEMESSAGERESPONSE>
</soap:Body>
</soap:Envelope> |
|
|
|
|
| Card |
|---|
| | Deck of Cards |
|---|
| | Card |
|---|
|
Image Added
| Deck of Cards |
|---|
| | Card |
|---|
| label | Teste de Envio (Xml) |
|---|
|
|
|
|
| Card |
|---|
| id | Integração Mensagem única |
|---|
| label | Testes EAI (JSON) |
|---|
| Image Added
| Deck of Cards |
|---|
| | Card |
|---|
| label | Teste de Recebimento (Json) |
|---|
| Este teste permite testar o recebimento da Mensagem Única de outro sistema para o Protheus. Para iniciar os testes é necessário que tenha realizado as etapas: - Cadastro do Adapter
- De/Para de Empresas e Filiais
- Exemplo de REST
- Configuração do REST
- Configurando o SOAPUI
| Dica |
|---|
| - Caso seja necessário a utilização de um Json enviado pelo cliente no teste, é necessário criar um De/Para de Mensagem única para os códigos referenciados no cadastro
Exemplo: Código de Vendedor no campo A1_VEND, é necessário criar um de/para de mensagem única usando o " VendorInformationInternalID" como "Valor Externo" e no "Valor interno" é preciso informar a empresa, a filial e o código do vendedor como neste exemplo.
|
| Aviso |
|---|
| - Exemplos de Arquivos Json para teste:
|
|
|
|
|
| | Card |
|---|
| id | Integração Mensagem única |
|---|
| label | Fontes de Integração |
|---|
| Fontes de Integração:| Card |
|---|
|
| id | Integração Mensagem única |
|---|
label | Configuração WS| Card |
|---|
| id | Integração Mensagem única |
|---|
| label |
|---|
|
|
|
|
| Outras Documentações | Documentações para apoio:| EAI Protheus (framework) | EAI Protheus | Treinamento Mensagem única |
|