...

Estrutura

A partir da estrutura original da Semelhante ao que se tem na mensagem padronizada, baseada em SOAP e XML, temos os 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. Originalmente, a mensagem trafega no formato XML, sobre o protocolo SOAP. Nessa Na nova proposta, a mensagem estará no formato JSON, trafegando sobre o padrão HTTP/REST.
• Interface: correpondem 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 nova proposta estrutura pode ser descrita conforme abaixo:

...

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

...

Mensagem

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

...

• 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 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. Quando a mensagem for de resposta, o atributo content terá a seguinte estruturaainda 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, seguindo a estrutura definida . 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, o qual conterá onde constará todos os internal IdsIDs relacionados a mensagem. A estrutura corresponde correspondente 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.

...

Exemplos

Uma mensagem da transação CostCenter, na 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
    }
}

...

{
    "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 O padrão REST/JSON fornece também um modelo para lote de mensagens, que corresponde a onde as mensagens são agrupadas em um array JSON, onde cada elemento corresponde a uma mensagem no formato 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 características 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.
• A forma como o lote deve ser tratado quanto a sua integridade atomicidade é determinada pelo parâmetro batchType, informado na requisição. Mais detalhes serão fornecidos na seção a seguir.

...

/totvseai/standardmessage/v1

Neste endpoint estarão devem estar 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 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 SOAP receiveMessage do padrão originalSOAP/XML.
• /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.

...

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

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 sera 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.

...

Os métodos HTTP previstos para o endpoint 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 as mensagens XML contendo a tag BusinessEvent, com Event igual a "delete".

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

...

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

Onde:

• 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.

...

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

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.

Elaboração da mensagem padronizada

...