Histórico da Página

Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Descrever os serviços necessários para que o monitor do TOTVS EAI  consiga realizar o diagnóstico dos serviços/integrações habilitadas entre os produtos integrados.

Definição da Regra de Negócio

Pré-requisitos

Os serviços de diagnósticos  disponibilizados pelos produtos deverão atender os seguintes pré-requisitos:

• Plataforma com suporte a REST e autenticação HTTP Basic.
• Suporte a expressões XPath, para pesquisa de conteúdo em documentos XML.
• Suporte a tratamento de cross-domain, por conta das requisições de serviços em servidores de domínio diferente.

Definições gerais dos serviços

Todas as linhas de produto deverão definir uma URL base, a partir da qual os serviços REST do monitor de EAI serão disponibilizados. Todos os caminhos descritos neste documento serão relativos a esta URL base, conforme a especificação de requisitos ER_FRWJOI01-3_Serviços_para_monitoramento_de_EAI. 

Os objetos de retorno dos métodos REST seguem o retorno especificado no requisito ER_FRWJOI01-3_Serviços_para_monitoramento_de_EAI. 

Todas as linhas de produto deverão disponibilizar no monitor os caminhos dos serviços do EAI de seus produtos.

Todos os parâmetros de query string page e perpage, quando não especificados, assumem o valor default de 1 e 10, respectivamente.

Serviços REST - Originados do Monitor EAI para o serviço REST do monitor disponível nos aplicativos (produtos)

GET /totvseai/monitor/v1/admin/companies/{appID}/{companyID}/{branchID}?page={page}&perPage={perPage}

Este método lista os de-para de empresas do aplicativo interno.

Caso o parâmetro appID seja enviado, é buscado a informação do relacionamento somente para o aplicativo em questão. Caso contrário, é buscado todas as informações dos aplicativos disponiveis (no Protheus uma mesma instalação pode possuir mais de um aplicativo, pois cada Grupo de empresas Protheus comporta um aplicativo).

Pode-se também enviar os parâmetros de companyID (para buscar o mapeamento somente de uma empresa/grupo daquele aplicativo) e branchID, para buscar somente daquela filial.

Retorno esperado:

• appID - Identificador do aplicativo interno (ex.PRODUCAO18@PROTHEUS)
• product - Nome do Produto interno (ex. PROTHEUS)
• companies - Array de objetos, onde cada objeto possui os atributos:
  • company - Empresa ou grupo de empresas (Protheus) do produto buscado
  • branch - Filial do produto buscado
  • integratedProducts  - Array de objetos, sendo
  • appID - Indentificador do aplicativo externo (Ex. PRODUCAO)
  • product - Indentificador do produto externo (Ex. RM)
  • company - Empresa ou grupo de empresas (Protheus) associado
  • branch - Filial associado ao produto externo.

{
  "messages": [],
  "length": 2,
  "data": [
    {
      "appID": "PRODUCAO18",
      "product": "PROTHEUS",
      "companies": [
        {
          "company": "18",
          "branch": "D MG 01",
          "integratedProducts": [
            {
              "appId": "AMBIENTE",
              "product": "RM",
              "company": "01",
              "branch": "01"
            },
            {
              "appId": "AMBX",
              "product": "DATASUL",
              "company": "1",
              "branch": "10"
            }
          ]
        },
        {
          "company": "18",
          "branch": "D RJ 01",
          "integratedProducts": [
            {
              "appId": "AMBIENTE",
              "product": "RM",
              "company": "01",
              "branch": "02"
            },
            {
              "appId": "AMBX",
              "product": "DATASUL",
              "company": "1",
              "branch": "11"
            }
          ]
        }
      ]
    },
    {
      "appID": "PRODUCAO19",
      "product": "PROTHEUS",
      "companies": [
        {
          "company": "19",
          "branch": "D MG 01",
          "integratedProducts": [
            {
              "appId": "AMBIENTE",
              "product": "RM",
              "company": "02",
              "branch": "02"
            }
          ]
        }
      ]
    }
  ]
}

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"appID" : "PRODUCAO19",
		"product" : "PROTHEUS",
		"companies" : [{
				"company" : "19",
				"branch" : "D MG 01",
				"integratedProducts" : [{
						"appId" : "AMBIENTE",
						"product" : "RM",
						"company" : "02",
						"branch" : "02"
					}
				]
			}
		]
	}
}

O método GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}  já criado para o monitor EAI será alterado, e um novo atributo será incluído no JSON:

• avaiableVersions - Indica as versões disponíveis para configuração da transação em questão. As diferentes versões disponíveis serão separadas por ";".

  Bloco de código
  language java title Exemplo de retorno de JSON
  { "messages" : [], "length" : 1, "data" : [{ "transactionID" : "order", "version" : "2.000", "supportedMode" : "both_enabled", "enabledMode" : "both_enabled", "allowAnonymous" : false, "includeOriginalMsg" : false "avaiableVersions" : "1.000;1.001" } ] }

GET /totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?appID={appid}&transactions={jSON}

Este serviço verifica a integridade da integração de acordo com as transações habilitadas em um aplicativo na camada do EAI (framework).

O parâmetro appID informa o aplicativo na origem da requisição. Por exemplo, o monitor quer validar informações colhidas no RM e validar contra estas informações no Protheus. Neste caso, o appID seria RM. O intuito deste parâmetro é poder verificar a consistência das rotas. Caso ele não seja enviado, informações de validações das rotas não serão verificadas.

o parâmetro transactions, opcional, quando enviado fará a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. A estrutura deste jSON é o mesmo do método  GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}.

O retorno esperado para este método é um outro jSON, que retornará a compatibilidade ou não das transações enviadas x transações no aplicativo.

O envio de jSON é opcional pois existem validações internas que independem do cadastro de outro sistema. Desta forma, se o JSON não for recebido pelo serviço, somente estas validações deverão ser verificadas.

JSON de retorno esperado:

• transactionID - Identificador da transação
• code - codigo do erro, para padronização das mensagens de erro identificadas. Estes erros seguem o padrão das mensagens de erro do EAI TOTVS. São listados novos status para o serviço de monitoramento

• (tabela abaixo). Caso o código de erro seja omitido, somente o valor do atributo text é apresentado como um status de erro. Caso o atributo text também não seja enviado, um erro genérico será apresentado.
• text  - Texto opcional, que pode ser acrescido as mensagens recebidas. A string associada ao código de erro sempre é apresentada ao usuário. O contexto deste retorno é acrescentar informações adicionais ao erro apresentado.

 {
    "messages" : [],
    "length" : 1,
    "data" : {
        "transactioID" : "order",
        "code":"FW006"
       "text":"Filial de execução - 001"
    }
}

GET /totvseai/monitor/v1/admin/healthcheck/checktransactions/business?appID={appid}&transactions={jSON}

Este serviço verifica a integridade da integração de acordo com as transações habilitadas em um aplicativo na camada de negócio (business).

O parâmetro appID informa o aplicativo na origem da requisição. Por exemplo, o monitor quer validar informações colhidas no RM e validar contra estas informações no Protheus. Neste caso, o appID seria RM. O intuito deste parâmetro é poder verificar a consistência das rotas. Caso ele não seja enviado, informações de validações das rotas não serão verificadas.

o parâmetro transactions, opcional, quando enviado fará a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. A estrutura deste jSON é o mesmo do método  GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}.

O retorno esperado para este método é um outro jSON, que retornará a compatibilidade ou não das transações enviadas x transações no aplicativo.

O envio de jSON é opcional pois existem validações internas que independem do cadastro de outro sistema. Desta forma, se o JSON não for recebido pelo serviço, somente estas validações deverão ser verificadas.

JSON de retorno esperado:

