A documentação da mensagem deve ser definida na propriedade customizada x-totvs que deve ficar dentro da propriedade info. O objetivo desta documentação é definir para cada mensagem o seu nome em português, uma descrição e descrever características de como ela está sendo implementada em cada produto.
O preenchimento desta documentação é obrigatório caso o produto implemente a mensagem, e de responsabilidade da equipe de negócio que definiu o seu conteúdo.
Mensagem: Branch
Bloco de código | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
"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": { "protheus": { "contact": "[email protected]", "description": "Cadastro de Filial", "adapter": "apcfg230i.prw", "helpUrl": "link aqui" } } } } |
Informações da estruturação da Mensagem Padronizada no protocolo Transactions, descrevendo o tipo da mensagem, o contrato das tags BusinessContent e ReturnContent, dentre outras informações .
Informações gerais da mensagem representa o resultado do consenso. Ou seja, neste espaço deve ser informado o nome, descrição e conceito que estão em acordo com todos os outros produtos do grupo.
Informações específicas do produto para a mensagem. Aqui podem entrar informações para entender o que a mensagem representa dentro de determinado produto.
Ao declarar uma API, é obrigatório inserir para cada verbo a documentação interna, e esta deve conter as seguintes informações:
paths: /Branch: get: tags: - Branch summary: "Retorna todas as Filiais da base" x-totvs: productInformation: -product: protheus available: true note: 'Este verbo esta disponivel com todos os parametros' minimalVersion: '12..1.21'
A propriedade x-totvs indica as informações de documentação interna. Ela contem array de objetos, onde cada item deve ser referente a um produto.
Cada Item deve conter as seguintes informações:
Sempre construir o Adapter (mensagem), pensando que ela deverá ser enviada e recebida, mesmo que o seu projeto não contemple as duas opções.
A codificação utilizada nas mensagens do TOTVSMessage é o UTF-8
A assinatura ou contrato que representa a estrutura de dados e métodos recebidos ou retornados numa API/Serviço não pode ser alterada. Uma vez liberada ou publicado o serviço, a sua assinatura deve ser imutável.
As mensagens padronizadas estão preparadas para serem controladas por Versão e por Modificação.
Se a mensagem utilizar o "internalID" sugerimos que inicie pelo número "2" e somente irá mudar quando a alteração na mensagem torna esta incompatível com o layout anterior a alteração. A decisão de mudar a versão nunca deve ser tomada somente pelo analista, o comitê deverá ser envolvido desde o princípio quando uma possibilidade desta for identificada.
Exemplo:
Exemplo de alteração de versão:
Quando uma mensagem mudar a versão, os sistemas precisam ser capazes de processar as versões anteriores.
Manter a compatibilidade entre as versões de mensagens, tratando campos atuais das versões do produto.
Exemplos:
Incluído um campo na versão 12 do Produto e consequentemente evoluído a mensagem de 3.000 para 3.001. A versão 12 do produto deverá ser capaz de processar a mensagem 3.000 (sem o campo novo) atribuindo um valor default para o campo evitando erros de CRUD. O mesmo se aplica para casos de alterações da estrutura da mensagem (de 3.000 para 4.000).
Sempre começa por 000 e somente irá mudar quando algum campo puramente informativo for incluído na mensagem. Caso a versão/modificação da mensagem ainda estão com seus adapters sendo desenvolvidos pelos produtos e a mensagem em si nesta versão/modificação ainda não foi para cliente, é possível alinhar entre os produtos para que novos campos sejam incluídos na modificação atual.
Exemplo de modificação:
Ao elaborar uma nova mensagem ou a nova versão de uma mensagem existente a equipe de negócio deve:
Índice |
---|