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 disponibilizados pelos produtos deverão atender os seguintes pré-requisitos:

• Plataforma com suporte a REST e autenticação ;
• Autenticação HTTP Basic.;
• 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

Os endpoints definidos neste documento seguem as definições presentes no documento Guia de implementação das APIs TOTVS. Em função disso, a API de diagnóstico terá uma versão diferente da API de monitoramento definida no documento 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, de forma que um ERP possa efetuar chamadas aos serviços dos demais ERPs.

Os parâmetros de paginação page e pageSize, 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 dos aplicativos (produtos)

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

GET /totvseai/monitor/v2/admin/companies?externalAppID={externalAppID}&companyID={companyID}&branchID={branchId}&page={page}&pageSize={pageSize}

Busca de empresas e filiais associadas (De-para de empresas)

Este método lista os de-para de empresa de um aplicativo interno (identificador do de-para igual a "CompanyInternalID"). Caso o parâmetro externalAppID seja enviado, é buscado a informação do relacionamento somente para o aplicativo externo em questão. Caso contrário, é buscado todas as informações dos aplicativos disponíveis.

Pode-se também enviar os parâmetros de companyID (valor da empresa do aplicativo interno) para buscar o mapeamento somente de uma empresa/grupo daquele aplicativo e branchID (valor da filial interna), para buscar somente daquela filial.Atributos do JSON de retorno esperado:

• appID - Identificador do aplicativo interno (ex.PRODUCAO18)
• productCode - Nome do Produto interno (ex. PROTHEUS)
• hasNext - indica se há mais itens além dos retornados na resposta.
• items- Array de objetos, onde cada objeto possui os seguintes atributos:
  • companyID - Empresa ou grupo de empresas (Protheus) do aplicativo interno.
  • branchID - Filial do aplicativo interno.
  • integratedProducts  - Array de objetos, sendo:
    • appID - Identificador do aplicativo externo (Ex. PRODUCAO)
    • productCode - Identificador do produto externo (Ex. RM)
    • companyID - Valor equivalente, no aplicativo externo, da empresa ou grupo de empresas (Protheus) associado.
    • branchID - Filial do aplicativo externo, equivalente a filial do aplicativo interno.

Fluxo do serviço. Neste exemplo, o Protheus será o aplicativo interno, e a comunicação é realizada apenas entre o monitor e o serviço REST do aplicativo.

Legenda: (seta verde) requisição de origem; (seta vermelha) resposta da requisição.

Retorno em caso de falha

O método deve retornar as seguintes mensagens de erro, bem como o código HTTP 404 (Not found) quando:

• O aplicativo interno não possuir de-para de empresas cadastrado (código FE012);
• Não existir registros de de-para de empresa para o aplicativo externo informado (externalAppID) (código FE011);
• Não existir registros de de-para com o companyID ou branchID informados (FE009).

O formato do corpo da resposta deve estar conforme especificado no Guia de implementação das APIs TOTVS. Ou seja:

• code: recebe o codigo do erro.
• message: recebe o texto padrão do erro.
• detailedMessage: recebe texto complementar ao erro padrão, podendo ser um detalhe técnico ou maiores explicações sobre a causa do erro.

Exemplos de retorno

• Obtendo todos os de-para de empresa do aplicativo interno.

{
	"appID": "PRODUCAO18",
	"productCode": "PROTHEUS",
	"hasNext": false,
	"items": [{
		"companyID": "18",
		"branchID": "D MG 01",
		"integratedProducts": [{
			"appID": "AMBIENTE",
			"productCode": "RM",
			"companyID": "01",
			"branchID": "01"
		},
		{
			"appID": "AMBX",
			"productCode": "DATASUL",
			"companyID": "1",
			"branchID": "10"
		}]
	},
	{
		"companyID": "18",
		"branchID": "D RJ 01",
		"integratedProducts": [{
			"appID": "AMBIENTE",
			"productCode": "RM",
			"companyID": "01",
			"branchID": "02"
		},
		{
			"appID": "AMBX",
			"productCode": "DATASUL",
			"companyID": "1",
			"branchID": "11"
		}]
	}]
}

• Obtendo os de-para de empresa do aplicativo interno com o aplicativo externo RM.

{
	"appID": "PRODUCAO18",
	"productCode": "PROTHEUS",
	"hasNext": true,
	"items": [{
		"companyID": "18",
		"branchID": "D MG 01",
		"integratedProducts": [{
			"appID": "AMBIENTE",
			"productCode": "RM",
			"companyID": "01",
			"branchID": "01"
		}]
	},
	{
		"companyID": "18",
		"branchID": "D RJ 01",
		"integratedProducts": [{
			"appID": "AMBIENTE",
			"productCode": "RM",
			"companyID": "01",
			"branchID": "02"
		}]
	}]
}

• Obtendo os de-para de empresa do aplicativo interno para a empresa "18" e filial "D MG 01".

{
	"appID": "PRODUCAO18",
	"productCode": "PROTHEUS",
	"hasNext": true,	
	"items": [{
		"companyID": "18",
		"branchID": "D MG 01",
		"integratedProducts": [{
			"appID": "AMBIENTE",
			"productCode": "RM",
			"companyID": "01",
			"branchID": "01"
		},
		{
			"appID": "AMBX",
			"productCode": "DATASUL",
			"companyID": "1",
			"branchID": "10"
		}]
	}]
}

Âncora
/totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage} /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}

Transações habilitadas no aplicativo

O método GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}, já criado para o monitor EAI, será utilizado. Para mais informações, consulte o método na especificação correspondente.

Fluxo de envio para o App Interno:

Image Removed

Fluxo de envio para consulta direto no app externo:

Image Removed

Fluxo de envio para o App Interno:

Image Added

Fluxo de envio para consulta direto no app externo:

Image Added

Legenda: (seta verde) requisição de origem; (seta vermelha) resposta da requisição.

Exemplos de retorno podem ser vistos na especificação do método.

Âncora

/totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?appID={appid}&version={version}&suportedMode={suportedMode}&enableMode={enableMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&avaiableVersions={avaiableVersions} /totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?appID={appid}&version={version}&suportedMode={suportedMode}&enableMode={enableMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}&avaiableVersions={avaiableVersions}

GET /totvseai/monitor/v2/admin/healthcheck/checktransactions/EAI?targetAppID={targetAppID}&transactionID={transactionID}&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}

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 targetAppID informa o aplicativo na origem da requisição. Por exemplo, o monitor quer validar informações colhidas no RM contra as informações presentes no Protheus. Neste caso, o targetAppID seria RM e a requisição seria enviada ao Protheus. 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.

Os parâmetros version, supportedMode e enabledMode, opcionais, quando enviados farão a consistência de uma transação (adapter) cadastrado em um aplicativo A contra um aplicativo B. Os valores permitidos para estes dados seguem os valores do retorno 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 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 destes parâmetros é opcional pois existem validações internas que independem do cadastro de outro sistema. 

JSON de retorno esperado :(baseado no formato definido no Guia de Implementação das APIs TOTVS):

• transactionID transactionID - Identificador da transação
• messages   - Array de objetos, contendo as mensagens pertinentes a transação:
  • code - codigo código 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. Caso o código de erro seja omitido, somente o valor do atributo additionalInformation é detailedMessage é apresentado como um status de erro. Caso o atributo additionalInformation também detailedMessage também não seja enviado, um erro genérico será apresentado. Os códigos de erro podem ser encontrados aqui.
  • text  message - Texto do erro padrão.
  • additionalInformation detailedMessage - Texto opcional, que pode ser acrescido as das 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.

Fluxo conceitual de envio para o aplicativo interno:

Image Removed

• • O contexto deste retorno é acrescentar informações adicionais ao erro apresentado.

Fluxo conceitual de envio para o aplicativo interno:

Image Added

Verificações realizadas por este endpoint:

O ERP, ao receber uma requisição neste endpoint, efetuará uma requisição para o endpoint GET /totvseai/monitor/v1/apps/{targetAppID}/transactions/{transactionID} no aplicativo indicado pelo parâmetro targetAppID.

Após receber o retorno do aplicativo, o aplicativo interno verificará:

• Se a transação existe no aplicativo consultado;
• Existindo transação, se as versões da transação existem no aplicativo consultado;
• Se o modo suportado da transação/versão é compatível com o modo suportado do aplicativo consultado (ver tabela logo abaixo);
• Se o modo habilitado da transação/versão é compatível com o modo habilitado do aplicativo consultado (ver tabela logo abaixo);
• Se a transação/versão está habilitada no aplicativo interno e no aplicativo consultado.

Compatibilidade de modos: Indica se é possível a troca de mensagens entre os aplicativos quando a transação encontra-se nos cenários abaixo:

Exemplo e envio de requisição para o aplicativo interno:

 {
	"items" :[{
		"transactionID" : "order",
		"messages" : [{
				"code" : "FW006"
				"textmessage" : "Mensagem somente executada em uma filial.",
				"additionalInformationdetailedMessage": "Mensagem disponível somente na filial 001"
			}
		]
	}]
}

Âncora
Check_de_parametrização_business Check_de_parametrização_business

GET /totvseai/monitor/v2/admin/healthcheck/checktransactions/business?targetAppID={targetAppID}&transactionID={transactionID}&version={version}

<<< Acrescentar método para enviar parâmetros adicionais ao ERP destino >>>

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 targetAppID 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 targetAppID 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 retorno esperado para este método é um outro jSONJSON, que retornará a compatibilidade ou não das transações enviadas x transações no aplicativo.

O envio destes parâmetros é opcional pois existem validações internas que independem do cadastro de outro sistema. 

As áreas de negócio deverão ser responsáveis por permitir ou não validação de terceiros (customizações) em suas rotinas.

JSON de retorno esperado:

• transactionID - Identificador da transação
• messages   - Array de objetos, contendo as mensagens pertinentes a transação:
  
  • code - codigo código 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. Caso o código de erro seja omitido, somente o valor do atributo additionalInformation é atributo detailedMessage é apresentado como um status de erro. Caso o atributo additionalInformation também atributo detailedMessage também não seja enviado, um erro genérico será apresentado. Os códigos de erro podem ser encontrados aqui.
  • text  message - Texto do erro padrão
  • additionalInformation detailedMessage - 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/v2/admin/healthcheck/checktransactions/EAI?targetAppID={targetAppID}&transactionId={transactionID}&version={version}.

Fluxo de envio do método:

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

Âncora
/totvseai/monitor/v1/admin/healthcheck/getcompanies/{appID}/{companyID}/{branchID} /totvseai/monitor/v1/admin/healthcheck/getcompanies/{appID}/{companyID}/{branchID}

GET /totvseai/monitor/v1/admin/healthcheck/checkMapping/{AppID}?mappingValue={mappingValue}&mappingID={mappingID}

Este serviço verifica a integridade dos mapeamentos entre entidades do aplicativo origem e destino

Este produto busca, a partir de uma chave de internalID os valores do correspondente no outro aplicativo.

• appID - Código do aplicativo interno
• mappingValue - Valor do codigo interno (de-para) do aplicativo interno
• mappingID = valor do ID o mapping . As definições sobre mappindID ainda estão ocorrendo. Somente o CompanyBranch estará disponível a princípio.
  
  

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

• destinationAppID -  Código do aplicativo externo.
• mappingValue - Valor do código interno
• messages  - array de objetos, contendo
  
  • 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. Caso o código de erro seja omitido, somente o valor do atributo additionalInformation é apresentado como um status de erro. Caso o atributo additionalInformation também não seja enviado, um erro genérico será apresentado. Os códigos de erro podem ser encontrados aqui.
  • text  - Texto do erro padrão
  • additionalInformation - 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.

Fluxo de envio para o aplicativo interno:

Fluxo de envio diretamente a um aplicativo externo:

Abaixo, exemplo de busca de de-para de empresas, com a requisição originada do aplicativo RM contra o Protheus

 {
	"messages" : [],
	"length" : 1,
	"data" : {
		"destinationAppID" : "PROTHEUS18@PRODUCAO",
		"mappingValue":"18|D MG 01",
		"messages" : [{
				"code" : "FI001"
				"text" : "Validado",
					"additionalInformation":""
			}
		]
	}
}

 {
	"messages" : [],
	"length" : 1,
	"data" : {
		"destinationAppID" : "PROTHEUS18@PRODUCAO",
		"mappingValue":"",
		"messages" : [{
				"code" : "FE011"
				"text" : "Não existe de-para associado.",
				"additionalInformation":""
			}
		]
	}
}

Âncora
Check_ws Check_ws

GET /totvseai/monitor/v1/admin/healthcheck/wsintegration/{targetAppID}/{companyID}/{branchID}

Este serviço realiza o teste de envio de WhoIs a outro sistema partindo de um erp (existe um método de verificação partindo do próprio monitor). O intuito deste serviço é testar se a comunicação entre os ERPs está funcionando de maneira satisfatória.

Este método é disparado visando validar a integração de um sistema A contra um sistema B. Neste cenário, o serviço REST é enviado ao sistema A, e o parâmetro targetAppID é enviado com o valor de B. O sistema A então irá validar se a integração com o sistema B está operante através de envio da mensagem WhoIS. O sistema A então devolve o status para o serviço do monitor.

O parâmetro targetAppID recebe o valor do aplicativo ao qual o destino deverá tentar conectar-se.

O parâmetro companyID recebe o valor da empresa/grupo de empresas do aplicativo A

o parâmetro branchID é opcional, e recebe o valor da filial buscada do aplicativo A

O jSon de retorno esperado para este método contém os seguintes atributos:

• • origintargetAppID  - targetAppID que enviou a requisição ao outro sitema.
  • destinationtargetAppID - targetAppID que se deseja verificar a integração.
  • originCompany - Empresa ou grupo originais enviados
  • originBranch - Filial enviada
  • messages - array de objetos, contendo:
    
    • 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. Caso o código de erro seja omitido, somente o valor do atributo additionalInformation é apresentado como um status de erro. Caso o atributo additionalInformation também não seja enviado, um erro genérico será apresentado. Os códigos de erro podem ser encontrados aqui.
    • text  - Texto do erro padrão
    • additionalInformation - 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.

Fluxo de envio da requisição, onde Protheus é o aplicativo interno:

Exemplo de envio de requisição ao Protheus, onde o mesmo irá disparar a WhoIs para o RM

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"origintargetAppID" : "PRODUCAO18@PROTHEUS",
		"destinationtargetAppID" : "RM@RM",
		"originCompany" : "18",
		"originBranch" : "D MG 01",
		"messages" : [{
				"code" : "FI001"
				"text" : "Validado",
					"additionalInformation":""
			}
		]
	}
}

Âncora
settings settings

GET /totvseai/monitor/v1/admin/healthcheck/settings?targetAppID={targetAppID}

Este serviço inicializa validações específicas de produto. 

O jSon de retorno esperado para este método contém os seguintes atributos:

• • AppID- Sistema que recebeu a requisição;
  • targetAppID - targetAppID que se deseja verificar a integração.
  • messages - array de objetos, contendo:
    
    • 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. Caso o código de erro seja omitido, somente o valor do atributo additionalInformation é apresentado como um status de erro. Caso o atributo additionalInformation também não seja enviado, um erro genérico será apresentado. Os códigos de erro podem ser encontrados aqui.
    • text  - Texto do erro padrão
    • additionalInformation - 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.

Fluxo conceitual do processo:

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"AppID" : "PRODUCAO18@PROTHEUS",
		"targetAppID" : "RM@RM",
		"messages" : [{
				"code" : "FI001"
				"text" : "Validado",
				"additionalInformation":""
			}
		]
	}
}

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 Padronizada já existentes nos produtos. Eles tem como originador o Monitor Totvs EAI e tem como destino os serviços de EAI dos aplicativos cadastrados.