• transactionID - Identificador da transação
• code - codigo do erro, para padronização das mensagens de erro identificadas. Estes erros seguem o padrão das mensagens de erro do EAI TOTVS. Códigos de erro de negócio são iniciados pela letra "A" e devem ser gerados pelas áreas envolvidas. Caso o código de erro seja omitido, somente o valor do atributo text é apresentado como um status de erro. Caso o atributo text também não seja enviado, um erro genérico será apresentado.
• text  - Texto opcional, que pode ser acrescido as mensagens recebidas. A string associada ao código de erro sempre é apresentada ao usuário. O contexto deste retorno é acrescentar informações adicionais ao erro apresentado.

 Caberá a cada framework como identificar a melhor maneira possível de realizar as chamadas as validações de cada área de negócio envolvida na integração.

No Protheus os adapters serão chamados e os dados recebidos na requisição REST serão repassados para cada um dos adapters, que serão responsáveis por realizar as validações internas necessárias. Caso não haja tratamento para a CHECKINTEGRITY é assumido que não existe validação necessária para o adapter.

O retorno esperado segue o proposto pelo método /totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?appID={appid}&transactions={jSON}

 {
    "messages" : [],
    "length" : 1,
    "data" : {
        "transactioID" : "financing",
        "code":""
       "text":"É necessário configurar o parâmetro MV_MULNATP e MV_MULNATR na integração com o TOTVS Incorporações."
    }
}

GET /totvseai/monitor/v1/admin/healthcheck/checkcompanies/{appID}/{companyID}/{branchID}

Este serviço verifica a integridade dos mapeamentos de empresa/filial entre o aplicativo origem e destino

Somente o parâmetro branchID é opcional.

O JSon esperado por este método deve possuir os atributos a seguir:

• originAppID
• companies  - 

Serviços SOAP - Originados do Monitor EAI para o serviço de EAI do aplicativo

Os serviços SOAP a seguir visam reutilizar os serviços de EAI - Mensagem Única já existentes nos produtos. Eles tem como originador o Monitor Totvs EAI e tem como destino os serviços de EAI dos aplicativos cadastrados.

Serviço que verifica se o servidor do serviço do EAI está disponível.

O serviço irá gerar uma requisição de consulta ao WSDL do serviço do EAI cadastrado para o aplicativo.

GET http://localhost:8080/eaiservice.apw

<?xml version="1.0" encoding="utf-8"?>
<!-- Generated 20160927 10:35:39 by ADVPL WSDL Server 1.110216 / Protheus 7.00.131227A-20160909 NG -->
<definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:s0="http://www.totvs.com/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" 
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
targetNamespace="http://www.totvs.com/" xmlns="http://schemas.xmlsoap.org/wsdl/">
    <types>
        <s:schema elementFormDefault="qualified" targetNamespace="http://www.totvs.com/">
            <s:element name="RECEIVEMESSAGE">
                <s:complexType>
                    <s:sequence>
                        <s:element minOccurs="1" maxOccurs="1" name="INMSG" type="s:string" />
                    </s:sequence>
                </s:complexType>
            </s:element>
            <s:element name="RECEIVEMESSAGERESPONSE">
                <s:complexType>
                    <s:sequence>
                        <s:element minOccurs="1" maxOccurs="1" name="RECEIVEMESSAGERESULT" type="s:string" />
                    </s:sequence>
                </s:complexType>
            </s:element>
        </s:schema>
    </types>
    <message name="RECEIVEMESSAGESOAPIN">
        <part name="parameters" element="s0:RECEIVEMESSAGE" />
    </message>
    <message name="RECEIVEMESSAGESOAPOUT">
        <part name="parameters" element="s0:RECEIVEMESSAGERESPONSE" />
    </message>
    <portType name="EAISERVICESOAP">
        <operation name="RECEIVEMESSAGE">
            <documentation>Metodo que recebe mensagens para processamento pelo Microsiga Protheus</documentation>
            <input message="s0:RECEIVEMESSAGESOAPIN" />
            <output message="s0:RECEIVEMESSAGESOAPOUT" />
        </operation>
    </portType>
    <binding name="EAISERVICESOAP" type="s0:EAISERVICESOAP">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
        <operation name="RECEIVEMESSAGE">
            <soap:operation soapAction="http://www.totvs.com/RECEIVEMESSAGE" style="document" />
            <input>
                <soap:body use="literal" />
            </input>
            <output>
                <soap:body use="literal" />
            </output>
        </operation>
    </binding>
    <service name="EAISERVICE">
        <documentation>&lt;b&gt;Serviço genérico de integração com o Microsiga Protheus via EAI&lt;/b&gt;</documentation>
        <port name="EAISERVICESOAP" binding="s0:EAISERVICESOAP">
            <soap:address location="http://172.16.32.191:89/pr12_bra/eai/EAISERVICE.apw" />
        </port>
    </service>
