...

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

...

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

...

{
    "Header" : {
        "UUID" : "d6bbfa63-ca27-e2ac-0b14-101970f59a5b",
        "Type" : "BusinessMessage",
        "SubType" : "event",
        "TransactionEvent" : "CostCenterupsert",
         "VersionTransaction" : "2CostCenter",
        "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" : "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.

{
    "Items" : [
        {
            "Header" : {
                "UUID" : "",
                "Type" : "",
                "SubType" : "",
                "TransactionEvent" : "customerVendor",
                 "VersionTransaction" : "2.001customerVendor",
                "SourceApplicationVersion" : "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" : ""
            }
        }
    ]
}

...

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

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:

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

{
	"$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": [

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		{
		  			"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": [
        BranchId:
      			{
							"product":    type: string
          description: Código da filial/estabelecimento/coligada
        CompanyInternalId:
          type: string
          description: InternalId da empresa
        Code:"protheus",
							"Field": "XX8.XX8_CODIGO",
							"Required": false,
							"Type": "Char",
							"length": "12",
							"avialable": true,
							"canUpdate": false
						}
					]
				},
          type		"internalId": string{
		            "description": Código"InternalId do centro de custo
da entidade",
		        InternalId:
    "type":      type: string"string",
					"example": "01",
					"x-totvs": [
          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:
 			{
							"product": "protheus",
							"Field": "XX8.XX8_CODIGO",
							"Required": false,
							"Type": "Char",
							"length": "100",
							"avialable": true,
							"canUpdate": false
						}
					]
		          type: string
     },
				"Description": {
					"type": "string",
					"example": "Filial São Paulo 1",
					"description": "Descrição",
					"x-totvs": [
     description: Descrição do centro de custo
    			{
							"product": "protheus",
							"Field": "XX8.XX8_NOME",
							"Required":  ShortCode:
          type: string
          description: Descrição breve do centro de custo
        SPED:
          type: boolean
        Class:
          type: numberfalse,
							"Type": "Char",
							"length": "100",
							"avialable": true,
							"canUpdate": false
						}
					]
				},
				"Code": {
					"type": "string",
					"example": "D SP 01",
					"description": "Filial/Codigo Unidade"
				},
				(...)
			},
			"required":["CompanyCode"]
		}
	}
}