Objetivo

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

Estrutura

Semelhante ao que se tem na mensagem padronizada, baseada em SOAP e XML, a 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. Na nova proposta, a mensagem estará no formato JSON, trafegando sobre o padrão HTTP/REST.
• Interface: correspondem 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 estrutura 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.

Considerando a crescente implementação de APIs nos produtos TOTVS e visando a definição de um glossário único na troca de dados entre os participantes de uma integração, estabeleceu-se a obrigatoriedade da mensagem padronizada nos seguintes contextos:

• Server-to-server: neste contexto a mensagem padronizada já está estabelecida como o único padrão de comunicação entre os produtos TOTVS e corresponde às integrações que vem sendo construídas ao longo dos anos. A troca de informações abrangidas pelo contexto server-to-server visam, principalmente, a sincronização de dados entre dois ou mais participantes de uma integração e, na maior parte das vezes, requer mecanismos de equivalência de chaves primárias e estrangeiras, como o uso do InternalId.
• Client-to-server: este contexto corresponde ao uso das APIs TOTVS por aplicações internas e de terceiros, onde o cliente depende exclusivamente dos dados providos pelo servidor, que geralmente é um ERP TOTVS. O cliente não necessita de mecanismos de equivalência de chaves (InternalId), pois utilizará aquelas providas pelo servidor. Neste contexto, a mensagem padronizada atua como um "dicionário de dados" padrão para todas as APIs que realizam as operações e requisições nas entidades mantidas pelo servidor.

Em função do exposto acima, a definição e uso de InternalId nas transações deve seguir esta orientação:

• A definição do InternalId é obrigatória no modelo da transação, seja em XML Schema, seja em modelo OpenAPI (Swagger). Ou seja os atributos correspondentes ao InternalId devem ser modelados, mesmo que, inicialmente, o contexto de uso seja apenas client-to-server. O motivo é manter a consistência do modelo de dados, quando, futuramente, for utilizado no outro contexto.
• O uso (preenchimento) do InternalId é obrigatório no contexto server-to-server e opcional no contexto client-to-server.

Definições

Mensagem

A mensagem padronizada, utilizando JSON como formato, será 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. São dados 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: tem objetivo similar às 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. Entretanto, os atributos modelados para preencher o atributo Content, que corresponde ao contexto de uso server-to-server, devem ser os mesmos no contexto de uso client-to-server.

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

• 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. Elas estarão estruturadas conforme definido 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, onde constará todos os internalIDs relacionados a mensagem. A estrutura correspondente ao internal ID terá 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.

Exemplos de Mensagem - contexto server-to-server

Uma mensagem da transação CostCenter, na versão 2.000, no contexto de uso server-to-server, seria expressa da seguinte forma, usando o formato JSON:

{
    "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" : "Ok"            
        },
        "ReturnContent" : {            
            "ListOfInternalID" : [
                {
                    "Name" : "CostCenter",
                    "Origin" : "99|ABC001",
                    "Destination" : "10|1000"
                },
                {
                    "Name" : "Company",
                    "Origin" : "99",
                    "Destination" : "10"
                }
            ]
        }
    }
}

O padrão REST/JSON fornece também um modelo para lote de mensagens, onde as mensagens são agrupadas em um array JSON, de nome items.

