Anatomia da Mensagem TOTVS

A Mensagem Padronizada TOTVS estabelece alguns padrões que devem ser seguidos por todos os aplicativos que participam da integração. Estes padrões estabelecem alguns tipos de mensagens suportadas bem como informações obrigatórias que devem fazer parte do seu conteúdo.

A composição do conteúdo de cada uma das mensagens de negócio será definida em conjunto com especialistas de negócio e não faz parte do escopo deste documento.

A anatomia básica de uma mensagem de negócio permite que dentro de uma mensagem específica seja definido apenas o conteúdo de negócio e retorno, mas quando a mensagem completa for trafegar entre os produtos, todas as informações citadas acima também façam parte da estrutura da mensagem.

Veja abaixo um exemplo do JSON de uma mensagem padronizada completa (incluindo header para controle da camada de EAI):

Clique aqui para obter mais informações sobre integração via transactions (EAI)

No caso de JSON simplificado para API, trabalhamos apenas com o conteúdo da propriedade "content", desconsiderando o header.

Veja abaixo o exemplo do mesmo JSON definido acima, porém como modelo de request/response de uma API.

{
    "CompanyId": "1",
    "BranchId": "B1",
    "CompanyInternalId": "CompanyInternalId",
    "InternalId": "InternalId",
    "Code": "Code",
    "Description": "Description",
    "NatureType": "NatureType",
    "UseCategory": "UseCategory",
    "Blocked": 0    
}

Clique aqui para obter mais informações sobre integração via API

Definição da Mensagem no modelo JsonSchema

Abaixo encontram-se as regras para definir uma mensagem padronizada.

• Seguir essa especificação do formato JsonSchema
  • Exemplos aqui
• Seguir a definição de campos especificada <link para definição de campos reformulada>
• Especificar propriedade X-Totvs, de acordo com regras especificadas, incluindo quais ERPs implementam aquela mensagem e os campos relacionados. 
• Sempre que possível, utilizar padrões internacionais. Para saber se já existe uma mensagem de conta contábil, por exemplo, pesquise no Google usando "account xsd oasis repository".
• Mensagens criadas para atender uma exigência legal devem se ater estritamente ao que é definido pela legislação. Nestes casos, o nome da mensagem e dos campos podem ser em português, se a legislação exigir.

Âncora
xtotvs xtotvs

X-TOTVS

Cabeçalho (Info)

O objetivo dessa propriedade é especificar quais produtos Totvs implementaram uma determinada propriedade da mensagem, e trazer outras informações sobre a mesma.

"info": {
...
"x-totvs": {
            "messageDocumentation": {
                "name": "StockTurnOver",
                "description": "Baixa de estoque",
                "segment": "Construção e Projetos"
            },
            "productInformation": [
                {
                    "product": "RM",
                    "contact": "Bruno Barbosa de Souza",
                    "note": "GDP Inovação Const. e Proj.",
                    "adapter": "MovMovimentoData"
                },
                {
                    "product": "PROTHEUS",
                    "contact": "Eduardo de Souza",
                    "note": "GDP de Materiais",
                    "adapter": "MATI241"
                },
                {
                    "product": "PIMS",
                    "contact": "José Alberto da Silva",
                    "note": "",
                    "adapter": ""
                }
            ],
            "transactionDefinition": {
                "subType": "event",
                "businessContentType": {
                    "$ref": "#/definitions/BusinessContentType",
                    "type": "object"
                },
                "returnContentType": {
                    "$ref": "#/definitions/ReturnContentType",
                    "type": "object"
                }
            }
        }
}

MessageInformation

Contém nome, descrição e agrupador da mensagem (esse último definido através da propriedade segment)

Clique aqui para verificar os valores disponíveis para a propriedade segment

Campo Obrigatório

ProductInformation

Contém lista com nomes dos produtos em que essa mensagem foi implementada, qual o seu adapter correspondente e responsável.

Campo Obrigatório

TransactionDefinition

Esse campo deve ser definido para ativar a integração dessa mensagem via transaction (EAI)

Ele contém a informação do subtype (event ou request), e quais objetos do schema correspondem ao businessContentType e returnContentType.

Ao ativá-lo dessa maneira, a propriedade "Header" será preenchida automaticamente pelo EAI, enquanto a propriedade "Content" será substituída pelo objeto configurado.

Clique aqui se existem dúvidas sobre integração via transaction

Campo Opcional

Corpo/Propriedades

O objetivo dessa propriedade é especificar quais produtos Totvs implementaram uma determinada propriedade da mensagem, e trazer informações específicas sobre aquele campo em um determinado produto.

Segue exemplo abaixo:

Code": {
                    "type": "string",
                    "description": "Código do País",
                    "x-totvs": [
                        {
                            "product": "Logix",
                            "Field": "paises.cod_pais",
                            "Required": true,
                            "Type": "Char",
                            "length": "3",
							"note": "some info...",
                            "available": true,
                            "canUpdate": false
                        },
                        {
                            "product": "RMS",
                            "Field": "AA1CPAIS.PAIS_COD",
                            "Required": true,
                            "Type": "integer",
                            "length": "6",
							"note": "some info...",
                            "available": true,
                            "canUpdate": false
                        }
                    ]
                },

Product

Nome do produto TOTVS do qual as outras informações se referem

Campo Obrigatório

Available 

Define se essa propriedade está ou não disponível 

Campo Obrigatório

CanUpdate

Define se essa propriedade pode ser atualizada

Campo Obrigatório

Field

A qual tabela.campo o campo da mensagem se refere.

Caso no produto este campo possa estar em mais tabela, explicar o funcionamento.

Campo Obrigatório

Required

Obrigatoriedade do campo, ou condições em que ele será obrigatório ou não.

Campo Obrigatório

Type

Tipo do campo no produto. Importante declarar aqui o tipo do campo como é conhecido no produto.

Campo Obrigatório

Length

Tamanho do campo no produto, pode ser informado apenas o tamanho ou outro texto que descreva como este tamanho funciona.

Campo Obrigatório

Note

Complemento de informações sobre o campo se for o caso.

Campo Opcional

Âncora
jschema-examples jschema-examples

Exemplos JsonSchema:

Json Schema da Mensagem Branch 2.001 : https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/Branch_2_001.json

Outros Json Schemas aprovados: https://github.com/totvs/ttalk-standard-message/tree/master/jsonschema/schemas

Exemplos Oficiais site json-schema: https://json-schema.org/learn/miscellaneous-examples.html

Âncora
int-examples int-examples

Padrões internacionais de mensagens para integração

http://docs.oasis-open.org/ubl/prd1-UBL-2.1/UBL-2.1.html

http://docs.oasis-open.org/ubl/UBL-2.1-JSON/v1.0/cnd02/UBL-2.1-JSON-v1.0-cnd02.html

http://docs.oasis-open.org/ubl/UBL-2.1-JSON/v1.0/cnd02/json-schema/maindoc/

http://www.hl7.org/

http://www.unece.org/cefact/brs/brs_index.html