Histórico da Página

...

Ao criar uma especificação de API TOTVS, é preciso ter em mente que existem alguns types e parameters padronizados previamente criados pela equipe TTALK, armazenados no arquivo totvsApiTypesBase.json. Com isso, esses parameters não precisam ser implementados "do zero" nos endpoints, mas sim propriamente referenciados na própria especificação de API.

...

	(...)

	"paths": {

		"/customerVendor": {

			"get": {

				"tags": [

					"customerVendor"

				],

				"summary": "Retorna todos Clientes/Fornecedores",

				"x-totvs": {

					"productInformation": [

						{

							"product": "Protheus",

							"available": true,

							"note": "Este verbo não está diponível no protheus. Utilize a consulta CustomerVendorEntity",

							"minimalVersion": "12.1.21"

						}

					]

				},

				"description": "Retorna todos clientes e/ou fornecedores",

				"operationId": "getcustomerVendor",

				"parameters": [

					{

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Authorization"

					},

					{

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Fields"

					},

					{

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Order"

					},

					{

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Page"

					},

					{

						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/PageSize"

					}

				],

				"responses": {

					"200": {

						"description": "Operação realizada com sucesso",

						"content": {

							"application/json": {

								"schema": {

									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/CustomerVendor_2_006.json#/definitions/PagedCustomerVendors"

								}

							}

						}

					},

					"400": {

						"description": "Erro na requisição!",

						"content": {

							"application/json": {

								"schema": {

									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/definitions/ErrorModel"

								}

							}

						}

					}


(...)

Utilizando os padrões fornecidos pela TTALK através do totvsApiTypesBase.json, o desenvolvedor não precisará criar na especificação os seguintes items:

...

Parameters:

• Authorization: caabeçalho cabeçalho usado para autorização das requisições;
• Order: utilizado para ordenação da coleção;
• Page: número da pagina da coleção;
• PageSize: utilizado para determinação de quantidade máxima de itens por página;
• AcceptLanguage: campo que determina o idioma que o cliente compreenderá;
• Fields: cabeçalho usado para restringir os campos trazidos em uma requisição;
• Expand: cabeçalho com o objetivo de expandir os campos requisitados.

Para maiores detalhes sobre uso dos cabeçalhos padronizados, visite nosso Guia de APIs. 

...

Uma API não deve ser confundida com um schema. As APIs são contratos responsáveis por definir os métodos e caminhos que permitem a comunicação entre dois pontosaplicativos. São as APIs que trazem informações relevantes sobre as trocas de dados entre uma aplicação e um produto TOTVS, definindo os moldes das mensagens trafegadas. Já o schema é modela a mensagem padronizada propriamente dita. Traz consigo uma forma de apresentar dados e seus tipos, permitindo a posterior transmissão de informações. Definições mais apuradas sobre os schemas podem ser encontradas na documentação sobre as mensagens padronizadas TOTVS.

...

• 3.4.1.1 x-totvs dentro da "info"

  O exemplo a seguir é um trecho da API UnitOfMeasure v2.

  Bloco de código
  language js title Exemplo collapse true
  (...) "info": { "description": "API para informações de Unidade de Medida para Unidade de Medida TOTVS", "version": "2.000", "title": "UnitOfMeasure", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasure", "description": "Cadastro de Unidade de Medida", "segment": "Serviços" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "QIES030.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "" } ] } } (...)

  A propriedade "messageDocumentation" do x-totvs traz informações sobre a própria API.

...

• 3.4.1.2 x-totvs dentro dos verbos dos endpoints

  O exemplo a seguir também é um trecho da API UnitOfMeasure v2.

  Bloco de código
  language js title Exemplo collapse true
  (...) "paths": { "/UnitOfMeasures": { "get": { "tags": [ "UnitOfMeasures" ], "summary": "Retorna lista de Unidade de Medida", "x-totvs": { "productInformation": [ { "product": "Protheus", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.21" }, { "product": "Logix", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.23" } ] } (...)

  Diferentemente do x-totvs da "info",  a propriedade "messageDocumentation" não está presente nos x-totvs dos "paths".
  
  Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.
  
  

  • product: produto ao qual aquelas informações do "productInformation" se referem;
  • available: campo booleano que indicia de o verbo esta implementado no produto;
  • note: observações sobre o verbo referente ao produto, como regras específicas;
  • minimalVersion: a versão minima na qual o verbo foi implementado no produto.

...

Como evidenciado no GIF o usuário pode, se preferir, acessar diretamente o arquivo OpenAPI e indentificar identificar no próprio JSON se as tags x-totvs especificam o produto procurado.

...

(...)

"info": {

		"description": "API para informações de Unidade de Medida para Unidade de Medida TOTVS",

		"version": "2.000",

		"title": "UnitOfMeasure",

		"contact": {

			"name": "T-Talk",

			"url": "api.totvs.com.br",

			"email": "[email protected]"

		},

		"x-totvs": {

			"messageDocumentation": {

				"name": "UnitOfMeasure",

				"description": "Cadastro de Unidade de Medida",

				"segment": "Serviços"

			},

			"productInformation": [

				{

					"product": "Protheus",

					"contact": "[email protected]",

					"description": "Cadastro de Unidade de Medida",

					"adapter": "QIES030.prw"

				},

				{

					"product": "Logix",

					"contact": "[email protected]",

					"description": "Cadastro de Unidade de Medida",

					"adapter": ""

				},
				{


					"product": "NovoProdutoTOTVS",


					"contact": "[email protected]",


					"description": "Cadastro de Unidade de Medida para NovoProdutoTOTVS",


					"adapter": "modeloDoAdpter"
				}
			]

		}

	}
(...)

Já para adição nos paths, o novo produto deve ser adicionado em cada um dos caminhos e verbos em que há cobertura pelo adapter. O exemplo para adição em apenas um verbo em um path pode ser visualizado abaixo:

...