Índice |
---|
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.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "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
Nota | ||
---|---|---|
| ||
É obrigatório que, ao utilizar as duas integrações disponíveis, o conteúdo definido para retorno da API seja o mesmo que o "Content" do protocolo transactions |
Abaixo encontram-se as regras para definir uma mensagem padronizada.
Âncora | ||||
---|---|---|---|---|
|
O objetivo dessa propriedade é especificar quais produtos Totvs implementaram uma determinada mensagem, e trazer outras informações sobre a mesma.
Bloco de código | ||||
---|---|---|---|---|
| ||||
"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" } } } } |
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
Contém lista com nomes dos produtos em que essa mensagem foi implementada, qual o seu adapter correspondente e responsável.
Campo Obrigatório
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
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:
Bloco de código | ||||
---|---|---|---|---|
| ||||
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 } ] }, |
Produto a que se refere essa informação.
Exemplo |
---|
product: “protheus” ou product: “rm” |
Campo Obrigatório
A qual tabela.campo o campo da mensagem se refere.
Caso no produto este campo possa estar em mais tabela, explicar o funcionamento.
Exemplo |
---|
Field: “clientes.cod_cliente” ou Field: “cliente.cod_cliente para Type=Customer ou fornecedor.cod_fornecedor para Type=Vendor” |
Campo Obrigatório
Obrigatoriedade do campo, caso haja alguma condição deve ser descrito na seção note.
Exemplo |
---|
Required: True Required: False |
Campo Obrigatório
Tipo do campo no produto. Importante declarar aqui o tipo do campo como é conhecido no produto.
Exemplo |
---|
type: ‘char’ type: ‘varchar’ type: ‘number’ type: ‘decimal’ type: ‘integer’ type: ‘boolean’ |
Campo Obrigatório
Tamanho do campo no produto, pode ser informado apenas o tamanho ou outro texto que descreva como este tamanho funciona.
Exemplo |
---|
length: ‘20’ length: ‘8,2’ length: ’sempre implantado como 20, mas o cliente pode usar até 50’ |
Campo Obrigatório
Complemento de informações sobre o campo se for o caso, como por exemplo formato da informação, vínculo entre mensagens, escopo de dados (deve ser informado para campos que precisam respeitar uma relação específica de valores no produto, podendo ser informado aqui: 'lista fixa' ou 'valores da tabela [tabela.campo]')
Exemplo |
---|
"note": "1=CEI;2=CNPJ;3=CPF;4=INCRA" "note": "Campo obrigatório para o processo fiscal/TAF." "note":"Segmento Principal" |
Caso na mensagem tenha sido definida lista fixa, informar aqui a relação dos valores da mensagem com os valores do produto.
...ou qualquer outra informação importante para descrever a representação desta tag no produto em questão.
Campo Opcional
Indica se o campo esta implementado para o produto, para a determinada mensagem. Recebe um valor Booleano:
Exemplo |
---|
available: true available: false |
Campo Obrigatório
indica se o valor do campo pode ser atualizado na tabela. Recebe um valor Booleano:
Exemplo |
---|
canUpdate: true canUpdate: false |
Campo Obrigatório
Âncora | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
|
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.unece.org/cefact/brs/brs_index.html