</definitions>

Caso seja necessária autenticação no aplicativo destino, a mesma deverá ser enviada no header da requisição, via basic authentication. Para isto será necessário cadastrar o usuário de acesso ao EAI no monitor (o usuário de acesso nem sempre é o usuário logado no monitor).

Serviço que visa verificar se o aplicativo destino está recebendo requisições normalmente.

 POST WhoIS

Este serviço irá realizar o post da Mensagem Única TOTVS WhoIs e irá aguardar o retorno da requisição.

A mensagem única TOTVS espera um código de empresa e filial para mapeamento de integrações. Este empresa e filial será capturada pelo método GET /totvseai/monitor/v1/admin/getcompanies.

O SourceApplication e Product  enviados na mensagem serão padronizados como "TOTVSMONITOR". O atributo version da tag Product será enviado com a versão "1.000".

O retorno deste método definirá se o EAI está disponível para recebimento (serviço disponível no ar) e se houve sucesso na autenticação. A verificação será realizada pelo retorno do status da conexão HTTP e pelo retorno da mensagem do tipo ResponseMessage.

Os valores de companyID e branchID são recuperados pelo método GET /totvseai/monitor/v1/admin/companies/{appID}/{companyID}/{branchID}?page={page}&perPage={perPage}

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tot="http://www.totvs.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tot:receiveMessage>
         <tot:inMsg><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<TOTVSMessage>
<MessageInformation version="1.000">
<UUID>dee8c4da-1e19-4b44-df97-249443638a9d</UUID>
<Type>BusinessMessage</Type>
<Transaction>WHOIS</Transaction>
<StandardVersion>1.000</StandardVersion>
<SourceApplication>TOTVSMONITOR</SourceApplication>
<CompanyId>18</CompanyId>
<BranchId>D MG 01</BranchId>
<Product name="TOTVSMONITOR" version="1.000"></Product>
<GeneratedOn>2015-11-26T10:55:23</GeneratedOn>
<DeliveryType>Sync</DeliveryType>
</MessageInformation>
<BusinessMessage>
<BusinessRequest>
<Operation>WhoIs</Operation>
</BusinessRequest>
<BusinessContent/>
</BusinessMessage>
</TOTVSMessage>]]></tot:inMsg>
      </tot:receiveMessage>
   </soapenv:Body>
</soapenv:Envelope>

O retorno esperado da Mensagem Única WhoIs deverá ser semelhante ao seguinte:

