...

Documentar a estrutura, funcionamento e práticas relacionadas a mensagem padronizada TOTVS utilizando REST como padrão de comunicação e JSON como formato de mensagem.

Estrutura

A partir da estrutura original da mensagem padronizada, baseada em SOAP e XML, temos os 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. Originalmente, a mensagem trafega no formato XML, sobre o protocolo SOAP. Nessa nova proposta, a mensagem estará no formato JSON, trafegando sobre o padrão HTTP/REST.
• Interface: correpondem aos endpoints que permitem o envio e recebimento das mensagens. Enquanto na implementação original, os endpoints são disponibilizados como Web Services SOAP, os endpoints da nova proposta serão disponibilizados como APIs REST, implementados construídos conforme o Guia de Implementação de APIs TOTVS.

Graficamente, a nova proposta pode ser descrita conforme abaixo:

<Inserir gráfico>Image Added

Funcionamento

A dinâmica envolvendo o envio e recebimento de mensagens não se altera com a nova proposta. O que muda, de fato, são o formato da mensagem e a interface.

...

A geração das mensagens continua a cargo 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 continua sendo intermediado pelo Engine de EAI, que determinará qual o adapter responsável por processar a mensagem recebida.

...

Mensagem

A mensagem padronizada, utilizando JSON como formato terá as seguintes características, será composta dos seguintes elementos:

Headerheader: contem informações equivalentes a tag MessageInformation, e algumas mais, conforme segue:

• UUID:
• type
• subType:
• transaction
• version
• sourceApplication
• productName
• productVersion
• generatedOn
• deliveryType

, do formato XML. Os atributos JSON correspondentes seguem as mesmas convenções de obrigatoriedade do padrão original. As tags que não estão descritas aqui, a principio, não serão utilizadas.

• UUID: mesma definição da tag UUID;
• type: mesma definição da tag Type, exceto que não haverá mensagens do tipo Receipt no formato JSON;
• subType: substitui as tags BusinessEvent e BusinessRequest. Os valores esperados para o atributo subType são event e request;
• transaction: mesma definição da tag Transaction;
• version: corresponde ao atributo version da tag MessageInformation, ou seja, indica a versão da transação;
• sourceApplication: mesma definição da tag SourceApplication;
• productName: corresponde ao atributo name da tag Product: indica o nome do produto origem da mensagem (PROTHEUS, DATASUL, RM, LOGIX, etc.);
• productVersion: corresponde ao atributo version da tag Product: indica a versão do produto origem;
• generatedOn: mesma definição da tag GeneratedOn;
• deliveryType: mesma definição da tag DeliveryType.

contentContent: contem informações equivalentes a tag BusinessContent, para mensagens de negócio, ou a tag ReturnContent, para 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á a seguinte estrutura:

• receivedMessage: conterá dados relativos à mensagem original, como o UUID e o aplicativo de origem (sentBy).
• processingInformation: conterá dados relativos ao processamento da mensagem original, como o status geral do processamento, a data de processamento, e eventuais mensagens de erro.
• returnContent: conterá o resultado do processamento da mensagem original. Sempre deve retornar , conforme definido para a transação. Além disso, pode conter também o atributo listOfInternalId, o qual conterá todos os internalIds relacionados a mensagem. internal Ids relacionados a mensagem. A estrutura corresponde ao internal ID terá os seguintes atributos:
  • name: mesma definição da tag Name;
  • origin: mesma definição da tag Origin;
  • destination: mesma definição da tag Destination.

Uma mensagem da transação CostCenter, versão 2.000, seria expressa da seguinte forma, usando o formato JSON proposto:

{
    "header" : {
        "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
        "type" : "BusinessMessage",
        "subType" : "event",
        "transaction" : "CostCenter",
        "version" : "2.000",
        "sourceApplication": "P1299",
        "productName" : "PROTHEUS",
        "productVersion" : "12.1.17",
        "companyId" : "99",
        "branchId" : "01",
        "generatedOn" : "2017-11-14T11:47:00-03:00",
        "deliveryType" : "async",
    },
    "content" : {
        "CompanyId" : "",
        "BranchId" : "",
		"CompanyInternalId" : "",
		"Code" : "",
		"InternalId" : "",
		"RegisterSituation" : "",
        "Name" : "",
		"ShortCode" : "",
		"SPED" : "",
		"Class" : ""
    }
}

A mensagem de resposta correspondente seria semelhante ao exemplo abaixo:

{
    "header" : {
        "UUID" : "",
        "type" : "Response",
        "subType" : "",
        "transaction" : "",
        "version" : "",
        "sourceApplication" : "",
        "productName" : "",
        "productVersion" : "",
        "generatedOn" : "",
        "deliveryType": ""
    },
    "content" : {
        "receivedMessage" : {
            "UUID" : "<originalMsgUUID>",
            "SentBy" : "<sourceApplication>",
            "event" : "upsert|delete"        
        },
        "processingInformation" : {
            "processedOn" : "",
            "status" : "OK|ERROR|WARNING",
            "details" : [
                {
                    "code" : "",
                    "message" : "",
                    "detailedMessage" : "",
                    "helpUrl" : "http://<serverName>"  // Opcional
                },
                {
                    "code" : "",
                    "message" : "",
                    "detailedMessage" : "",
                    "helpUrl" : "http://<serverName>"  // Opcional
                }
            ]
        },
        "returnContent" : {
            "atributo1" : "",
            "atributo2" : "",
            "listOfInternalID" : [   // Opcional em caso de resposta de requests
                {
                    "name" : "InternalIdName",
                    "origin" : "",
                    "destination" : ""
                },
                {
                    "name" : "InternalIdName",
                    "origin" : "",
                    "destination" : ""
                }
            ]
        }
    }
}

Interface

As mensagens padronizadas em formato JSON serão recebidas por um endpoint padrão, conforme descrito abaixo:

...