Histórico da Página

Índice

...

O que é uma API?

...

Âncora
definicao-api
definicao-api

Uma Interface de Programação de Aplicações é uma coleção de informações padronizadas estabelecida por um software que possibilita a utilização de suas funcionalidades por outros aplicativos. Com as informações persistidas em uma especificação de API, é possível enviar ou receber dados de uma aplicação sem que seja necessário entrar nos detalhes da implementação deste programa.

...

Para descrever uma API, se faz necessária uma especificação padronizada. O padrão utilizado para a construção das APIs TOTVS é o OpenAPI 3.0, o qual descreve um formato para definição de toda a API. Essa especificação é que define como serão evidenciados os endpoints e seus métodos, parâmetros de operações de entrada e saída, métodos de autenticação, metadados (tais como informações gerais, contato, licença e termos de uso), entre outros.

...

Criação de uma API

...

Âncora
criacao-api
criacao-api

Nesta documentação não entraremos em muitos detalhes sobre a criação dos OpenAPIs, uma vez que as As regras para o desenvolvimento de novos arquivos OpenAPIs APIs já estão especificadas no nosso Guia de Implementação de APIs.

Explicaremos mais o x-totvs. Mais detalhes sobre construção de APIs podem ser encontrados em Implementação de APIs com Mensagem Padronizada#Defini%C3%A7%C3%A3odaAPIeseusEndpoints

Todas as APIs já desenvolvidas podem ser encontradas em nosso repositório do GitHub.

3.2.1 totvsApiTypesBase

Uma ótima maneira de iniciar a criação de um novo arquivo OpenAPI é observando como outros documentos foram construídos. Para ter acesso a todas as APIs já desenvolvidas, basta acessar nosso repositório no GitHub.

totvsApiTypesBase
Âncora
api-types-base
api-types-base

Ao criar uma especificação de API TOTVS, é necessário preciso ter em mente que existem alguns métodos padrão types e parameters padronizados previamente criados pela equipe TTALK.Com isso, esses endpoints , armazenados no arquivo totvsApiTypesBase.json. Com isso, esses parameters não precisam ser implementados , apenas propriamente referenciados.

Retornar ao Fluxograma de Criação de Integrações

3.3 Diferenciação entre API e Schema

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 pontos. 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 é 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.

Anteriormente era possível que o schema fosse incluso diretamente na API, porém essa regra foi modificada. Para aprimorar a reusabilidade dos schemas, agora os arquivos JSON devem ser separados em API e JsonSchema. Esse modelo possibilita a utilização do protocolo transactions sem que haja a necessidade do desenvolvimento de uma API, caso essa configuração seja suficiente para suprir a necessidade e interesse do desenvolvedor. Como vantagem adicional, uma mesma API pode ser utilizada de formas diferentes, alterando somente o schema o qual ela faz referência.

Para uma melhor apresentação visual das APIs, foi criado o portal API Reference, onde todas as APIs desenvolvidas pelos segmentos TOTVS e aprovadas pelo comitê podem ser encontradas.

3.4 A propriedade "x-totvs"

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 ao qual está vinculado, adapter atrelado, se determinado verbo está disponível para aquele caminho, entre outros.

3.4.1 x-totvs em diferentes partes do OpenAPI

Abaixo está descrito o comportamento da propriedade x-totvs e o significado de cada uma de suas tags internas, utilizadas apenas no arquivo OpenAPI. Caso sua intenção seja entender o funcionamento do x-totvs no JsonSchema, visite a documentação de Definição da Mensagem no modelo JsonSchema.

3.4.1.1 x-totvs dentro da "info"

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

...

language	js
title	Exemplo
collapse	true

...

"do zero" nos endpoints, mas sim propriamente referenciados na própria especificação de API.

O exemplo a seguir traz um trecho do arquivo OpenAPI CustomerVendor v1, mostrando como ocorre essa referenciação.

Bloco de código

