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.
Este documento leva em consideração que o leitor tenha um conhecimento prévio da mensagem padronizada TOTVS utilizando XML e SOAP. Caso algum termo não esteja suficientemente descrito aqui, recomenda-se consultar o documento Padrão para criação de mensagem padronizada, disponível no portal de Integrações TOTVS. |
Semelhante ao que se tem na mensagem padronizada, baseada em SOAP e XML, a estrutura é composta dos seguintes elementos:
Graficamente, a estrutura pode ser descrita conforme abaixo:
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.
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.
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á ainda os seguintes atributos:
No padrão REST/JSON, a indicação do tipo de operação - upsert ou delete - originalmente indicada na tag Event do padrão SOAP/XML, estará vinculada ao método HTTP utilizado na requisição. Mais informações serão prestadas na seção Interface deste documento. |
Uma mensagem da transação CostCenter, na versão 2.000, 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" : "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"
}
]
}
}
} |
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:
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:
Salvo quando explicitamente indicado no documento, deve-se considerar que os endpoints disponibilizam os recursos previstos no Guia de Implementação de APIs para paginação, ordenação e filtro de dados. |
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/transactions?batchType={batchType}?batchUUID={batchUUID} |
Onde:
| Os parâmetros de paginação, ordenação e filtro de dados previstos pelo Guia de Implementação de APIs não são aplicáveis para as requisições deste predicado. |
Os métodos HTTP previstos são:
Exemplos de utilização deste predicado podem ser encontrados nos links a seguir:
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/contents/{transactionID_version}/{internalID}. |
Onde:
Os métodos previstos são:
| 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 utilizadas para realizar o controle da mensagem (rastreamento, fila, etc). A proposta é 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 apenas ao atributo content do modelo completo, usado pelo endpoint /transactions. |
Exemplos de utilização deste predicado podem ser vistos nos link a seguir:
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.
O desenho de uma transação, no formato REST/JSON, deve utilizar o formato Swagger/OpenAPI, em substituição ao formato XML Schema, utilizado na implementação original. Para mais informações sobre como implementar um documento Swagger, consulte a especificação.