Nesta página, é descrita a arquitetura de componentes e tecnologia utilizadas pelo TOTVS Agro API Hub, como forma de apresentar e elucidar a estrutura unificada e padronizada desenvolvida para expor as APIs do ecossistema TOTVS Agro Bioenergia. Este hub atua como uma camada de abstração e governança técnica centralizada, fornecendo endpoints RESTful consistentes, documentação interativa via Swagger/OpenAPI, gestão de ciclos de vida (API Lifecycle) e mecanismos robustos de segurança e autenticação (como OAuth 2.0). Seu propósito fundamental é simplificar e escalar a integração entre os sistemas corporativos (como ERPs, plataformas de trading, aplicações de campo e ferramentas de análise) e a suite de soluções TOTVS para o agronegócio, promovendo interoperabilidade, reduzindo a complexidade no desenvolvimento e acelerando a inovação digital no setor de bioenergia.

Diagrama Arquitetural

Elaborar um diagrama arquitetural que demonstre, de forma facilitada, o API Hub e sua relação com outros elementos (banco de dados Bioenergia Oracle, banco de dados API Hub PostgreSQL, setas/linhas com relação entre componentes na arquitetura, comunicação externa (se houver), uso do WSW e o máximo de detalhes para explicar em uma ou mais imagens, o papel de API Hub e seus usos;
Utilizar de Excalidraw ou Miro ou PPT;
Avaliar o que pode ser aproveitado de ideia de outras docs neste sentido:
Instalação TOTVS Agro Connector Client - TOTVS AGRO - TDN
https://tdn.totvs.com/pages/viewpage.action?pageId=570365032
TOTVS Agro Connector - TOTVS AGRO - TDN
https://tdn.totvs.com/display/PA/TOTVS+Agro+Connector

Consumo das APIs

O API-Hub oferece dois modelos de URL que podem ser utilizados. A seguir, apresentamos cada um deles com suas respectivas características e aplicações.

- 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, DELETE e PATCH (modelo entity), e estarão disponíveis conforme configurados em cada modelo de exposição de APIs.

Lista de apis

draw.io Diagram

border	true

diagramName	APIs Padrões TOTVS Agro Bioenergia
simpleViewer	false
width
links	auto
tbstyle	top
lbox	true
diagramWidth	1270
revision	4

...

Segurança / Autenticação

A autenticação/autorização das APIs de integração

...

utiliza 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;

Características Técnicas

Requisitos

...

Consumo das APIs

O TOTVS Agro API Hub

...

disponibiliza dois modelos de URL para acesso às APIs: Entidade e Query. Cada modelo possui características específicas e métodos GET, POST, PUT, DELETE e PATCH, conforme configurado para cada API. As definições e a estrutura de cada API estão disponíveis para consulta na página APIs Padrão TOTVS Agro Bioenergia

O TOTVS Agro API Hub disponibiliza dois modelos de URL para acesso às APIs: Entidade e Query. Cada modelo possui características específicas e suporta métodos HTTP ou HTTPs como GET, POST, PUT, DELETE e PATCH, conforme configurado para cada API.

- Entidade - Utilizado para operações diretas sobre entidades do sistema

Estrutura base de acesso: http://IP:PORTA/api/entity/[apiVersion]/[pathUrl]
Exemplo de uma Entidade: http://127.0.0.1:8080/api/entity/v1/unidadesMedidaInd?page=1&pagesize=1

- Query - Destinado a consultas e à obtenção de dados específicos previamente definidos pela equipe de produto

Estrutura base de acesso: http://IP:PORTA/api/query/[apiVersion]/[pathUrl]
Exemplo de uma Entidade: http://127.0.0.1:8080/api/query/v1/baixaConsumiveisMativ?page=1&pagesize=5

Informações

title	APIs Padrões - TOTVS Agro Bioenergia

As definições detalhadas e a estrutura de cada API podem ser consultadas na página 🔗APIs Padrão TOTVS Agro Bioenergia.

Perguntas Frequentes (FAQ)

Nesta seção, você encontrará orientações para configurar o TOTVS Agro API Hub, por meio do link 🔗Orientações e FAQ - TOTVS Agro API HUB

Requisitos de Hardware

Recomendado (equivalente

Requisitos

Requisitos de Hardware

Recomendado (Equivalente ou superior): CPU Intel® Xeon® Gold 5415+ Processor (22.5M Cache, 2.90 GHz) / 4 vCPU
Recomendado (inicial): 12 GB de RAM disponível (somente para TOTVS Agro API Hub + PostgreSQL);
Recomendado: 30 GB espaço em disco disponível (somente para TOTVS Agro API Hub + PostgreSQL);

...

- Os requisitos de hardware (memória RAM e espaço em disco) podem ser superiores aos inicialmente recomendados, devido ao volume de dados monitorado/integrado entre as aplicações que estão sendo integradas por ele (para isto, será necessário monitorar e validar a necessidade de subida destes requisitos durante uma homologação);
- Na instalação, os componentes/serviços do TOTVS API Hub devem estar o mais próximo das bases de dados de Oracle/Bioenergia, reduzindo assim questões de latência e/ou instabilidade com a base de dados monitorada/sincronizada;
- Também recomendamos a separação entre ambiente/infraestrutura de TOTVS Agro API Hub e demais aplicações (por exemplo, TOTVS Agro Bioenergia, TOTVS Agro PIMSServer e/ou TOTVS Agro Portal Agrícola) - desta forma, seguir a recomendação mencionada no quadro "Infraestrutura e ambientes" (abaixo);
- A latência (ping) entre ambiente de instalação dos componentes/serviços do TOTVS Agro API Hub e as bases de dados deve ser inferior aos valores recomendados (em milissegundos);
  - ```
  "<= 3 ms": Uso de "ping" via comando "ping HOSTNAME";
```
  - Importante: O teste de ping não reflete diretamente na latência durante a comunicação com o banco de dados, mas sim na indicação geral da conectividade/latência entre cliente e servidor de banco de dados.
- ```
"<= 3 ms": Uso de "tnsping" via comando "tnsping SERVICE_NAME";
```
    - Importante: O teste com tnsping não reflete diretamente na latência durante a comunicação com o banco de dados, mas sim para testar a latência na resolução de nomes de serviço e na conexão inicial com o banco de dados Oracle.
- A latência durante as operações de banco de dados entre ambiente de instalação dos componentes/serviços do TOTVS Agro API Hub e as bases de dados deve ser inferior aos valores recomendados
  - "<= 1 ms": Para execução de consultas simples, como exemplo:
    - ```
    Oracle: "SELECT 1 FROM DUAL"
```

Informações

title	Requisitos recomendados

Esta página apresenta os requisitos recomendados para uma instalação e configuração padrões.

⚠️ Como TOTVS Agro API Hub é uma plataforma de comunicação com TOTVS Agro Bioenergia, tais requisitos podem ser revistos e sinalizados aos clientes, a qualquer momento, pois seu uso (TOTVS Agro API Hub) tem relação com volume de dados e poder computacional necessário para chamadas HTTP/REST.

Informações

title	Infraestrutura e ambientes

Recomenda-se a separação entre ambiente/servidor (TOTVS Agro API Hub) - com seus componentes (por exemplo, PostgreSQL) e ambientes/servidores das demais soluções/ferramentas TOTVS Agro que farão uso da plataforma.

Por exemplo:

1 ambiente/servidor para TOTVS Agro API Hub + 1 ambiente/servidor para TOTVS Agro Bioenergia (avaliar requisitos recomendados separados); ou
1 ambiente/servidor para TOTVS Agro API Hub + 1 ambiente/servidor para TOTVS Agro PIMSServer (avaliar requisitos recomendados separados);

* Em situações específicas (desde que alinhado com time TOTVS Agro), tais ambientes/servidores podem ser unificados, desde que os requisitos separados sejam atendidos em sua totalidade. Importante mencionar que a separação física/lógica destes ambientes/servidores otimiza aspectos de análise, investigação, disponibilidade e otimização de configurações.

Requisitos de Software

Sistema Operacional

O TOTVS Agro API Hub está homologado para execução no sistema operacional Windows Server. A seguir, são descritas as versões do Windows atualmente suportadas

- Windows Server 2019 Standard;
- Windows Server 2022 Standard;

Plataforma Java (JDK/JRE)

O TOTVS Agro API Hub faz uso da plataforma Java, como ambiente de execução, na versão OpenJDK 21.0.2 (versão opensource do Java, que não demanda por licenciamento).

O conjunto de binários utilizado é fornecido durante a instalação e configuração do TOTVS Agro API Hub.

Requisitos de Banco de Dados

TOTVS Agro API HUB

O TOTVS Agro API Hub utiliza o banco de dados PostgreSQL para armazenar sua estrutura

...

PostgreSQL 15

...

Bases de dados - TOTVS Agro API Hub

Totvs custom tabs box

tabs	1 - Oracle, 2 - Postgres
ids	ORACLE,POSTGRES

Totvs custom tabs box items

default	yes
referencia	ORACLE

Versão
- Versão mínima requerida é Oracle 19c.
Definição do Banco
- Banco de Dados Oracle - Recomendações & Parametrização

Bloco de código

language	sql
theme	Confluence
title	Criação das seguintes tablespaces (Caso não exista)
linenumbers	true

CREATE TABLESPACE PIMS_DATA DATAFILE '/u01/oradata/orcl/PIMS_DATA.ORA' SIZE 20G;

CREATE TABLESPACE PIMS_INDX DATAFILE '/u01/oradata/orcl/PIMS_INDEX.ORA' SIZE 20G;

Bloco de código

language	sql
theme	Confluence
title	Permissões (Oracle / TOTVS Agro API Hub)
linenumbers	true

CREATE USER {{DB_USUARIO_API_HUB_BIO}} IDENTIFIED BY "{{DB_SENHA_API_HUB}}" DEFAULT TABLESPACE PIMS_DATA TEMPORARY TABLESPACE TEMP PROFILE DEFAULT ACCOUNT UNLOCK;  
 
GRANT CONNECT                    TO {{DB_USUARIO_API_HUB}};
GRANT "RESOURCE                  TO {{DB_USUARIO_API_HUB}};
GRANT UNLIMITED TABLESPACE       TO {{DB_USUARIO_API_HUB}};
GRANT DEBUG CONNECT SESSION      TO {{DB_USUARIO_API_HUB}};
GRANT DEBUG ANY PROCEDURE        TO {{DB_USUARIO_API_HUB}};  
GRANT CREATE SYNONYM             TO {{DB_USUARIO_API_HUB}};
GRANT CREATE VIEW                TO {{DB_USUARIO_API_HUB}};
GRANT CREATE PROCEDURE           TO {{DB_USUARIO_API_HUB}}; 
GRANT CREATE TRIGGER             TO {{DB_USUARIO_API_HUB}};
GRANT CREATE SEQUENCE            TO {{DB_USUARIO_API_HUB}}; 
GRANT CREATE MATERIALIZED VIEW   TO {{DB_USUARIO_API_HUB}};
GRANT UNLIMITED TABLESPACE       TO {{DB_USUARIO_API_HUB}};
 
ALTER USER {{DB_USUARIO_API_HUB}} QUOTA UNLIMITED ON PIMS_DATA;
ALTER USER {{DB_USUARIO_API_HUB}} QUOTA UNLIMITED ON PIMS_INDX;

Totvs custom tabs box items

default	no
referencia	POSTGRES

Versão
- Postgres 15 (recomendado)
Definição do Banco
- Encoding : UTF8
- Collation : pt_BR.UTF-8
- Character Type : pt_BR.UTF-8
- Em sistema operacional Windows Server, a Collation e Character Type devem ser utilizadas como Portuguese_Brazil.1252 ou English_United States.1252

Bloco de código

language	sql
theme	Confluence
title	Permissões (PostgreSQL / TOTVS Agro API Hub)
linenumbers	true

GRANT CONNECT ON DATABASE <NOME_DO_BANCO> TO

...

<NOME_DO_USUARIO>;,

...


GRANT CREATE, USAGE ON SCHEMA <NOME_DO_SCHEMA> TO <NOME_DO_USUARIO>;,

...


GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA <NOME_DO_SCHEMA> TO <NOME_DO_USUARIO>;,

...


ALTER DEFAULT PRIVILEGES IN SCHEMA <NOME_DO_SCHEMA> GRANT ALL ON TABLES TO <NOME_DO_USUARIO>;,

...


GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA <NOME_DO_SCHEMA> TO <NOME_DO_USUARIO>;,

...


ALTER DEFAULT PRIVILEGES IN SCHEMA <NOME_DO_SCHEMA> GRANT ALL ON SEQUENCES TO <NOME_DO_USUARIO>;,

...


ALTER DEFAULT PRIVILEGES IN SCHEMA <NOME_DO_SCHEMA> GRANT ALL ON FUNCTIONS TO <NOME_DO_USUARIO>;

TOTVS Agro Bioenergia

Bases de dados - externas

É possível utilizar bases de dados de múltiplos produtos externos (mínimo de 1 e máximo de 3), como TOTVS Agro Bioenergia (obrigatório), Indústria MI (opcional) e Indústria PI (opcional). Para o processo de

...

habilitação (instalação, configuração e uso) do API Hub com o TOTVS Agro Bioenergia, a versão mínima requerida do banco de dados é Oracle

...

19c.

- Oracle
  - Banco de dados homologados
- - - TOTVS Agro Bioenergia e TOTVS Agro Indústria
  - Conexão com a Base de Dados do Produto

Permissão de

Banco

Banco
Bloco de código
language sql
theme Confluence
title Permissões (Oracle / TOTVS Agro Bioenergia)
linenumbers true
GRANT CONNECT TO "NOME_OWNER";
GRANT RESOURCE TO "NOME_OWNER";


GRANT UNLIMITED TABLESPACE TO "NOME_OWNER";

GRANT CREATE SYNONYM TO "NOME_OWNER";
GRANT CREATE VIEW TO "NOME_OWNER";


GRANT CREATE PROCEDURE TO "NOME_OWNER";

GRANT CREATE TRIGGER TO "NOME_OWNER";
GRANT CREATE SEQUENCE TO "NOME_OWNER";


GRANT CREATE MATERIALIZED VIEW TO "NOME_OWNER


GRANT CREATE ANY TABLE TO ""NOME_OWNER";


GRANT ALTER ANY TABLE  TO "NOME_OWNER";


GRANT INSERT ANY TABLE TO "NOME_OWNER";


GRANT UPDATE ANY TABLE TO "NOME_OWNER";


GRANT DELETE ANY TABLE TO "NOME_OWNER";


GRANT SELECT ANY TABLE TO "NOME_OWNER";


GRANT CREATE ANY TRIGGER TO "NOME_OWNER";

Requisitos de Acesso Externo

O TOTVS Agro API - Hub requer acesso à internet para realizar integrações e atualizações automáticas. Para garantir seu funcionamento, é necessário possua conectividade com as URLs listadas abaixo;

- http://engenharia.agro.totvs.com.br:8080/*

- Caso exista bloqueio/restrição na rede, baseado em whitelist, adicionar os hosts na máquina em que o TOTVS Agro API Hub será instalado:
- Liberações de IPs do TOTVS iPaaS
  - O TOTVS iPaaS é uma plataforma de integração como serviço (iPaaS) que permite conectar sistemas, aplicações e fontes de dados de forma ágil e segura. Caso essa solução seja utilizada, é necessário realizar a liberação dos itens descritos na documentação a seguir:
    - https://tdn.totvs.com/display/public/IPAAS/TOTVS+iPaaS+%7C+Lista+de+IPs
    - Demais Documentações TOTVS iPaaS
      - TOTVS iPaaS | Documentação técnica
      - TOTVS iPaaS | O que há de novo?

Aviso

title	Compatibilidade com o TOTVS Agro Bioenergia

O TOTVS Agro API Hub é compatível com a versão 12.1.2412 ou superior do TOTVS Agro Bioenergia.

Links e referências

TOTVS Agro API Hub (Instalação - Windows)

https://tdn.totvs.com/pages/viewpage.action?pageId=969134928

Integração TOTVS Agro Bioenergia & TOTVS iPaaS

https://tdn.totvs.com/pages/viewpage.action?pageId=886015459

TOTVS Developers

https://api.totvs.com.br/

TOTVS API Pocket

https://api.totvs.com.br/guia

Guia de implementação das APIs TOTVS

https://tdn.totvs.com/display/INT/Guia+de+implementacao+das+APIs+TOTVS

Páginas filhas

Versões comparadas

Versão antiga 9

Nova versão Atual

Chave

Diagrama Arquitetural

Consumo das APIs

Segurança / Autenticação

Características Técnicas

Consumo das APIs

Perguntas Frequentes (FAQ)

Requisitos de Hardware

Requisitos

Requisitos de Hardware

Requisitos de Software

Requisitos de Banco de Dados

Requisitos de Acesso Externo

Links e referências

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 9

Nova versão Atual

Chave

Diagrama Arquitetural

Consumo das APIs

Segurança / Autenticação

Características Técnicas

Consumo das APIs

Perguntas Frequentes (FAQ)

Requisitos de Hardware

Requisitos

Requisitos de Hardware

Requisitos de Software

Requisitos de Banco de Dados

Requisitos de Acesso Externo

Links e referências