TOTVS Agro : APIs / Serviços Públicos
Esta página apresenta e descreve a técnica (framework, ferramental e tecnologias) utilizados para o desenvolvimento de APIs padrões (serviços públicos) em produtos TOTVS Agro, com foco em TOTVS Agro Bioenergia.
Este material menciona "TOTVS Agro API Hub", como o framework, ferramental e tecnologias necessárias para a construção e a exposição de APIs padrões (serviços públicos), bem como o "TOTVS Agro Middleware", que representa um serviço/componente intermediário para camada de adaptadores (adapter), como transformações, regras de negócio e outras implementações específicas.
Introdução / Contextualização (APIs e Integrações) | TOTVS Agro
TOTVS Agro API Hub | Modelo e tecnologia padronizados para novas APIs em TOTVS Agro
O projeto ta-api-hub é uma ferramenta desenvolvida para facilitar a exposição de APIs de forma facilitada e padronizada, com base na estrutura de dados das soluções TOTVS Agro (Bioenergia), possibilitando também customizar as APIs via cadastro de queries obtendo maior flexibilidade.
O Cadastro de Entidades e Queries definirá a configuração / exposição e comportamento das APIs, bem como os métodos HTTPs habilitados, tabelas e colunas utilizadas, atributos da estrutura JSON relacionada, validações básicas, como tamanho, tipo de dado, obrigatoriedade, aplicação de máscara, validação de existência de entidade relacionada.
Cadastro de Entidade
A disponibilização das APIs no ta-api-hub é realizada via cadastro de entidades, definida e baseada na estrutura de dados da aplicação, conforme os cadastros a seguir:
Endpoint para entidades:
Estrutura de dados:
{ "id": "UUID", "name": "nomeEntidade", "description": "Descrição da Entidade", "product": "BIOENERGIA", "entityTable": "NOME_DA_TABELA", "lastUpdate": "2024-06-20T12:58:05.401", "entityDeList": [ { "id": "UUID", "fieldName": "nomeDoCampo", "description": "Descricao do Campo", "tableColumn": "NOME_DA_COLUNA", "columnType": "STRING", "columnSize": 50, "columnRequired": true, "columnMask": null, "columnPk": true, "tableFk": null, "columnFk": null, "filter": true }, ... ], "entityChildList": [ { "id": "UUID", "entityChild":{} "entityChildType": "" }, ... ], "entityApi": { "id": "UUID", "pathUrl": "entidades", "apiVersion": "v1", "businessClass": "", "enableGet": true, "enablePost": true, "enablePut": true, "enableDelete": true, "enabled": true, "lastUpdate": "2024-06-20T12:58:05.401" } }
Header
- id: Campo identificador único / chave do header (UUID)
- name: Nome da entidade.
- description: Descrição da entidade.
- product: Produto associado à entidade (BIOENERGIA / MULTICULTIVO).
- entityTable: Nome da tabela no banco de dados
- lastUpdate: Data/hora da última atualização.
Detalhes (Lista)
- id: Campo identificador único / chave do detalhe (UUID)
- fieldName: Nome do campo de acordo com a estrutura de dados JSON.
- description: Descrição do campo
- tableColumn: Nome da coluna correspondente no banco de dados
- columnType: Tipo de dado da coluna.
- columnSize: Tamanho da coluna.
- columnMask: Máscara de formatação.
- columnRequired: Flag para indicar se o campo é obrigatório.
- columnPk: Flag para indicar se a coluna é uma chave primária.
- tableFk: Nome da tabela quando atributo for FK
- columnFk: Nome da coluna quando atributo for FK
- filter: Flag para indicar se a coluna pode ser usada como filtro para método GET.
Entidades Filhas (Lista)
- id: Campo identificador único / chave da entidade filha(UUID)
- entityChild: Entidade, previamente cadastrada, que será a entidade filha da entidade principal
- entityChildType: Tipo da entidade filha (ELEMENT / LIST ).
Entidade API - Indica que a entidade será exposta via API
- id: Campo identificador único / chave da entidade API (UUID)
- pathUrl: Path da url da entidade (Ex: instancias)
- apiVersion: Versão da API (Ex: V1)
- businessClass: Classe de negócio para validações customizadas.
- enableGet: Flag para indicar se a operação GET está habilitada.
- enablePost: Flag para indicar se a operação POST está habilitada.
- enablePut: Flag para indicar se a operação PUT está habilitada.
- enableDelete: Flag para indicar se a operação DELETE está habilitada.
- enabled: Flag para indicar se a API está habilitada.
- lastUpdate: Campo interno para indicar data/hora da última atualização.
Sumário de Entidades
Diponibilizado endpoint para consulta do sumário de entidades cadastradas.
Método GET
[ { "id": "a3427359-dc2f-4245-915c-972cfa2b25af", "name": "parametro", "description": "Parametros", "path": "api/entity/v1/parametros", "enableGet": true, "enablePost": false, "enablePut": false, "enableDelete": false, "enabled": true, "details": [ { "id": "d4a0e418-9423-4516-940b-03d4de5b9800", "fieldName": "secao", "description": "Seção", "columnRequired": false, "columnPk": false, "filter": true }, { "id": "6c076bf9-2456-4b46-b43a-1296047be0ab", "fieldName": "entrada", "description": "Entrada", "columnRequired": false, "columnPk": false, "filter": true }, { "id": "87c60f83-7592-44d7-9005-43589a05dcda", "fieldName": "tipo", "description": "Tipo", "columnRequired": false, "columnPk": false, "filter": false }, { "id": "2fe199e6-3209-463b-af31-1ef20794e2b5", "fieldName": "valor", "description": "Valor", "columnRequired": false, "columnPk": false, "filter": false }, { "id": "0611d39b-42f8-4044-86db-bb9e6336c998", "fieldName": "descricao", "description": "Descrição", "columnRequired": false, "columnPk": false, "filter": true }, { "id": "828fcde4-9d47-4270-b1a7-82f35f148517", "fieldName": "validos", "description": "Valores Válidos", "columnRequired": false, "columnPk": false, "filter": false }, { "id": "a4802480-ed33-46b6-91c1-df0e442672ac", "fieldName": "instancia", "description": "Instancia", "columnRequired": false, "columnPk": false, "filter": true } ] }, ... ]
Cadastro de Queries
A disponibilização das APIs no ta-api-hub também podes ser realizada via cadastro de queries, definida e baseada na estrutura de dados da aplicação, conforme os cadastros a seguir:
Endpoint para queries:
Estrutura de dados:
[ { "id": "UUID", "name": "nomeEstruturaDados", "description": "Descrição", "product": "BIOENERGIA", "pathUrl": "queries", "lastUpdate": "2024-06-20T04:58:05.401", "queryDeList": [ { "id": "UUID", "apiVersion": "v1", "query": "SELECT CD_SAFRA, DE_SAFRA, DE_COMP_TBL FROM SAFRAS WHERE CD_SAFRA = ::codigo", "databaseType": "ORACLE", "httpMethod": "GET", "enabled": true }, ... ], "queryFieldsList": [ { "fieldName": "codigo", "tableColumn": "CD_SAFRA", "columnType": "INTEGER", "columnSize": 5, "columnRequired": true, "columnMask": null, "columnPk": true, "tableFk": null, "columnFk": null, "id": "697e73b0-9520-4819-a6dc-350172fd9792" }, ... ] } ]
Query Header
- id: Campo identificador único / chave do header (UUID)
- name: Nome da estrutura de dados.
- description: Descrição.
- product: Produto associado à entidade (BIOENERGIA / MULTICULTIVO).
- pathUrl: Path da url da entidade (Ex: instancias)
- lastUpdate: Data/hora da última atualização.
Query Detail
- id: Campo identificador único / chave do detalhe (UUID)
- apiVersion: Versão da API (Ex: V1)
- query: Instrução SQL a ser executada na chamada da API (Select, Insert, Update, Delete)
- databaseType: Tipo do banco de dados (ORACLE, SQL_SERVER)
- httpMethod: Método HTTP (GET, POST, PUT, DELETE)
- enabled: Flag para indicar se a API está habilitada.
Query Field
- id: Campo identificador único / chave do campo (UUID)
- fieldName: Nome do campo de acordo com a estrutura de dados JSON.
- tableColumn: Nome da coluna correspondente no banco de dados
- columnType: Tipo de dado da coluna.
- columnSize: Tamanho da coluna.
- columnMask: Máscara de formatação.
- columnRequired: Flag para indicar se o campo é obrigatório.
- columnPk: Flag para indicar se a coluna é uma chave primária.
- tableFk: Nome da tabela quando atributo for FK
- columnFk: Nome da coluna quando atributo for FK
Sumário de Queries
Diponibilizado endpoint para consulta do sumário de queries cadastradas.
Método GET
[ { "id": "ce429b8e-e284-44c7-a37c-d7dfbb0b7aed", "name": "safra", "description": "Safras", "details": [ { "id": "56c53717-727b-4b33-bfcd-57b6f85d20df", "query": "SELECT CD_SAFRA, DE_SAFRA, DE_COMP_TBL FROM SAFRAS WHERE CD_SAFRA = ::codigo", "httpMethod": "GET", "path": "/api/v1/safras", "enabled": true }, { "id": "bf3bbf43-cb35-4cc7-8c50-4c441772d4ce", "query": "INSERT INTO SAFRAS(CD_SAFRA, DE_SAFRA, DE_COMP_TBL) VALUES (::codigo,::descricao,::complemento)", "httpMethod": "POST", "path": "/api/v1/safras", "enabled": true }, { "id": "23856856-2b8b-48a4-988d-38a20dba7209", "query": "UPDATE SAFRAS SET DE_SAFRA = ::descricao, DE_COMP_TBL = ::complemento WHERE CD_SAFRA = ::codigo", "httpMethod": "PUT", "path": "/api/v1/safras", "enabled": true }, { "id": "4ddbba69-91a3-4f6e-92c3-92cd24a8619a", "query": "DELETE FROM SAFRAS WHERE CD_SAFRA = ::codigo", "httpMethod": "DELETE", "path": "/api/v1/safras", "enabled": true } ] } ]
Consumo das APIs
Composição da URL da API
A URL para as entidades e queries cadastradas é composta confome conforme configurado no cadastro da EntityAPI e QueryHe/QueryDe, para os campos apiVersion e pathUrl, conforme demonstrado a seguir:
- Entidade: http://IP:PORTA/api/entity/[apiVersion]/[pathUrl]
- Query: http://IP:PORTA/api/query/[apiVersion]/[pathUrl]
Os métodos HTTPs que podem ser utilizados são GET, POST, PUT e DELETE, e estarão disponíveis conforme configurados em cada modelo de exposição de APIs.
Segurança / Autenticação
A autenticação/autorização das APIs de integração utiliza o OAuth 2.0 Client Credentials Grant, sendo o método mais utilizado e também um fluxo de autorização projetado especificamente para integrações entre sistemas backend.
Principais vantagens:
- As credenciais do cliente são mantidas seguras e o token de acesso é temporário e pode ser revogado.
- Suporta múltiplos clientes e permite o controle granular de permissões e acessos.
- Amplamente adotado e suportado por muitos provedores de serviços, garantindo interoperabilidade entre sistemas diferentes.
Fluxo:
- Cliente realiza requisição para o servidor de autorização com as credenciais Client Id e Client Secret;
- Servidor verifica as credenciais, estando válidas retorno um token de acesso;
- Cliente utiliza o token de acesso para autenticar as requisições feitas para o servidor de recursos;
TOTVS Agro Middleware | Componente intermediário das APIs públicas do TOTVS Agro API Hub
Este tópico visa descrever o processo e as tecnologias utilizadas no desenvolvimento do TOTVS Agro Middleware. Utilizamos Java 21 pela sua robustez e eficiência, aliado à versão mais recente do Spring Framework, que oferece uma vasta gama de funcionalidades para a construção de aplicações modernas. Para simplificar a configuração, utilizamos traduções de XML baseadas em anotações, permitindo uma manutenção mais intuitiva e menos redundante. Além disso, implementamos um sistema de controle de filas lógicas e monitoramento de status para assegurar a integridade e a eficiência dos processos assíncronos. Essa combinação de tecnologias e práticas nos permite desenvolver uma aplicação escalável, segura e de alto desempenho.
Vídeos para exemplificar o fluxo completo da Integração entre Fila EAI x TOTVS Agro Middleware x TOTVS Agro API Hub
Parte 1
Parte 2
Framework e Engenharia TOTVS Agro
Release 12.1.2406 (Junho/2024)