Estrutura

A comunicação através do protocolo transaction (EAI) possui uma estrutura composta dos seguintes elementos:

Emissor/Receptor: correspondem aos aplicativos (ERPs) dos quais se origina (emissor) e para os quais se destina (receptor) a mensagem.
Mensagem: corresponde ao conteúdo que trafega entre o emissor e o receptor.
Interface: correspondem aos endpoints REST (/totvseai/standardmessage/v1/transactions), webservices SOAP, ou filas AMQP que permitem o envio e recebimento das mensagens.

O canal em que essa comunicação acontece pode ser algum dos seguintes:

REST
AMQP
SOAP (Legado)

Graficamente, a estrutura pode ser descrita conforme abaixo:

Frameworksp > 2. Definindo uma integração via transaction > image2017-11-14_10-14-4.png

Funcionamento

Os modos de operação podem ser: síncrono e assíncrono, sendo que neste último temos a necessidade de uma fila e de um agente que se responsabilize por sua gestão (processador de fila).

A geração das mensagens é responsabilidade dos adapters, que entregam para a Engine do EAI a estrutura de dados necessária para gerar a mensagem no padrão TOTVS. Da mesma, forma o recebimento das mensagens é intermediada pelo Engine de EAI, que determinará qual o adapter responsável por processar a mensagem recebida.

O uso do InternalId é obrigatório nesse modelo.

Clique aqui para saber mais sobre internalId

Mensagem

A mensagem padronizada, utilizada através de transactions (EAI), é composta dos elementos Header e Content.

Header: contem informações sobre a mensagem sendo trafegada, como seu identificador único, data em que foi gerada, transação ao qual se refere, entre outras.

UUID: Identificador único desta mensagem e que não pode ser igual ao UUID de qualquer outra mensagem em qualquer um dos aplicativos participantes da integração.
Type: Identifica o tipo da mensagem (BusinessMessage, ReceiptMessage ou ResponseMessage).
SubType: Os valores esperados para o atributo subType são event e request;
Event: quando SubType é event, este atributo conterá os valores upsert ou delete, para indicar que a mensagem corresponde a uma inclusão/alteração ou a uma eliminação, respectivamente. Ele não é utilizado quando o SubType é request.
Transaction: identificador do tipo de transação da mensagem. Esta informação será utilizada pelos aplicativos para definir como os dados serão processados no recebimento.
Version: Identifica qual a versão daquela mensagem de negócio. Uma mensagem de Item, por exemplo, pode sofrer alterações no decorrer do tempo, sendo que cada uma destas alterações irá afetar esta informação.
SourceApplication: Identifica a instancia dos aplicativos TOTVS que gerou a mensagem. Uma instância representa uma instalação/configuração daquele aplicativo/produto. Caso duas instancia do mesmo aplicativo participem da mesma integração, cada um deverá ser identificado de forma única.
ProductName: Identifica o produto e versão que originou a mensagem. Neste caso, o valor pode ser o igual, mesmo em instâncias diferentes do mesmo aplicativo.
ProductVersion: indica a versão do produto origem;
GeneratedOn: Identifica o timestamp de geração desta mensagem.
DeliveryType: Forma de envio da mensagem, podendo ser sync ou async, ou seja, síncrono ou assíncrono.

Content: contem informações da mensagens de negócio, ou mensagens de resposta. Devido a isso, os atributos podem variar de acordo com a definição da transação.

Quando a mensagem for de resposta, o atributo Content terá ainda os seguintes atributos:

ReceivedMessage:
ProcessingInformation: Contém atributo Details, que por sua vez, contém as mensagens referentes ao processamento da mensagem original. Elas estarão estruturadas conforme definido no Guia de Implementação de APIs TOTVS, item Mensagens de erro, com a ressalva de que os atributos utilizaram a forma capitalizada, em vez do formato "camelCase", ou seja, em vez de "code", é usado "Code", por exemplo.
ReturnContent: Contém o resultado do processamento da mensagem original, conforme definido para a transação. Além disso, pode conter também o atributo ListOfInternalId, onde constam todos os internalIDs relacionados a mensagem. A estrutura correspondente ao internal ID tém os seguintes atributos:
- Name: nome da entidade correspondente ao valor sendo trafegado. Exemplo: "CustomerVendor", "Item", "SalesOrder";
- Origin: mesma definição da tag Origin;
- Destination: mesma definição da tag Destination.

Tipos de Mensagens

O padrão de mensagem TOTVS através do protocolo transactions (EAI) estabelece três tipos de mensagens: BusinessMessage, ResponseMessage e ReceiptMessage.

BusinessMessage