Âncora
WsGetStatus WsGetStatus

Verificação de WSDL e autenticação

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.

A URL para obtenção do WSDL será obtida do retorno do serviço apps, no atributo wsdlUrl, e os dados para autenticação serão obtidos do arquivo monitor-url-list.json.

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

Fluxo do serviço:

<?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).

Âncora
Autenticação e recebimento Autenticação e recebimento

Autenticação e recebimento

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

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

A mensagem Padronizada 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. Para Datasul e Logix não existe a necessidade de envio  destes valores.

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.

Fluxo do serviço:

<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 Padronizada 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>

Âncora
simulação simulação

Message Simulation

Este serviço SOAP irá disparar, a partir de um XSD de mensagem padronizada previamente configurado no monitor, uma mensagem para um produto destino.

Um novo evento de mensagem será criado aos já existentes (existentes hoje: upsert e delete ). O novo tipo, simulation, será utilizado para que os adapters não realizem a gravação dos dados e o disparo de algumas regras de negócio, quando não aplicáveis.

As áreas de negócio TOTVS serão as responsáveis por criar os métodos de simulação dentro dos adapters já existentes. Desta maneira, adapters que já existem terão, até serem adequados para este serviço, simulação não disponível.

O monitor deverá ser capaz de prever os retornos de mensagem tanto no formato da Mensagem Padronizada quanto por SoapFault.

Erros de simulação gerados dentro do adapters deverão ser trafegados em formato da Mensagem Padronizada TOTVS.

Alguns códigos de erro podem ser utilizados para o retorno desta mensagem. Os códigos de erro podem ser encontrados aqui.

O monitor irá validar também o retorno da mensagem contra o XSD.

O monitor irá validar somente mensagens síncronas.

Fluxo do serviço:

Exemplo de envio de simulation

<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="2.000">
		<UUID>28b7fad2-7649-cc7d-c197-af60bcbdb85a</UUID>
		<Type>BusinessMessage</Type>
		<Transaction>FINANCIALNATURE</Transaction>
		<StandardVersion>1.000</StandardVersion>
		<SourceApplication>TOTVSMonitor</SourceApplication>
		<CompanyId>18</CompanyId>
		<BranchId>D MG 02 </BranchId>
		<Product name="TOTVSMonitor" version="12"/>
		<GeneratedOn>2016-11-18T20:27:44Z</GeneratedOn>
		<DeliveryType>sync</DeliveryType>
	</MessageInformation>
	<BusinessMessage>
		<BusinessEvent>
			<Entity>FinancialNature</Entity>
			<Event>simulation</Event>
			<Identification>
				<key name="InternalId">18|D MG 02 |VALE00001F</key>
			</Identification>
		</BusinessEvent>
		<BusinessContent>
			<CompanyId>18</CompanyId>
			<BranchId>D MG 02 </BranchId>
			<CompanyInternalId>18|D MG 02 </CompanyInternalId>
			<InternalId>18|D MG 02 |VALE00001F</InternalId>
			<Code>VALE00001F</Code>
			<Description>CREDITO                       </Description>
			<NatureType>Analytical</NatureType>
			<UseCategory>Receivable</UseCategory>
			<Blocked>0</Blocked>
		</BusinessContent>
	</BusinessMessage>
</TOTVSMessage>]]></tot:inMsg>
      </tot:receiveMessage>
   </soapenv:Body>
</soapenv:Envelope>

Tarefas de diagnóstico

O objetivo desta seção é demonstrar como cumprir tarefas de diagnóstico do EAI através dos serviços disponibilizados.  A tarefa é descrita como tópico principal, e os passos para cumpri-la são descritos como subtópicos.

Os seguintes "placeholders" são utilizados nas URLs abaixo:

<URL_monitor_local_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo interno.

<URL_monitor_externo_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.

<URL_EAI_interno_SOAP>: Refere-se à URL base dos serviços EAI que são consumidos no aplicativo interno.