language	js
title	Exemplo
collapse	true

	(...)
	"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": {

...

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

...

					"$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:

Types:

Paging: responsável pelo mecanismo de paginação;
ErrorModel, ErrorModelBase e ErrorDetail: responsáveis por modelos de emissão de erros padronizados;
ExpandablesType: tipo de dado que define o cabeçalho expand.

Parameters:

Authorization: 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.

Aviso

title	Cuidados ao referenciar arquivos do GitHub

Ao referenciar qualquer arquivo do GitHub, tenha certeza que está obtendo o link apenas com o JSON e não o da árvore de arquivos. Para isso, ao entrar na página do arquivo desejado, clique em "Raw" e só então copie o link da página com o arquivo JSON.

Sinta-se à vontade para navegar por nossas APIs, tanto pelo API Reference quanto pelo nosso repositório do GitHub, e observar como estão referenciados seus respectivos types e parameters!

Retornar ao Fluxograma de Criação de Integrações

Diferenciação entre API e Schema
Âncora
diferenciacao-api-schema
diferenciacao-api-schema

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 aplicativos. 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.

Anteriormente era possível que o schema fosse incluso diretamente na API, porém essa regra foi modificada. Para aprimorar a reusabilidade dos schemas, agora os arquivos JSON devem ser separados em API e JsonSchema. Esse modelo possibilita a utilização do protocolo transactions sem que haja a necessidade do desenvolvimento de uma API, caso essa configuração seja suficiente para suprir a necessidade e interesse do desenvolvedor. Como vantagem adicional, uma mesma API pode ser utilizada de formas diferentes, alterando somente o schema o qual ela faz referência.

Para uma melhor apresentação visual das APIs, foi criado o portal API Reference, onde todas as APIs desenvolvidas pelos segmentos TOTVS e aprovadas pelo comitê podem ser encontradas.

A propriedade "x-totvs"
Âncora
xtotvs-api
xtotvs-api

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 em diferentes partes do OpenAPI
Âncora
xtotvs-diferentes-partes-api
xtotvs-diferentes-partes-api

Abaixo está descrito o comportamento da propriedade x-totvs e o significado de cada uma de suas tags internas, utilizadas apenas no arquivo OpenAPI. Caso sua intenção seja entender o funcionamento do x-totvs no JsonSchema, visite a documentação de Definição da Mensagem no modelo JsonSchema.

x-totvs dentro da "info"
Âncora
xtotvs-info
xtotvs-info

O exemplo a seguir é um trecho da API StockGroup

Bloco de código

language	js
title	Exemplo
collapse	true

(...)
"info": {
		"description": "API para informações de Grupo de Produto para Produtos TOTVS",
		"version": "1.000",
		"title": "Grupo de Produto",
		"contact": {
			"name": "T-Talk",
			"url": "api.totvs.com.br",
			"email": "[email protected]"
		},
		"x-totvs": {
			"messageDocumentation": {
				"name": "StockGroup",
                "description": "Cadastro de Grupo de Produto",
                "segment": "Construção e Projetos",
				"domain": "Planejamento"
			},
			"productInformation": [
				{
					"product": "Protheus",
					"contact": "[email protected]",
					"description": "Grupo de Produto",
					"adapter": "MATS035.prw"
				},
				{
					"product": "Logix",
					"contact": "[email protected]",
					"description": "Cadastro de Grupo de Produto",
					"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 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.

Aviso

title	Consistência na declaração de produtos

O validador automatizado no GitHub avalia a consistência dos 'products' declarados na info e nos paths. Caso um dado produto tenha implementado algum dos endpoints de uma API, ele deve ser declarado no 'productInformation' daquele endpoint e também na 'info'. Analogamente, um dado produto só pode estar declarado na 'info' se tiver implementado pelo menos um dos endpoints daquela API.

Sinta-se à vontade para navegar por nossas APIs, tanto pelo API Reference quanto pelo nosso repositório do GitHub, e observar como estão configurados seus respectivos x-totvs!

Clique aqui para retornar ao Fluxograma de Criação de Integrações

Identificar se o produto a ser integrado já está definido na documentação da API
Âncora
verificar-produto-definido
verificar-produto-definido

O API Reference é um portal que obtém os dados do JSON da API e os transfere para uma interface visual, tornando a navegação pelas APIs mais atrativa aos usuários. Para identificar quais produtos estão adaptados a uma determinada API, basta acessar o API Reference e identificar quais os produtos que se encontram explicitados (como demonstra a animação abaixo).

Image Added

No caso do exemplo acima, os produtos Protheus e Logix são os que estão configurados para a API em questão.

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

Clique aqui para retornar ao Fluxograma de Criação de Integrações

Editar "x-totvs" da API
Âncora
#editar-xtotvs-api
#editar-xtotvs-api

Caso a API já exista, porém não para o produto desejado pelo usuário, significa que há necessidade de adaptar o arquivo OpenAPI para que o produto em questão passe a ser especificado. Para tal, é necessário adicionar ao arquivo JSON da especificação da API novos objetos dentro do array "productInformation" nas propriedades x-totvs, na info e nos verbos dos paths.

Seguindo o mesmo exemplo da API apresentado nesta seção, a adição de um novo produto se daria da seguinte forma no cabeçalho (info):

Bloco de código

language	js
title	Exemplo
collapse	true

(...)
"info": {
		"description": "API para informações de Grupo de Produto para Produtos TOTVS",
		"version": "1.000",
		"title": "Grupo de Produto",
		"contact": {
			"name": "T-Talk",
			"url": "api.totvs.com.br",
			"email": "[email protected]"
		},
		"x-totvs": {
			"messageDocumentation": {
				"name": "StockGroup",
                "description": "Cadastro de Grupo de Produto",
                "segment": "Construção e Projetos",
				"domain": "Planejamento"
			},
			"productInformation": [
				{
					"product": "Protheus",
					"contact": "[email protected]",
					"description": "Grupo de Produto",
					"adapter": "MATS035.prw"
				},
				{
					"product": "Logix",
					"contact": "[email protected]",
					"description": "Cadastro de Grupo de Produto",
					"adapter": ""
				},
				{
					"product": "NovoProdutoTOTVS",
					"contact": "[email protected]",
					"description": "Cadastro de Grupo de Produto 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:

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"
						},
						{
							"product": "NovoProdutoTOTVS",
							"available": true,
							"note": "Alguma nota caso seja necessário",
							"minimalVersion": "12.1.23"
						}
					]
				}
(...)

Aviso
Vale lembrar que, seguindo o Fluxograma de Criação de Integrações, é necessário também checar se o JsonSchema utilizado pela API já está configurado para o produto em questão. Caso não esteja, é necessário editar o x-totvs também do schema.

Clique aqui para retornar ao Fluxograma de Criação de Integrações

Versionamento da API
Âncora
versionamento-api
versionamento-api

O versionamento de APIs que atuam sobre entidades com mensagem padronizada seguirá o padrão definido pelo guia de APIs, sendo independente da versão da mensagem padronizada. Entretanto, mudanças no modelo de dados implicam em mudança no contrato da API e, consequentemente, podem exigir alteração da versão da API.

Segundo o guia de APIs, a versão é composta do seguinte formato:

"v" + majorVersion + "." + minorVersion

onde majorVersion e minorVersion são números inteiros sequenciais, sem "zeros" complementares.

Exemplos de APIs versionadas:

/api/financeiro/v1/accountantAccounts
/api/educacional/v1.5/disciplines
/api/rh/v3.2/employees

As regras para versionamento das APIs, quando relacionadas a mensagem padronizada, são as seguintes:

Alterando-se a minorVersion da mensagem padronizada, deve-se alterar a minorVersion da API.
Alterando-se a majorVersion da mensagem padronizada, deve-se alterar a majorVersion da API.
Inclusão de verbos HTTP, ações ou filtros na API não alteram versão.
Alteração de comportamento de endpoint ou na forma de passar os parâmetros alteram versão da API, entretanto não é necessário replicar todos os outros endpoints da API para a nova versão.

Exemplos de versionamento
Âncora
exemplo-versionamento
exemplo-versionamento

Para tornar mais claro como versionar as APIs baseadas em mensagem padronizada, colocaremos a seguir um caso de uso.

Mensagem padronizada Request, utilizada para CRUD de requisições de estoque ou compras.
Mensagem padronizada CancelRequest, utilizada para cancelamento de requisições.

Na versão inicial da API temos os seguintes endpoints, todos baseados na versão 1.000 da transação Request:

Bloco de código

title	APIs v1

GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}

Em um momento posterior, foi liberada a operação de cancelamento da requisição, utilizando a transação CancelRequest, versão 1.000, conforme abaixo:

Bloco de código

title	Novo Endpoint na API v1

POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest

A API teve mais um endpoint adicionado, porém os demais endpoints não tiveram alteração de contrato. Neste caso, a versão do novo endpoint permanece igual a dos demais.

Consideremos agora, que a API teve alteração na versão da transação Request, evoluindo para a versão 1.001. Neste caso, devemos alterar a versão da API, modificando o minorVersion, conforme segue:

Bloco de código

title	APIs v1.1

GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}

Agora, teremos disponíveis os seguintes endpoints (observe que o endpoint de cancelamento permaneceu na v1):

Bloco de código

title	Endpoints disponíveis

- V1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- V1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}

Seguindo com o nosso exemplo, vamos considerar agora, que o endpoint de cancelamento precisa, obrigatoriamente, receber um parâmetro de query. Isso altera consideravelmente o comportamento do endpoint. Sendo assim, o incremento deve ocorrer na majorVersion do endpoint, conforme segue.

Bloco de código

title	Novo endpoint v2

POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue

Com isso, teremos o seguinte cenário de APIs:

Bloco de código

title	Endpoints disponíveis

- v1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- v1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}
- v2
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue

Depois de um certo tempo, pode ser necessário reorganizar o cenário das APIs disponíveis, concentrando em uma única versão todas as alterações realizadas. Neste caso, aproveitando a evolução da versão da transação cancelRequest para 2.000 (que afetaria apenas um endpoint), podemos ter uma nova majorVersion abrangendo os demais endpoints da API:

Bloco de código

title	Endpoints disponíveis

- v1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- v1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}
- v2
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue
- v3
GET /api/manufacturing/stock/v3/requests
GET /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/requests
PUT /api/manufacturing/stock/v3/requests/{requestId}
DELETE /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/request/{requestId}/cancelRequest?mandatoryParam=someValue

Aviso

title	Atenção

Após a reorganização da API pode ser necessário excluir a versão anterior e neste caso, a depreciação deve ser feita conforme politica de cada linha de produto.

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:

Bloco de código

language	js

"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".

Bloco de código

language	js

"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":

Bloco de código

language	js

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

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

...

- - 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.

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"

						}

					]

				}

(...)

...

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.

Sinta-se à vontade para navegar por nossas APIs, tanto pelo API Reference quanto pelo nosso repositório do GitHub, e observar como estão configurados seus respectivos x-totvs!

Clique aqui para retornar ao Fluxograma de Criação de Integrações

3.4.2 Identificar se o produto a ser integrado já está definido na documentação da API

O API Reference é um portal que obtém os dados do JSON da API e os transfere para uma interface visual, tornando a navegação pelas APIs mais atrativa aos usuários. Para identificar quais produtos estão adaptados a uma determinada API, basta acessar o API Reference e identificar quais os produtos que se encontram explicitados (como demonstra a animação abaixo).

Image Removed

No caso do exemplo acima, os produtos Protheus e Logix são os que estão configurados para a API em questão.

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

Clique aqui para retornar ao Fluxograma de Criação de Integrações

3.4.3 Editar "x-totvs" da API

Caso a API já exista, porém não para o produto desejado pelo usuário, significa que há necessidade de adaptar o arquivo OpenAPI para que o produto em questão passe a ser especificado. Para tal, é necessário adicionar ao arquivo JSON da especificação da API novos objetos dentro do array "productInformation" nas propriedades x-totvs, na info e nos verbos dos paths.

Seguindo os exemplos apresentados na seção 3.4.1, a adição de um novo produto se daria da seguinte forma no cabeçalho (info):

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": ""

				},
				{


					"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:

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"

						},
						{

							"product": "NovoProdutoTOTVS",

							"available": true,

							"note": "Alguma nota caso seja necessário",

							"minimalVersion": "12.1.23"


						}

					]

				}

