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

Graficamente, a nova proposta pode ser descrita conforme abaixo:

<Inserir gráfico>

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á o adapter responsável por processar a mensagem recebida.

Definições da nova proposta

Mensagem

A mensagem padronizada utilizando JSON como formato terá as seguintes características:

Header: contem informações equivalentes a tag MessageInformation, entre elas:

• UUID
• Type
• Transaction
• StandardVersion
• SourceApplication
• ProductName
• ProductVersion
• GeneratedOn
• 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.

Interface

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

/totvseai/standardmessage/v1/receive/{transactionID}

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

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

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.