...
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.
As 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 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 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 TTALK, armazenados no arquivo totvsApiTypesBase.json. Com isso, esses parameters não precisam ser implementados nos endpoints, mas sim propriamente referenciados na própria especificação de API.
...
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
(...)
"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"
}
}
}
}
(...)
|
...
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
...