Uma mensagem do tipo BusinessMessage são aquelas que iniciam qualquer processo de troca de mensagens entre os aplicativos. Sempre que um aplicativo A quiser enviar ou solicitar informações do aplicativo B, ele enviará uma BusinessMessage que será processada pelo aplicativo destinatário.

As BusinessMessages podem assumir dois tipos:

Event: As mensagens de evento são aquelas cujo objetivo é notificar outros aplicativos da ocorrência de um evento. Estas mensagens são normalmente utilizadas para fins de replicação de dados, quando um dos aplicativos (cadastro master) envia para os demais (slaves) sobre a inclusão, alteração ou eliminação de um registro.
Request: As mensagens de solicitação são utilizadas para consumir um serviço de um aplicativo remoto. Pode ser entendido por serviço qualquer processamento feito pelo aplicativo chamado com base nas informações passadas pelo aplicativo chamador. As mensagens de request são normalmente enviadas por aplicativos-clientes aos aplicativos-servidores para iniciar um processamento (como a consulta do saldo de um item, por exemplo).

A tabela abaixo apresenta um comparativo entre mensagens de evento e de solicitação:

	Event	Request
Objetivo	Replicação de Dados	Compartilhar Lógicas
Quem Gera (normalmente)	Um (cadastro Master)	Vários (clientes que precisam da lógica)
Quem Responde (normalmente)	Vários (cadastros replicados)	Um (detentor da lógica)
Uso + comum	Síncrono (Envia e aguarda)	Assíncrono (envia e esquece)
Exemplo	Upsert UnitOfMeasure	getCashAvailableOnDate

BusinessMessage – Event

As mensagens de eventos de negócio basicamente descrevem o evento ocorrido, como no exemplo abaixo:

{
    "Header": {
        "UUID": "6c7b9b15-6126-972e-aad8-8f64edcf637a",
        "Type": "BusinessMessage",
        "SubType": "event",
		"Event": "upsert"
        "Transaction": "UNITOFMEASURE",
        "StandardVersion": "1.000",
        "SourceApplication": "RM_TS",
        "CompanyId": "1",
        "BranchId": "1",
        "GeneratedOn": "2019-01-18T11:54:40Z",
        "DeliveryType": "Async",
        "Version": "2.002",
        "ProductName": "RM",
        "ProductVersion": "12.1.23.0"
    },
    "Content": {
        "Code": "QS",
        "InternalId": "18|D MG|QS",
        "Description": "QS"
    }
}

Onde:

Event: Qual foi o evento associado à mensagem (pode ser upsert – inclusão/alteração – ou delete – eliminação).
Content: JSON com informações sobre o evento, normalmente contendo todas as informações pertinentes àquela entidade.

BusinessMessage – Request

As mensagens de request descrevem qual função se deseja executar e os parâmetros necessários, como no exemplo abaixo:

{
	"Header": {
		"UUID": "c18535da-75b8-4925-9e32-b6445d4f2927",
		"Type": "BusinessMessage",
		"SubType": "request",
		"Transaction": "AccountsReceivableOffsetting",
		"StandardVersion": "1.000",
		"SourceApplication": "RM",
		"CompanyId": "2",
		"BranchId": "2",
		"GeneratedOn": "2016-06-21T19:41:21",
		"DeliveryType": "Sync",
		"Version": "2.000",
		"ProductName": "RM",
		"ProductVersion": "11.83.55"
	},
	"Content": {
		"CompanyInternalId": "CompanyInternalId1",
		"CompanyId": "CompanyId1",
		"BranchId": "BranchId1",
		"InternalId": "InternalId1",
		"AccountReceivableDocumentInternalId": "AccountReceivableDocumentInternalId1",
		"AdvanceInternalId": "AdvanceInternalId1",
		"OffsettingDate": "1900-01-01T00:00:00",
		"HistoryText": "HistoryText1",
		"OffsettingValue": 1.0
	}
}

Onde:

Content: contem JSON com informações necessárias para o processamento, normalmente parâmetros de entrada.

Uma BusinessMessage, seja do tipo Event quanto do tipo Request, tem seu atributo Content definido no schema da mensagem padronizada TOTVS. Conforme pode ser visto nesta página, deve-se indicar, através do atributo x-totvs na seção info do schema qual modelo será utilizado para definir o atributo Content (transactionDefinition/BusinessContentType).

ResponseMessage

Uma ResponseMessage representa o resultado do processamento de uma BusinessMessage pelo aplicativo que a recebeu e o seu conteúdo pode variar de acordo com o tipo de mensagem e com o resultado do processamento.

Todas as respostas geradas por uma BusinessMessage devem ser associadas à mensagem original e mantidas pelo aplicativo-origem, como forma de rastrear quem processou aquela mensagem e qual o resultado do processamento.

A mensagem de resposta contém informações sobre o resultado do processamento de uma BusinessMessage.

