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.
É de grande interesse para a TOTVS que aplicações externas consigam se comunicar com seus produtos de maneira facilitada. Por meio da implementação de uma API, é possível que outras aplicações obtenham dados internos dos produtos TOTVS, apenas enviando uma requisição HTTP para o endereço devidamente descrito na especificação da API.
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.
Nesta documentação não entraremos em muitos detalhes sobre a criação dos OpenAPIs, uma vez que as regras para o desenvolvimento de novos arquivos APIs já estão especificadas no nosso Guia de APIs. 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.
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.
O exemplo a seguir traz um trecho do arquivo OpenAPI CustomerVendor v1, mostrando como ocorre essa referenciação.
(...)
"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:
Types:
Parameters:
Para maiores detalhes sobre uso dos cabeçalhos padronizados, visite nosso Guia de APIs.
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
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 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.
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.
O exemplo a seguir é um trecho da API UnitOfMeasure v2.
(...)
"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.
O exemplo a seguir também é um trecho da API UnitOfMeasure v2.
(...)
"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.
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
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).
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
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 na seção 3.4.1, a adição de um novo produto se daria da seguinte forma no cabeçalho (info):
(...)
"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:
(...)
"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"
}
]
}
(...) |
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
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:
As regras para versionamento das APIs, quando relacionadas a mensagem padronizada, são as seguintes: