Documentação
Um campo declarado dentro da a mensagem deve conter a propriedade description preenchida, além da propriedade customizada “x-totvs”Na documentação em descriptionobrigatoriamente as propriedades:
- Type: Indica o tipo do campo, mais detalhes consultar o tópico Tipos de dados padrão.
- Description: é importante que a descrição esteja bem detalhada, lembre-se que para o analista que está propondo um campo, o objetivo deste campo é sempre muito óbvio, porém próximos analistas do mesmo produto ou até analistas de outros produtos sempre terão dificuldade caso o campo não esteja bem documentado.
- x-totvs: propriedade customizada com a documentação referente ao campo em cada produto Totvs. Mais detalhes no tópico
Consulte o tópico Padrão de nomenclatura para mais detalhes sobre a correta redação da documentação dos campos e elaboração de seus nomes.
x-totvs
Como o objetivo da Mensagem Padronizada é ser um único contrato independente o produto, mas cada produto tem suas particularidades,viu-se a necessidade da criação da propriedade x-totvs. Essa propriedade é necessária em todos os campos que serão utilizados pelo produto para execução de determinada mensagem.
ATENÇÃO! Campos de de InternalId só só precisam de de x-totvs se se representarem a PK da mensagem. Se estes estiverem representando a FK de uma entidade pode-se entender que na declaração da PK já existe a documentação. Isto é interessante para evitar a replicação da definição da composição das chaves da da InternalId na na documentação.
Exemplo: |
---|
Essa propriedade consiste em um array de objetos, conforme exemplo abaixo:
Code Block |
---|
|
"CNAECode": {
"type": "string",
"example": "Pesquisar",
"description": "Código da Classificacao Nacional de Ativades Economicas",
"x-totvs": [{
"product": "protheus",
"field": "SM0.M0_CNAE",
"required": false,
"type": "Char",
"length": "7",
"note": "Campo obrigatório para o processo fiscal/TAF.",
"avialable": true,
"canUpdate": false
}]
} |
Product
CNAECode:
type: string
example: 'Pesquisar'
description: 'Código da Classificacao Nacional de Ativades Economicas'
x-totvs:
-product: protheus
field: 'SM0.M0_CNAE'
required: false
type: 'Char'
length: '7'
note: "Campo obrigatório para o processo fiscal/TAF."
avialable: true
canUpdate: false
Product:Produto a que se refere essa informação.
Exemplo: |
---|
product: “protheus” ou product: “rm” |
Field
: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” |
Required
:Obrigatoriedade do campo, caso haja alguma condição deve ser descrito na seção note.
Exemplo: |
---|
Required: True Required: False |
Type
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’ |
Length
: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’ |
note:Note
Complemento de informações sobre o campo se for o caso.
Exemplo: |
---|
Formato da informação
Vínculo entre mensagens
Escopo de dados - Deve , 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.
available
:Indica se o campo esta implementado para o produto, para a determinada mensagem. Recebe um valor Booleano:
Exemplo: |
---|
available: true available: false |
canUpdate
:indica se o valor do campo pode ser atualizado na tabela. Recebe um valor Booleano:
Exemplo: |
---|
canUpdate: true canUpdate: false |
Padrão de nomenclatura
:Os nomes dos campos na mensagem única devem respeitar as regras a seguir:
Devem ser sempre escritos em inglês.
Procure discutir com outras pessoas ou pesquisar no Google Translator a tradução correta dos termos. Deve-se prestar muita atenção na possibilidade de ocorrerem os falsos cognatos.
Exemplo: Código do Turno é ShiftCode e não TurnCode e nem CodeOfTurn. Turn em inglês significa: transformar, voltar, vez e não “turno”, é um caso de falso cognato.
camel case:Devem respeitar a formatação em camelCase Upper CamelCase com a primeira letra em maiúsculomaiúscula.
: , , , Padrão para chaves primárias e estrangeiras simples
Ao criar o elemento que representa a chave primária da mensagem utilize apenas a palavra Code, quando for chave simples. Exemplo: na mensagem Seller, use Code e Description/Name.
: |
---|
Mensagem Item Code Description Status RegisterDate |
Ao utilizar esta chave primária como chave estrangeira em outra mensagem, utilize o padrão “Mensagem” + “Code”, ou seja ItemCode, CustomerCode, BankCode. Exemplo: Na mensagem SalesOrder use SellerCode.
: |
---|
Mensagem Warehouse Code Description Mensagem Item Code Description Status RegisterDate WarehouseCode |
Reaproveitamento de nomes
Deve-se evitar a utilização de nomes diferentes para campos com o mesmo objetivo, por isso ao criar os nomes de campos para uma mensagem é importante verificar em outras mensagens qual termo está sendo utilizado para o mesmo objetivo.Exemplos:
sempre e para para empresa e filial Utilizar |
sempre pois pois este já é utilizado em todas as mensagens que usam a chave primária da mensagem Item. Não |
utilizar utilizar ProductCode, a mensagem para produto é a Item. |
Utilizar para para código do representante e |
não e nem e nem Provider, pois a mensagem já existente |
é mensagem mensagem Role, que representa Cargo no Logix. O Cargo do Logix corresponde a Função no Protheus. Então novas mensagens propostas pelo Protheus têm que usar o termo Role para Função e |
não
Utilize nomes que reflitam a descrição e vice-versaExemplos
Exemplo reais e proposta de correção |
---|
: |
---|
TableCodeItem - Código da Tabela de Preços (Deveria |
ser ou ou PriceTableCode) SalesPrice - Preço de mínimo de venda do produto (Deveria |
ser
Tipos dados padrões
Os Tipo de dados seguem o padrão definido na especificação do swagger (link).
Tipos dados padrões
Seguindo as especificações do OpenAPI 3.0.1, os tipo de dados deverão ser representados da seguinte forma:.
Texto
type: string
Code Block |
---|
|
"companyCodeCompanyCode": {
"type": "string"
} |
Propriedades de validação
maxLength | tamanho máximo do texto. Deve ser um valor inteiro maior que 0. |
minLength | tamanho mínimo do texto. Deve ser um valor inteiro maior que 0. |
pattern | string com expressão regular. |
Exemplo |
---|
minLength: 2, maxLength:2, pattern: "^[0-9]*$" | Válido: "22" ; "11" Inválido: "aa" ; "1"; "123" |
Numérico
Inteiro
type: integer
format: int32
Code Block |
---|
|
"bankCodeBankCode": {
"description": "Código do banco",
"type": "integer",
"format": "int32"
} |
Long
type: integer
format: int64
Code Block |
---|
|
"bankCodeBankCode": {
"description": "Código do banco",
"type": "integer",
"format": "int64"
} |
Float
type: number
format: float
Code Block |
---|
|
"unitsPerHourUnitsPerHour": {
"type": "number",
"format": "float"
} |
Double
type: number
format: double
Code Block |
---|
|
"creditLimitCreditLimit":{
"type":"number",
"format":"double"
} |
Propriedades de validação
minimum | menor valor possível para o campo. ex: -9999999.999 |
maximum | maior valor possível para o campo. ex: 9999999.999 |
multipleOf | define que apenas múltiplos a este valor podem ser atribuídos ao campo |
Info |
---|
Para definir precisão e escala de números com ponto flutuante, deve-se utilizar essas 3 propriedades. Exemplo |
---|
precisão: 10 escala: 3 | minimum: -9999999.999 maximum: 9999999.999 multipleOf: 1e-3 | Válido: 123.12 ; 000.254 Inválido: 123.4565 ; 0000.55484 |
|
Boleano
type: boolean
Code Block |
---|
|
"isPayerIsPayer":{
"type":"boolean"
} |
Data
type: string
format: date
Code Block |
---|
|
"registerdateRegisterdate":{
"type": "string",
"format": "date"
} |
Data e Hora
type: string
format: date-time
Code Block |
---|
|
"registerdateRegisterdate":{
"type": "string",
"format": "date-time"
} |
Objeto
type: object
Deve conter o atributo properties, o qual será um objeto com n propriedades.
Code Block |
---|
|
"creditInformationCreditInformation": {
"type": "object",
"properties": {
"creditIndicatorCreditIndicator": {
"type": "integer",
"format": "int32"
}
}
} |
Para objetos de tipos externos, deve-se utilizar a propriedade $ref, indicando a url do schema desejado, seguido de #/components/schemas/[nome do schema].
Code Block |
---|
|
"CommunicationInformation": {
"$ref": "http://api.totvs.com.br/schema/ContactInformation_1_000.json#/components/schemas/CommunicationInformationType",
"description": "Informações para Contato",
"type": "object"
} |
Array
type: array
Deve conter o atributo items, o qual deverá conter uma das seguintes opções:
type |
Quando array de tipos comuns (string, integer, number, boolean, etc) | Code Block |
---|
"type":"array",
"items": {
"type": "string"
} |
|
properties |
Quando for array de objetos | Code Block |
---|
"type":"array",
"items": {
"properties": {
"bankCode": {
"descriptionnote": "Código do banco",
"type": "integer",
"format": "int32"
}
}
} |
|
$ref | Quando array de objetos externos | Code Block |
---|
"type":"array",
"items":{
"$ref": "https://api.totvs.com.br/schemas/#/components/schemas/AddressInfo"
} |
|
Atributos:
maxItems: Indica o tamanho máximo do array
Code Block |
---|
|
"bankingInformation": {
"type": "array",
"maxItems": "1",
"items": {
"properties": { Note |
---|
Por definição todo campo ListOf deve ser array. |
Propriedades de validação
minItems | valor mínimo de items do array. |
maxItems | valor máximo de items do array. |
"BankCode": {
"description": "Código do banco",
"type": "integer",
"format": "int32"
}
}
}
}Obrigatoriedade
No yaml as propriedades devem ser definidas como não obrigatórias, pois as mensagens únicas são utilizadas tanto para inclusão quando para exclusão. Ou seja, uma exclusão não precisa enviar tantas informações quanto a inclusão. Se a mensagem única tivesse os seus campos obrigatórios geraria a necessidade de se enviar o registro completo para exclusão e não apenas a sua chave.
Além disso, a obrigatoriedade de um campo depende de cada produto, o que torna muito mais difícil chegar a um consenso se for necessário considerar esta característica na mensagem.
Por isso, ao declarar o schema não se deve inserir a propriedade required:
Campos que se repetem poderão apresentar um padrão diferente, consulte o tópico Criando listas de valores e elementos para mais informações.
Havendo a necessidade de validação da presença ou não de informação na mensagem, este controle deve ser feito no próprio adapter.
Campos de código + descrição
Não é necessário montar mensagens específicas para tabelas que só precisarão trafegar código + descrição. Estas informações poderão trafegar como chave estrangeira na mensagem que as utilizar. Também não é necessário criar agrupadores específicos para estes campos, podem ser colocados na raiz das mensagens.
Exemplo:
Hipoteticamente, a mensagem Item deverá levar a informação do fabricante.
Mensagem Item
Code
Description
ManufacturerCode
ManufacturerDescription
Por exemplo: Não existe a necessidade de criar a mensagem Manufacturer (supondo que contém apenas Código + Descrição). Estes dados deverão ser enviados na mensagem de Item
Anchor |
---|
| valores_fixos |
---|
| valores_fixos |
---|
|
Campos com valores fixosCampos com valores fixos devem ser definidos como type: String e seus valores respeitar a sequencia 1,2,3,4 etc... O objetivo desta definição é evitar confusões pelo uso de letras iguais para objetivos diferentes entre os produtos TOTVS. Exemplo: RM Pedido Cancelado = “C”, Datasul Pedido Concluído = “C”. Utilizando sempre a sequência numérica o desenvolvedor se vê obrigado a observar a lista de valores presentes na mensagem, observando inclusive se o tipo que queira utilizar já está listado no YAML
Porém, muitas vezes quando um campo em um produto é composto por uma lista fixa de valores, em outro produto esses valores podem ser cadastrados dinamicamente. Exemplo: Tipo do documento no Logix é fixo, no Protheus é pre-cadastrado e permite alterar, na Datasul é fixo e na RM é totalmente cadastrável. Para estes casos leia o tópico Conflito entre valores fixos e valores cadastráveis.
Exemplo: |
---|
Code Block |
---|
|
"SubscriptionType": {
"type": "string",
"example": "pesquisar",
"description": "Unidade de Negócio",
"enum": ["1",
"2",
"3",
"4"],
"x-totvs": [{
"product": "protheus",
"field": "SM0.M0_TPINSC",
"required": false,
"type": "Char",
"length": "1",
"avialable": true,
"canUpdate": false,
"note": |
SubscriptionType: type: string example: 'pesquisar' description: 'Unidade de Negócio' enum: ['1','2','3','4'] x-totvs: -product: protheus: field: 'SM0.M0_TPINSC' required: false type: 'Char' length: '1' avialable: true canUpdate: false note: "1=CEI;2=CNPJ;3=CPF;4=INCRA"
}]
} |
Exemplo de documentação:
branchBranch_2_001.json
Referências
https://tools.ietf.org/html/draft-wright-json-schema-validation-00
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#dataTypes
https://github.com/OAI/OpenAPI-Specification/issues/602