{
    "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 uso do formato de lote de mensagens tem algumas considerações 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.
• Um lote pode ser tratado como um simples agrupador de mensagens sem relação entre si, ou um lote transacional, onde as mensagens são interdependentes, representando uma única transação de negócio. Veja a descrição do parâmetro batchType, do predicado /transactions na seção a seguir, para mais informações.
• Geração e envio do UUID pela origem é obrigatória. Veja a descrição do parâmetro batchUUID, do predicado /transactions na seção a seguir, para mais informações.

Exemplos de mensagem - contexto client-to-server

A transação CostCenter, versão 2.000, no contexto de uso client-to-server, seria representada em JSON conforme segue:

{
        "CompanyId" : "99",
        "BranchId" : "01",
		"Code" : "ABC001",
		"RegisterSituation" : "Active",
        "Name" : "Centro de Custo ABC001",
		"ShortCode" : "ABC001",
		"SPED" : true,
		"Class" : 2
    }

Observe que os campos relativos a InternalId não estão presentes, por serem opcionais neste contexto de uso.

Interface

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

/totvseai/standardmessage/v1/{resource}

No endpoint, v1 corresponde à versão do padrão de mensagem, que pode evoluir. A versão será alterada, quando necessário, conforme o Guia de Implementação de APIs.

Em resource, pode-se informar as seguintes opções:

• transactions: utilizado para receber mensagens que devem ser gerenciadas pelo Engine de EAI. As mensagens recebidas neste predicado devem ter, obrigatoriamente, um identificador único (UUID) e podem ser encaminhadas para uma fila, quando o modo de operação for assíncrono. É o equivalente à operação receiveMessage do padrão SOAP/XML.
  
  

Predicado /transactions

Onde:

• 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 será 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.
• batchUUID UUID gerado pela origem que ira ser a referencia do lote, esta informação é obrigatória quando for lote, mesmo o batchType ser implícito.

Os métodos HTTP previstos são:

• POST: para receber 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 às mensagens XML contendo a tag BusinessEvent, com Event igual a "delete".

Exemplos de utilização

Exemplos de utilização deste predicado podem ser encontrados nos links a seguir:

• Submeter mensagem de inclusão/alteração em lote;
• Submeter uma mensagem de inclusão/alteração;
• Submeter uma mensagem de eliminação;
• Submeter um lote de mensagens de eliminação.

Coexistência com o formato XML

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.

Para permitir a utilização dos adapters atuais, sem que seja necessário convertê-los de imediato para o formato JSON, está disponível um conversor de XML para JSON e vice-versa, implementado no formato de DLL. Para mais informações, consulte a documentação correspondente.

Para apoiar na migração de adapters do formato XML para o formato JSON, foi desenvolvido o documento Equivalência entre formatos, o qual possui orientações importantes para este processo.

Modelagem de transações

O desenho de uma transação, no formato REST/JSON, deve utilizar o formato OpenAPI (anteriormente chamado Swagger), versão 3.0 em diante, em substituição ao formato XML Schema, utilizado na implementação SOAP/XML. Para mais informações sobre como implementar um documento Swagger, consulte a especificação própria do padrão.

Para a documentação da transação no arquivo de definição OpenAPI, há regras para a mensagem e para os campos, conforme abaixo:

• 1 - Definições para Mensagem padronizada;
• 2 - Definições para campos.

Modelagem do InternalId

Conforme descrito no item Funcionamento deste documento, os atributos relativos ao InternalId devem ser modelados, independentemente do contexto de uso.

O exemplo a seguir mostra a modelagem da transação CostCenter, versão 2.000, usando o padrão OpenAPI (Swagger), considerando a obrigatoriedade da definição de InternalIds, mas não o seu uso. Ou seja, os campos de InternalId não são marcados como requeridos.

openapi: 3.0.0
info:
  description: Centro de Custo
  version: '2.000'
  title: CostCenter
  contact:
    name: T-Talk
paths: {}
servers:
  - url: 'http://api.totvs.com.br/'
components:
  schemas:
    CostCenter:
      type: object
      required:
        - Code
        - Name
        - ShortCode
      properties:
        CompanyId:
          type: string
          description: Código da empresa
        BranchId:
          type: string
          description: Código da filial/estabelecimento/coligada
        CompanyInternalId:
          type: string
          description: InternalId da empresa
        Code:
          type: string
          description: Código do centro de custo
        InternalId:
          type: string
          description: InternalId do centro de custo
        RegisterSituation:
          type: string
          description: Indica se o centro de custo está ativo ou não.
          enum:
            - Active
            - Inactive
        Name:
          type: string
          description: Descrição do centro de custo
        ShortCode:
          type: string
          description: Descrição breve do centro de custo
        SPED:
          type: boolean
        Class:
          type: number