<?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>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;&lt;TOTVSMessage&gt;&lt;MessageInformation version=&quot;1.001&quot;&gt;&lt;UUID&gt;66a7fdd0-ec4d-ac9a-0915-4a0c17a75cd4&lt;/UUID&gt;&lt;Type&gt;Response&lt;/Type&gt;&lt;Transaction&gt;WHOIS&lt;/Transaction&gt;&lt;StandardVersion&gt;1.000&lt;/StandardVersion&gt;&lt;SourceApplication&gt;PR12_BRA&lt;/SourceApplication&gt;&lt;CompanyId&gt;18&lt;/CompanyId&gt;&lt;BranchId&gt;D MG 01 &lt;/BranchId&gt;&lt;Product name=&quot;PROTHEUS&quot; version=&quot;12&quot;&gt;&lt;/Product&gt;&lt;GeneratedOn&gt;2016-09-27T17:05:16Z&lt;/GeneratedOn&gt;&lt;DeliveryType&gt;Sync&lt;/DeliveryType&gt;&lt;/MessageInformation&gt;&lt;ResponseMessage&gt;&lt;ReceivedMessage&gt;&lt;SentBy&gt;TOTVSMONITOR&lt;/SentBy&gt;&lt;UUID&gt;dee8c4da-1e19-4b44-df97-249443638a9d&lt;/UUID&gt;&lt;MessageContent&gt;&lt;![CDATA[&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;&lt;TOTVSMessage&gt;&lt;MessageInformation version=&quot;1.000&quot;&gt;&lt;UUID&gt;dee8c4da-1e19-4b44-df97-249443638a9d&lt;/UUID&gt;&lt;Type&gt;BusinessMessage&lt;/Type&gt;&lt;Transaction&gt;WHOIS&lt;/Transaction&gt;&lt;StandardVersion&gt;1.000&lt;/StandardVersion&gt;&lt;SourceApplication&gt;TOTVSMONITOR&lt;/SourceApplication&gt;&lt;CompanyId&gt;18&lt;/CompanyId&gt;&lt;BranchId&gt;D MG 01&lt;/BranchId&gt;&lt;Product name=&quot;TOTVSMONITOR&quot; version=&quot;1.000&quot;&gt;&lt;/Product&gt;&lt;GeneratedOn&gt;2015-11-26T10:55:23&lt;/GeneratedOn&gt;&lt;DeliveryType&gt;Sync&lt;/DeliveryType&gt;&lt;/MessageInformation&gt;&lt;BusinessMessage&gt;&lt;BusinessRequest&gt;&lt;Operation&gt;WhoIs&lt;/Operation&gt;&lt;/BusinessRequest&gt;&lt;BusinessContent&gt;&lt;/BusinessContent&gt;&lt;/BusinessMessage&gt;&lt;/TOTVSMessage&gt;]]&gt;&lt;/MessageContent&gt;&lt;/ReceivedMessage&gt;&lt;ProcessingInformation&gt;&lt;ProcessedOn&gt;2016-09-27T17:05:16Z&lt;/ProcessedOn&gt;&lt;Status&gt;ok&lt;/Status&gt;&lt;/ProcessingInformation&gt;&lt;ReturnContent&gt;&lt;EnabledTransactions&gt;&lt;Transaction&gt;&lt;Name&gt;WHOIS&lt;/Name&gt;&lt;Version&gt;1.001 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;MYMESSAGE&lt;/Name&gt;&lt;Version&gt;1.000 &lt;/Version&gt;&lt;Mode&gt;send_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;COSTCENTER&lt;/Name&gt;&lt;Version&gt;2.000 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;FINANCIALNATURE&lt;/Name&gt;&lt;Version&gt;2.000 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;ACCOUNTRECEIVABLEDOCUMENTDISCHARGE&lt;/Name&gt;&lt;Version&gt;2.001 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;CUSTOMERVENDOR&lt;/Name&gt;&lt;Version&gt;2.002 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;Transaction&gt;&lt;Name&gt;BANK&lt;/Name&gt;&lt;Version&gt;1.007 &lt;/Version&gt;&lt;Mode&gt;both_enabled&lt;/Mode&gt;&lt;/Transaction&gt;&lt;/EnabledTransactions&gt;&lt;/ReturnContent&gt;&lt;/ResponseMessage&gt;&lt;/TOTVSMessage&gt;</RECEIVEMESSAGERESULT>
        </RECEIVEMESSAGERESPONSE>
    </soap:Body>
</soap:Envelope>