Frameworksp

Atalhos

Páginas filhas
  • 1.1 Definições para campos

Versões comparadas

Versão antiga 2

changes.mady.by.user Usuário desconhecido (francisco.cardoso)

Gravado em

comparado com

Nova versão 3

changes.mady.by.user Usuário desconhecido (francisco.cardoso)

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

  • 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. 
    • Clique aqui para mais detalhes <COLOCAR ANCORA COM O OUTRO DOCUMENTO>

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.

Padrão de nomenclatura

Os nomes dos campos na mensagem única devem respeitar as regras a seguir:

...

Devem respeitar a formatação em Upper CamelCase com a primeira letra maiúscula.

Exemplo

CustomerCode

RegisterDate

ListOfItem

TypeOfDay

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.

Exemplo

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.

Exemplo

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.

Exemplo

Utilizar sempre CompanyId e BranchId para empresa e filial

Utilizar sempre ItemCode pois este já é utilizado em todas as mensagens que usam a chave primária da mensagem Item. Não utilizar ProductCode, a mensagem para produto é a Item.

Utilizar VendorCode para código do representante e não Suplier e nem Provider, pois a mensagem já existente é CustomerVendor.

Informações

Hoje já existe a 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 Function.

...

Utilize nomes que reflitam a descrição e vice-versa

Exemplo reais e proposta de correção

TableCodeItem - Código da Tabela de Preços (Deveria ser PriceListCode ou PriceTableCode)

SalesPrice - Preço de mínimo de venda do produto (Deveria ser MinimumSalesPrice)


Tipos dados padrões

Os Tipo de dados seguem as especificações do OpenAPI 3.0.1.

...

Propriedades de validação

maxLengthtamanho 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

...

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
Informações

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

...

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)

Bloco de código
"type":"array",
"items": {
   "type": "string"
}





properties





Quando for array de objetos

Bloco de código
"type":"array",
"items": {
    "properties": {
          "bankCode": {
          	"note": "Código do banco",
          	"type": "integer",
          	"format": "int32"
		   }
	}
}
$refQuando array de objetos externos
Bloco de código
"type":"array",
"items":{
	"$ref": "https://api.totvs.com.br/schemas/#/components/schemas/AddressInfo"
}
Nota

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.

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.

...