Exemplo de um JSON de resposta de processamento sem erros

{
    "Header" : {
        "UUID" : "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
        "Type" : "Response",
        "SubType" : "event",
        "Transaction" : "CostCenter",
        "Version" : "2.000",
        "SourceApplication" : "LGX12",
        "ProductName" : "LOGIX",
        "ProductVersion" : "12.1.15",
        "GeneratedOn" : "2017-11-14T11:47:15-03:00",
        "DeliveryType": "async"
    },
    "Content" : {
        "ReceivedMessage" : {
            "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
            "SentBy" : "P1299",
            "Event" : "upsert"       
        },
        "ProcessingInformation" : {
            "ProcessedOn" : "2017-11-14T11:47:15-03:00",
            "Status" : "Ok"           
        },
        "ReturnContent" : {           
            "ListOfInternalID" : [
                {
                    "Name" : "BankInternalId",
                    "Origin" : "01|99|123",
                    "Destination" : "01|99|abc"
                }
            ]
        }
    }
}

Onde:

ReceivedMessage: Segmento com informações sobre a mensagem original (BusinessMessage) que deu origem a esta resposta.
- SentBy: Indica qual foi a instancia que gerou a mensagem original
- UUID: Identificador universal da mensagem de origem
- Event: Qual foi o evento associado à mensagem (pode ser upsert – inclusão/alteração – ou delete – eliminação).
ProcessingInformation: Segmento com informações sobre o resultado do processamento
- ProcessedOn: Timestamp de quando a mensagem foi processada pelo destino
- Status: Situação final do processamento (ok ou error)
- Details: Lista de mensagens (erro ou aviso) retornadas no processamento.
ReturnContent: JSON com as informações de negócio retornadas no processamento

Da mesma forma que o atributo Content de uma BusinessMessage, o atributo ReturnContent de uma ResponseMessage é definido no schema da mensagem padronizada. De acordo com a documentação sobre schemas, na atributo x-totvs da seção info deve ser referenciado o modelo que definirá o ReturnContent (transactionDefinition/ReturnContentType).

Exemplo de um JSON de resposta de processamento com erros:

{
	"Header": {
		"UUID": "25121218-a5c8-e581-b010-0a139a59f4bf",
		"Type": "Response",
		"SubType": "event",
		"Transaction": "Bank",
		"StandardVersion": "1.0",
		"SourceApplication": "Logix",
		"GeneratedOn": "2001-12-31T12:00:00",
		"Version": "1.000",
		"ProductName": "LOGIX",
		"ProductVersion": "12.1.19"
	},
	"Content": {
		"ReceivedMessage": {
			"SentBy": "dts11",
			"UUID": "24121218-a5c8-e581-b010-0a139a59f4bf",
			"Event": "upsert"
		},
		"ProcessingInformation": {
			"ProcessedOn": "2001-12-31T12:00:00",
			"Status": "error",
			"Details": [{
					"Type": "warning",
					"Code": "254",
					"Message": "Messagem de Aviso"
				}, {
					"Type": "error",
					"Code": "-25",
					"Message": "Messagem de erro"
				}, {
					"Type": "error",
					"Code": "EAI30",
					"Message": "Mensagem de Teste3"
				}
			]
		}
	}
}

Obs: Consultar Catalogo de Erros

ReceiptMessage

Uma ReceiptMessage representa a confirmação de recebimento de uma BusinessMessage pelo aplicativo destino.

Diferente da ResponseMessage, uma ReceiptMessage não irá conter qualquer informação relevante sobre o processamento da mensagem, uma vez que se entende que, se o aplicativo destino retornou um Receipt, ele não processou a mensagem naquele momento (comunicação assíncrona).

Quando a mensagem for processada pelo aplicativo-destino, uma mensagem de resposta (ResponseMessage) será gerada e encaminhada ao aplicativo que originou a BusinessMessage.

As informações contidas nas mensagens de recibo são genéricas e focam especificamente nos dados de recebimento da mensagem.

Onde:

ReceivedMessage: Segmento com informações sobre a mensagem original (BusinessMessage) que deu origem a esta resposta.
- SentBy: Indica qual foi a instancia que gerou a mensagem original
- UUID: Identificador universal da mensagem de origem
ReceiptData: Segmento com informações sobre o recebimento da mensagem
- - ReceivedOn: Timestamp do recebimento da mensagem.

Quando uma BusinessMessage é recebida e for síncrona, ela deverá ser processada imediatamente e gerará como resposta uma ResponseMessage.

Quando uma BusinessMessage é recebida e for assíncrona, será gerada como resposta, no momento da recepção uma ReceiptMessage, e posteriormente quando for processada será enviada uma ResponseMessage para esta mensagem.