<URL_EAI_externo_SOAP>: Refere-se à URL base dos serviços EAI que são consumidos no aplicativo externo.

<URL_monitor_externo_REST>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.

1. Conectar-se como um aplicativo no monitor
2. Verificar quais empresas/grupo de empresas e filiais estão associadas à aquele aplicativo
   1. GET <URL_monitor_local_REST>/totvseai/monitor/v1/admin/companies?targetAppID=<id_aplicativo_interno>&companyID={companyID}&branchID={branchId}&page={page}&perPage={perPage}, para identificar os aplicativos que fazem integração com o aplicativo interno.
3. Verificar a integridade dos de-para de empresas entre os aplicativos obtidos.
   1. GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/checkmapping/<app_interno>?mappingValue=<empr_interna>|<filial_interna>&mappingID=CompanyBranch
   2. realizar a chamada do método para cada empresa do aplicativo selecionado.
4. Verificar as transações habilitadas no aplicativo interno
   1. GET  <URL_monitor_local_REST>/totvseai/monitor/v1/apps/<app_interno>/transactions?page={page}&perPage={perPage} para buscar as informações dos aplicativos habilitados no aplicativo interno.
5. Verificar a integridade das transações frente ao aplicativo externo

   1. GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/checktransactions/EAI?targetAppID=<App_interno>&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}, verificando, para cada transação, se a mesma está correta na visão do EAI;

      
      

   2. GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/checktransactions/business?targetAppID=<app_interno>&version={version}&supportedMode={supportedMode}&enabledMode={enabledMode}&allowAnonymous={allowAnonymous}&includeOriginalMsg={includeOriginalMsg}, verificando, na camada de negócio, se as transações estão cadastradas de maneira correta.

6. Verificar a integridade da integração, observando o aplicativo como um todo
   1. GET <URL_monitor_externo_REST>/totvseai/monitor/v1/admin/healthcheck/settings?targetAppID={targetAppID}, observando  o retorno do método.
7. Verificar se o serviço de integração está operando corretamente.
   1. GET <URL_EAI_interno_SOAP>, verificando se o serviço de EAI interno está acessível pelo monitor.
   2. GET <URL_EAI_externo_SOAP>, verificando se o serviço de EAI externo está acessível pelo monitor.
   3. GET <URL_EAI_interno_SOAP>/totvseai/monitor/v1/admin/healthcheck/wsintegration/<app_externo>/{companyID}/{branchID}, para verificar se o aplicativo interno consegue se comunicar com o aplicativo externo.
   4. GET <URL_EAI_externo_SOAP>/totvseai/monitor/v1/admin/healthcheck/wsintegration/<app_interno>/{companyID}/{branchID}, para verificar se o aplicativo externo consegue se comunicar com o aplicativo interno.
8. Verificar se é possível autenticar e receber uma mensagem do monitor.
   1. POST <URL_EAI_interno_SOAP>, verificando se o aplicativo interno consegue receber e retornar o post.
   2. POST <URL_EAI_externo_SOAP>, verificando se o aplicativo externo consegue receber e retornar o post.
9. Verificar a simulação da mensagem
   1. POST <URL_EAI_externo_SOAP>, verificando se a mensagem foi processada com sucesso.
10. Verificar se existem mensagens processadas em um aplicativo mas pendentes de envio em outro aplicativo (normalmente por time-out).
    1. Buscar as mensagens com status de notDelivered no aplicativo externo:
       1. GET <URL_EAI_externo_SOAP>/totvseai/monitor/v1/msgs/list?sourceApp={sourceApp}&status=notDelivered
    2. A partir dos UUIDs retornados buscar, no aplicativo interno, as mensagens através:
       1. GET <URL_EAI_interno_SOAP>/ /totvseai/monitor/v1/msgs/{msgUUID}
    3. Apresentar, no monitor, as mensagens com status divergentes entre os sistemas.

Âncora
Codigos de erro Codigos de erro

 Códigos de erro padrão criados para o serviço de diagnóstico.