Histórico da Página
...
- 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:
...
- A definição do InternalId é obrigatória no modelo da transação, seja em XML Schema, seja em modelo OpenAPI (Swagger)Json Schema. 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.
...
- UUID: mesma definição da tag UUID;
- Type: mesma definição da tag Type, exceto que não haverá mensagens do incluindo também o 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;
- Event: quando SubType é event, este atributo conterá os valores upsert ou delete, para indicar que a mensagem corresponde a uma inclusão/alteração ou a uma eliminação, respectivamente.
- Transaction: mesma definição da tag Transaction;
- Version: corresponde ao atributo 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á ainda os seguintes atributos: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 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., com a ressalva de que os atributos utilizaram a forma capitalizada, em vez do formato "camelCase", ou seja, em vez de "code", será usado "Code", por exemplo.
- ReturnContent: conterá o resultado do processamento da mensagem original, conforme definido para a transação. Além disso, 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 internal IDs 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.
| Informaçõeswarning | ||
|---|---|---|
| ||
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. | ||
| ||
A tag Identification, subordinada à tag | ||
| Informações | ||
| ||
A tag Identification, subordinada à tag BusinessEvent, não será contemplada no formato REST/JSON. Essa tag foi sendo substituída ao longo do tempo pelos Internal IDs InternalIDs do corpo das mensagens. Ao migrar um adapter para utilizar o novo formato, qualquer processamento baseado na tag Identification deve ser revisto. |
...
Exemplos de Mensagem - contexto server-to-server
Uma mensagem da transação CostCenter, na versão 2.000, seria expressa da seguinte no contexto de uso server-to-server, seria expressa da seguinte forma, usando o formato JSON:
| Bloco de código | ||
|---|---|---|
| ||
{
"Header" : {
"UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
"Type" : "BusinessMessage",
"SubType" : "event",
"Event" : "upsert",
"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
}
} |
...
| Bloco de código | ||
|---|---|---|
| ||
{
"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"
}
]
}
}
} |
Para mensagem de Resposta Assíncronas o método do envio deve ser POST, pois esta sendo trafegada a resposta, independente da operação original. Para obter o processo da mensagem original pode se acessar a propriedade Content.ReceivedMessage.Event.
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.
| Bloco de código | ||
|---|---|---|
| ||
{
"Items" : [
{
"Header" : {
"UUID" : "",
"Type" : "",
"SubType" : "",
"Event" : "",
"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" : ""
}
}
]
} |
...
- É 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.
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:
...
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:
| Bloco de código | ||||
|---|---|---|---|---|
| ||||
{
"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.
| Informaçõ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. |
Predicado /transactions
| Painel | ||
|---|---|---|
| ||
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/transactions?batchType={batchType}?batchUUID={batchUUID} |
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.
| Nota |
|---|
| 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:
- 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".
| Informações | ||
|---|---|---|
| ||
Por definição, não serão aceitas mensagens com subtipo request no método DELETE. Apenas mensagens com subtipo event serão permitidas. Quando tal situação ocorre, será retornado, no mínimo, o código HTTP 405 (Method not allowed). |
| Informações | ||
|---|---|---|
| ||
Diante do descrito até o momento, há duas formas de se indicar a operação de uma mensagem do tipo BusinessMessage: via métodos HTTP (POST e DELETE) e via atributo Event. Sempre que for possível determinar a operação pelos atributos do canal, esta será a informação prevalente, como é o caso do canal REST, onde os métodos HTTP provêm essa indicação. Neste caso, pode ocorrer sobre posição da informação no atributo Event da mensagem, se ele não for compatível com a indicação do canal. O atributo Event, dentro da mensagem, será considerado apenas nos casos onde o canal não fornecer a indicação da operação, como é o caso do canal AMQP. |
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.Isso implica que a modelagem de uma transação usando o padrão REST/JSON seja compatível com a modelagem usando o padrão SOAP/XML (orientações no tópico seguinte).
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 Json Schema, Draft 4 ou superior, em substituição ao formato XML Schema (XSD) utilizado na implementação SOAP/XML. Para mais informações sobre como implementar um documento no formato Json Schema consulte a especificação própria do padrão.
Em nome da consistência entre os formatos, é necessário ter em mente o seguinte procedimento: ao desenvolver, por exemplo, um documento Json Schema (padrão REST/JSON) para a transação CostCenter, versão 2.000, deve-se verificar se já existe um documento XSD da referida transação (padrão SOAP/XML). Existindo o documento, todos os atributos que definem a tag BusinessContent devem estar presentes no tipo equivalente no documento Json Schema, para que o modelo seja considerado como sendo da transação CostCenter, versão 2.000.
Por outro lado, é possível que um documento Json Schema seja implementado sem que haja o correspondente em XSD. Neste caso, a modelagem deve ser elaborada considerando que a transação também pode vir a ser usada no futuro para integração server-to-server, e por isso, deve conter atributos que permitam o uso em tal contexto, mesmo que inicialmente a utilização seja no contexto client-to-server. Se isso for levado em consideração, não será necessário criar um documento XSD equivalente para a mesma transação e versão.
Para a documentação da transação no arquivo de definição Json Schema, há regras para a mensagem e para os campos, conforme abaixo:
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 Branch, versão 2.001, usando o padrão Json Schema, 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.
| Informações |
|---|
| Este exemplo foi reduzido para destacar a definição do modelo de dados. Entretanto, um modelo completo deve incluir, entre outras coisas, a documentação da mensagem conforme indicado anteriormente. |
| Bloco de código | ||
|---|---|---|
| ||
{
"$schema": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/events/branch_2_001.json#",
"info": {
"description": "Contrato de Mensagem Padronizada para a entidade filial (Branch) para produtos TOTVS",
"version": "2.001",
"title": "Branch",
"contact": {
"name": "T-Talk",
"url": "API.Totvs.com.br",
"email": "[email protected]"
},
"x-totvs": {
"transactionMessageDocumentation": {
"subType": "event",
"businessContentType": {
"type": "object",
"$ref": "#/definitions/BranchType"
},
"returnContentType": {
"type": "object",
"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/ListOfInternalId_1_000.json#/definitions/ReturnContentWithModelType"
}
},
"messageDocumentation": {
"name": "Branch",
"description": "Filial",
"segment": "FrameWork"
},
"productInformation": [
{
"product" : "protheus",
"contact": "[email protected]",
"description": "Cadastro de Filial",
"adapter": "apcfg230i.prw",
"helpUrl": "link aqui"
}
]
}
},
"definitions": {
"BranchType": {
"type": "object",
"properties": {
"CompanyCode": {
"type": "string",
"example": "D",
"description": "Código da Empresa",
"x-totvs": [
{
"product": "protheus",
"Field": "XX8.XX8_CODIGO",
"Required": false,
"Type": "Char",
"length": "12",
"avialable": true,
"canUpdate": false
}
]
},
"internalId": {
"description": "InternalId da entidade",
"type": "string",
"example": "01",
"x-totvs": [
{
"product": "protheus",
"Field": "XX8.XX8_CODIGO",
"Required": false,
"Type": "Char",
"length": "100",
"avialable": true,
"canUpdate": false
}
]
},
"Description": {
"type": "string",
"example": "Filial São Paulo 1",
"description": "Descrição",
"x-totvs": [
{
"product": "protheus",
"Field": "XX8.XX8_NOME",
"Required": false,
"Type": "Char",
"length": "100",
"avialable": true,
"canUpdate": false
}
]
},
"Code": {
"type": "string",
"example": "D SP 01",
"description": "Filial/Codigo Unidade"
},
(...)
},
"required":["CompanyCode"]
}
}
}
|
| Informaçõ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. |
Predicado /transactions
| Painel | ||
|---|---|---|
| ||
| http://<servidor>[:<porta>]/totvseai/standardmessage/v1/transactions?batchType={batchType}?batchUUID={batchUUID} |
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.
| Nota |
|---|
| 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:
- 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".
| Informações | ||
|---|---|---|
| ||
Por definição, não serão aceitas mensagens com subtipo request no método DELETE. Apenas mensagens com subtipo event serão permitidas. Quando tal situação ocorre, será retornado, no mínimo, o código HTTP 405 (Method not allowed). |
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.
Elaboração da mensagem padronizada
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas