Histórico da Página

...

A propriedade x-totvs nas APIs está localizada tanto no cabeçalho (tag info) quanto nos métodos dos paths (endpoints) no arquivo OpenAPI, contendo informações diferentes dependendo do local em que está inserida. Contudo, as propriedades x-totvs tem sempre um objetivo em comum: armazenar dados pertinentes aos produtos TOTVS. São nas x-totvs em que são especificadas informações como o nome do produto ao qual se refere, segmento e domínio ao qual está vinculado, adapter atrelado, se determinado verbo está disponível para aquele caminho, entre outros.

...

• x-totvs dentro da "info"

  Âncora
  xtotvs-info xtotvs-info

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

  Bloco de código
  language js title Exemplo collapse true
  (...) "info": { "description": "API para informações de UnidadeGrupo de MedidaProduto para Unidade de MedidaProdutos TOTVS", "version": "21.000", "title": "UnitOfMeasureGrupo de Produto", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasureStockGroup", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "segment": "ServiçosConstrução e Projetos", } "domain": "Planejamento" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "CadastroGrupo de Unidade de MedidaProduto", "adapter": "QIES030MATS035.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "adapter": "" } ] } } (...)

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

• • • name: título da API;
    • description: descrição da API;
    • segment: segmento da TOTVS pelo qual aquela API foi implementada.
    • domain: domínio de negócio ao qual os recursos pertencem.
      
      
  Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.

• • • product: produto ao qual aquelas informações do "productInformation" se referem;
    • contact: e-mail para contato com quem desenvolveu aquela API naquele determinado produto;
    • description: descrição da API para aquele determinado produto;
    • adapter: adapter que se comunica com aquela determinada API;
    • A propriedade "productInformation" poderia ter ainda a tag helpUrl, que contém um link para a documentação daquela API para aquele produto, caso haja.

  Nota
  title Segment e Product padronizados
  A grafia dos campos 'segment' e 'product' descritos acima devem estar de acordo com padrões previamente determinados. Para saber qual a grafia correta do segmento e produto que deseja declarar, visite a lista de referências do portal de APIs e verifique no menu lateral os padrões de grafia aceitos.

• x-totvs dentro dos verbos dos endpoints 

  Âncora
  xtotvs-paths xtotvs-paths

  O exemplo a seguir é um trecho da API UnitOfMeasure

  x-totvs dentro dos verbos dos endpoints  Âncoraxtotvs-pathsxtotvs-paths

  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.

...

(...)
"info": {
		"description": "API para informações de UnidadeGrupo de MedidaProduto para Unidade de MedidaProdutos TOTVS",
		"version": "21.000",
		"title": "UnitOfMeasureGrupo de Produto",
		"contact": {
			"name": "T-Talk",
			"url": "api.totvs.com.br",
			"email": "[email protected]"
		},
		"x-totvs": {
			"messageDocumentation": {
				"name": "UnitOfMeasureStockGroup",
				                "description": "Cadastro de UnidadeGrupo de MedidaProduto",
                "segment": "Construção e Projetos",
				"segmentdomain": "ServiçosPlanejamento"
			},
			"productInformation": [
				{
					"product": "Protheus",
					"contact": "[email protected]",
					"description": "CadastroGrupo de Unidade de MedidaProduto",
					"adapter": "QIES030MATS035.prw"
				},
				{
					"product": "Logix",
					"contact": "[email protected]",
					"description": "Cadastro de UnidadeGrupo de MedidaProduto",
					"adapter": ""
				},
				{
					"product": "NovoProdutoTOTVS",
					"contact": "[email protected]",
					"description": "Cadastro de UnidadeGrupo de MedidaProduto para NovoProdutoTOTVS",
					"adapter": "modeloDoAdpter"
				}
			]
		}
	}
(...)

...

Tipos de Conteúdo 

Âncora
tipos-conteudo tipos-conteudo

JSON 

Âncora
conteudo-json conteudo-json

O formato padrão e recomendado de tipo de conteúdo, ou "Content-Type", a ser trafegado via APIs é "application/json".

É representado da seguinte maneira:

"content": {
				"application/json": {
						"schema": {
								"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SomeJsonSchema_2_006.json#/definitions/SomeObject"
						}
				}
			}

XML 

Âncora
conteudo-xml conteudo-xml

Em alguns casos pode existir a necessidade de utilizar "application/xml" , por ex: quando é exigido por legislação.  Nessa situação, as mesmas regras definidas nos tópicos anteriores continuam valendo, visto que estas estão relacionadas ao schema. (Se possível, evitar esse uso e sempre priorizar o JSON).

É representado de maneira muito similar ao JSON, porém trocando a notação do ContentType por "application/xml".

"content": {
				"application/xml": {
						"schema": {
								"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SomeJsonSchema_2_006.json#/definitions/SomeObject"
						}
				}
			}

Clique aqui sobre mais detalhes da representação do XML em OAS3

Arquivos Binários 

Âncora
conteudo-binario conteudo-binario

Para endpoints de arquivos binários, é obrigatório que o schema siga a seguinte estrutura (Com "type": "string" e "format":"binary") 

A notação do ContentType é sempre referente ao tipo de arquivo que o mesmo lida. No exemplo abaixo, um endpoint que resolve um arquivo de extensão ".png":

"content": {
				"image/png": {
						"schema": {
								"type":"string",
								"format": "binary"
						}
				}
			}

Clique aqui sobre mais detalhes da representação de arquivos binários em OAS3