(...)

Aviso
Vale lembrar que, seguindo o Fluxograma de Criação de Integrações, é necessário também checar se o JsonSchema utilizado pela API já está configurado para o produto em questão. Caso não esteja, é necessário editar o x-totvs também do schema.

...

Outras documentações

Implementação de APIs com Mensagem Padronizada

Páginas filhas

Versões comparadas

Versão antiga 32

Nova versão Atual

Chave

O que é uma API?

Âncora
definicao-api
definicao-api

Criação de uma API

Âncora
criacao-api
criacao-api

3.2.1 totvsApiTypesBase

totvsApiTypesBase
Âncora
api-types-base
api-types-base

3.3 Diferenciação entre API e Schema

3.4 A propriedade "x-totvs"

3.4.1 x-totvs em diferentes partes do OpenAPI

3.4.1.1 x-totvs dentro da "info"

Diferenciação entre API e Schema
Âncora
diferenciacao-api-schema
diferenciacao-api-schema

A propriedade "x-totvs"
Âncora
xtotvs-api
xtotvs-api

x-totvs em diferentes partes do OpenAPI
Âncora
xtotvs-diferentes-partes-api
xtotvs-diferentes-partes-api

x-totvs dentro da "info"
Âncora
xtotvs-info
xtotvs-info

