Histórico da Página

...

Veja abaixo um exemplo do JSON de uma mensagem padronizada completa (incluindo header para controle da camada de EAI):

Clique aqui para obter mais informações sobre integração via transactions (EAI)

No caso de JSON simplificado para API, trabalhamos apenas com o contéudo da propriedade "content", desconsiderando o header.

...

Bloco de código

language	js
title	Mensagem Padronizada API

{
    "CompanyId": "1",
    "BranchId": "B1",
    "CompanyInternalId": "CompanyInternalId",
    "InternalId": "InternalId",
    "Code": "Code",
    "Description": "Description",
    "NatureType": "NatureType",
    "UseCategory": "UseCategory",
    "Blocked": 0    
}

Exemplo de um JSON de resposta de processamento sem erros (Através da camada de EAI):

Bloco de código

language	js
title	Mensagem do Tipo Response (EAI)
linenumbers	true

{
    "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"
                }
            ]
        }
    }
}

Exemplo de um JSON de resposta de processamento com erros:

Bloco de código

language	xml
title	Response com Erro
linenumbers	true

{
	"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"
				}
			]
		}
	}
}

...

As mensagens TOTVS possuem um segmento chamado MessageInformation que possui as principais informações utilizadas para identificação e roteamento da mensagem. Exemplo:

Image Removed

Onde:

MessageInformation 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.
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).
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.
StandardVersion: Identifica a versão do padrão TOTVS, ou seja, do formato utilizado nas áreas genéricas da mensagem TOTVS. Caso o padrão TOTVS seja alterado, este valor será alterado.
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.
CompanyId/BranchId/UserId: Identificador da empresa/filial e usuário que gerou a mensagem. Esta informação é apenas documental e não deve ser utilizada para o processamento da mensagem já que não existe garantia da sua existência na mensagem. Quando a informação for relevante para o negócio, é preciso buscar esta informação do conteúdo da mensagem de negócio.
Product: 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.
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.

Tipos de Mensagens

O padrão de mensagem TOTVS estabelece quatro 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:

...

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:

Image Removed

Onde:

Entity: Identifica qual foi a entidade de negócio que sofreu o evento
Event: Qual foi o evento associado à mensagem (pode ser upsert – inclusão/alteração – ou delete – eliminação).
Identification/Keys: Campos-chave para identificação do registro impactado pela alteração
BusinessContent: XML 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:

Image Removed

Onde:

Operation: Identifica qual a operação que se deseja executar
BusinessContent: XML com informações necessárias para o processamento, normalmente parâmetros de entrada

...

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, como no exemplo abaixo:

Bloco de código

language	xml
title	ResponseMessage
linenumbers	true

<ResponseMessage>
	<ReceivedMessage>
		<SentBy>PROTHEUS</SentBy>
		<UUID>25121218-a5c8-e581-b010-0a139a59f4bf</UUID>
		<Event>upsert</Event>
		<MessageContent>
			<![CDATA[
			... mensagem original...
			]]>
		</MessageContent>
	</ReceivedMessage>
	<ProcessingInformation>
		<ProcessedOn>2011-06-23T17:04:16</ProcessedOn>
		<Status>error</Status>
		<ListOfMessages>
			<Message type="warning" code="254">Mensagem de aviso</Message>
			<Message type="error"   code="-25">Mensagem de erro</Message>
			<Message type="error"   code="EAI30">Mensagem de Teste3</Message>
		</ListOfMessages>
	</ProcessingInformation>
	<ReturnContent>
		...
	</ReturnContent>
</ResponseMessage>

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).
- MessageContent: XML da mensagem original (opcional).
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)
- ListOfMessages: Lista de mensagens (erro ou aviso) retornadas no processamento.
ReturnContent: XML com as informações de negócio retornadas no processamento

Obs: Consultar Catalogo de Erros

...

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.

Image Removed

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
- MessageContent: XML da mensagem original (opcional).
ReceiptData: Segmento com informações sobre o recebimento da mensagem
- - ReceivedOn: Timestamp do recebimento da mensagem.

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

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

Exemplo(s)

Explicar regras de propriedades a partir do(s) exemplo(s)Clique aqui para obter mais informações sobre integração via API

Atalhos

Páginas filhas

Versões comparadas

Versão antiga 11

Nova versão 12

Chave

Tipos de Mensagens

BusinessMessage

BusinessMessage – Event

BusinessMessage – Request