Objetivo

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, construídos conforme o Guia de Implementação de APIs TOTVS.

Graficamente, a nova proposta pode ser descrita conforme abaixo:

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.

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

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.

Definições da nova proposta

Mensagem

A mensagem padronizada, utilizando JSON como formato, será composta dos seguintes elementos:

header: contem informações equivalentes a tag MessageInformation, 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.

content: 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: equivalente à tag ReceivedMessage, da mensagem de resposta no padrão SOAP, exceto pela tag filha MessageContent, que não será mais utilizada;
• processingInformation: equivalente à tag ProcessingInformation, do padrão SOAP, exceto pela tag filha ListOfMessages, que foi substituída pelo atributo details, que por sua vez, conterá as mensagens referentes ao processamento da mensagem original, seguindo a estrutura definida no Guia de Implementação de APIs TOTVS, item Mensagens de erro.
• returnContent: conterá o resultado do processamento da mensagem original, conforme definido para a transação. Além disso, pode conter também o atributo listOfInternalId, o qual conterá todos os internal Ids relacionados a mensagem. A estrutura corresponde ao internal ID terá os seguintes atributos:
  • name: mesma definição da tag do padrão SOAP 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" : "99",
        "BranchId" : "01",
		"CompanyInternalId" : "99",
		"Code" : "ABC001",
		"InternalId" : "99|ABC001",
		"RegisterSituation" : "Active",
        "Name" : "Centro de Custo ABC001",
		"ShortCode" : "ABC001",
		"SPED" : true,
		"Class" : 2
    }
}

A mensagem de resposta correspondente seria semelhante ao exemplo abaixo:

{
    "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" : "ERROR",
            "details" : [
                {
                    "code" : "FE001",
                    "message" : "Mensagem padrão no formato incorreto.",
                    "detailedMessage" : ""
                },
                {
                    "code" : "AE004",
                    "message" : "Empresa não configurada para integração.",
                    "detailedMessage" : ""
                }
            ]
        },
        "returnContent" : {            
            "listOfInternalID" : [
                {
                    "name" : "CostCenter",
                    "origin" : "99|ABC001",
                    "destination" : "10|1000"
                },
                {
                    "name" : "Company",
                    "origin" : "99",
                    "destination" : "10"
                }
            ]
        }
    }
}

A nova proposta fornece também um modelo para lote de mensagens, que corresponde a um array JSON, onde cada elemento corresponde a uma mensagem no formato JSON.

{
    "items" : [
        {
            "header" : {
                "UUID" : "",
                "type" : "",
                "subType" : "",
                "transaction" : "customerVendor",
                "version" : "2.001",
                "sourceApplication": "",
                "productName" : "",
                "productVersion" : "",
                "generatedOn" : "",
                "deliveryType" : "async",
            },
            "content" : {
                "atributo1" : "",
                "atributo2" : "",
                ...
                "atributoN" : ""
            }
        },{
            "header" : {
                "UUID" : "",
                ...
                "transaction" : "item",
                "version" : "3.001",
                ...
                "deliveryType" : "async" 
            },
            "content" : {
                "atributo1" : "",
                "atributo2" : "",
                ...
                "atributoN" : ""
            }
        }
    ]
}

O lote de mensagens tem algumas características importantes:

• É válido somente para mensagens assíncronas. Caso uma das mensagens presentes no lote tenha o atributo DeliveryType igual a "sync", todo o lote deve ser rejeitado.
• Pode conter mensagens de uma mesma transação e versão, ou mensagens de transações/versões distintas.
• A forma como o lote deve ser tratado quanto a sua integridade é determinada pelo parâmetro batchType, informado na requisição. Mais detalhes serão fornecidos na seção a seguir.

Interface

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

/totvseai/standardmessage/v1

Neste endpoint estarão disponíveis dois predicados ou entidades:

• /transactions: utilizado para receber mensagens que devem ser gerenciadas pelo Engine de EAI. As mensagens recebidas desta forma terão identificador único e podem ser encaminhadas para uma fila, quando o modo de operação for assíncrono. É o equivalente à operação SOAP receiveMessage do padrão original.
• /contents: utilizado para receber mensagens onde apenas o conteúdo é relevante, e não há necessidade de maiores controles. Neste endpoint, o modo de operação será exclusivamente síncrono.

Predicado /transactions

URL completa: /totvseai/standardmessage/v1/transactions?batchType={batchType}.

• batchType: indica como deve ser tratado o lote de mensagens recebido, se for aplicável. Permite os seguintes valores:
  
  • businessTransaction: indica que o lote será tratado como uma transação de negócio, onde todas as mensagens compondo o lote devem ser processadas com sucesso, para que o lote seja considerado processado. Se ocorrer erro em alguma mensagem do lote, todo o lote sera recusado.
  • simpleBatch: indica que o lote serve apenas como agrupador de mensagens, que serão processadas independentemente. Se ocorrer erro em alguma mensagem do lote, isso não afeta as demais mensagens. Neste caso, o lote sempre será considerado processado.

Os métodos HTTP previstos para o endpoint são:

• POST: para mensagens de requisição (request), ou mensagem de inclusão/alteração (event). Corresponde às mensagens XML contendo a tag BusinessRequest, ou tag BusinessEvent com Event igual a "upsert".
• DELETE: para mensagens de eliminação (delete). Corresponde as mensagens XML contendo a tag BusinessEvent, com Event igual a "delete".

Exemplos de utilização deste endpoint podem ser encontrados nesta página.

Predicado /contents

URL completa: /totvseai/standardmessage/v1/contents/{transactionID_version}/{internalID}.

• transactionID_version: identificador que designa a transação e versão a ser considerada;
• internalID: identificador da instância da entidade indicada pela transação e versão informados no parâmetro anterior. Por exemplo: quando a transação e versão for "customervendor_1_000", o parâmetro internalID deve conter um valor que identifique um registro de cliente/fornecedor no originador da requisição. Consequentemente, no recebedor da requisição, será necessário uma estrutura de tradução - de-para - que permita identificar o registro equivalente no destino.

Os métodos previstos são:

• GET: para recuperar entidades.
• POST: para incluir ou alterar entidades.
• DELETE: para eliminar entidades.

Formato de mensagem

O formato de mensagem utilizado nas requisições para o endpoint /contents é mais simples, já que não requer as informações de cabeçalho para realizar o controle da mensagem. A proposta do modelo é apenas utilizar-se do modelo de mensagem padronizada para trafegar informações entre as partes.

Na prática, o modelo de dados que será trafegado nas requisições corresponde ao atributo content do modelo completo, usado pelo endpoint /transactions.

Exemplos de utilização deste endpoint podem ser vistos aqui.

Coexistência com o formato XML/SOAP

No período de migração das implementações em XML para JSON, será necessário que os formatos convivam simultaneamente e sejam interoperáveis. Assim que todos os ERPs forem capazes de trabalhar com a nova proposta, o formato XML e os endpoints SOAP poderão ser desativados.

Elaboração da mensagem padronizada

O desenho de uma transação, na nova proposta, utilizará o formato Swagger/OpenAPI, em substituição ao formato XML Schema, utilizado na implementação original.