x-totvs dentro dos verbos dos endpoints
Âncora
xtotvs-paths
xtotvs-paths

Identificar se o produto a ser integrado já está definido na documentação da API
Âncora
verificar-produto-definido
verificar-produto-definido

Editar "x-totvs" da API
Âncora
#editar-xtotvs-api
#editar-xtotvs-api

Versionamento da API
Âncora
versionamento-api
versionamento-api

Exemplos de versionamento
Âncora
exemplo-versionamento
exemplo-versionamento

Tipos de Conteúdo
Âncora
tipos-conteudo
tipos-conteudo

JSON
Âncora
conteudo-json
conteudo-json

XML
Âncora
conteudo-xml
conteudo-xml

Arquivos Binários
Âncora
conteudo-binario
conteudo-binario

3.4.1.2 x-totvs dentro dos verbos dos endpoints

3.4.2 Identificar se o produto a ser integrado já está definido na documentação da API

3.4.3 Editar "x-totvs" da API

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 32

Nova versão Atual

Chave

O que é uma API?

Âncoradefinicao-apidefinicao-api

Criação de uma API

Âncoracriacao-apicriacao-api

3.2.1 totvsApiTypesBase

totvsApiTypesBase Âncoraapi-types-baseapi-types-base

3.3 Diferenciação entre API e Schema

3.4 A propriedade "x-totvs"

3.4.1 x-totvs em diferentes partes do OpenAPI

3.4.1.1 x-totvs dentro da "info"

Diferenciação entre API e Schema Âncoradiferenciacao-api-schemadiferenciacao-api-schema

A propriedade "x-totvs" Âncoraxtotvs-apixtotvs-api

x-totvs em diferentes partes do OpenAPI Âncoraxtotvs-diferentes-partes-apixtotvs-diferentes-partes-api

x-totvs dentro da "info" Âncoraxtotvs-infoxtotvs-info

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

Identificar se o produto a ser integrado já está definido na documentação da API Âncoraverificar-produto-definidoverificar-produto-definido

Editar "x-totvs" da API Âncora#editar-xtotvs-api#editar-xtotvs-api

Versionamento da API Âncoraversionamento-apiversionamento-api

Exemplos de versionamento Âncoraexemplo-versionamentoexemplo-versionamento

Tipos de Conteúdo Âncoratipos-conteudotipos-conteudo

JSON Âncoraconteudo-jsonconteudo-json

XML Âncoraconteudo-xmlconteudo-xml

Arquivos Binários Âncoraconteudo-binarioconteudo-binario

3.4.1.2 x-totvs dentro dos verbos dos endpoints

3.4.2 Identificar se o produto a ser integrado já está definido na documentação da API

3.4.3 Editar "x-totvs" da API

Âncora
definicao-api
definicao-api

Âncora
criacao-api
criacao-api

totvsApiTypesBase
Âncora
api-types-base
api-types-base

Diferenciação entre API e Schema
Âncora
diferenciacao-api-schema
diferenciacao-api-schema

A propriedade "x-totvs"
Âncora
xtotvs-api
xtotvs-api

x-totvs em diferentes partes do OpenAPI
Âncora
xtotvs-diferentes-partes-api
xtotvs-diferentes-partes-api

x-totvs dentro da "info"
Âncora
xtotvs-info
xtotvs-info

x-totvs dentro dos verbos dos endpoints
Âncora
xtotvs-paths
xtotvs-paths

Identificar se o produto a ser integrado já está definido na documentação da API
Âncora
verificar-produto-definido
verificar-produto-definido

Editar "x-totvs" da API
Âncora
#editar-xtotvs-api
#editar-xtotvs-api

Versionamento da API
Âncora
versionamento-api
versionamento-api

Exemplos de versionamento
Âncora
exemplo-versionamento
exemplo-versionamento

Tipos de Conteúdo
Âncora
tipos-conteudo
tipos-conteudo

JSON
Âncora
conteudo-json
conteudo-json

XML
Âncora
conteudo-xml
conteudo-xml

Arquivos Binários
Âncora
conteudo-binario
conteudo-binario