Histórico da Página

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.

Links e referências

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

Características Técnicas

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

Descrever ou tabular informações técnicas a respeito do TOTVS Agro API Hub como SO homologado, BD homologado, principais acessos que devem ser preparados para permitir a instalação, configuração e uso, URLs que devem ser liberados (e.g., TOTVS Apps e outros), autenticação, paginação, filtros, link para lista de APIs existentes;
Resumir (listar) e deixar claro os principais tópicos e informações que envolvem características técnicas, como forma de facilitar o primeiro entendimento sobre API Hub e suas dependências;
Utilizar de tópicos resumidos e objetivos, para facilitar;

Requisitos de Hardware

Diagrama Arquitetural

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;

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

Observações de instalação (ambiente/infraestrutura)

- 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

...

O API-Hub

...

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

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
  Bloco de código
  language sql
  theme Confluence
  title Permissões (Oracle / TOTVS Agro Bioenergia)
  linenumbers true
  GRANT CONNECT TO
Oracle

⚠️ Base de Dados do Produto:

Versão mínima requirida do banco de dados

Oracle 12c, ou superior

Permissão de Banco

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/*

...

Comunicação entre os ambientes do TOTVS Agro API Hub e bases de dados de outros produtos (por exemplo, TOTVS Agro Bioenergia, com compatibilidade com Oracle);
- Caso exista bloqueio/restrição na rede, baseado em whitelist, adicionar os hosts na máquina em que

o

- 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

...

title	Infraestrutura e ambientes

- - - Demais Documentações TOTVS iPaaS
      - TOTVS iPaaS | Documentação técnica
      - TOTVS iPaaS | O que há de novo?

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

...

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.

Diagrama Arquitetural

...

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/

...

Segurança / Autenticação

A autenticação/autorização das APIs de integração utilizará 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

Consumo das APIs

Composição da URL da API

A URL para as entidades e queries cadastradas é composta conforme 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]

...

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 3

Nova versão Atual

Chave

Características Técnicas

Requisitos de Hardware

Diagrama Arquitetural

Segurança / Autenticação

Consumo das APIs

Perguntas Frequentes (FAQ)

Requisitos de Hardware

Requisitos de Software

Requisitos de Banco de Dados

Requisitos de Acesso

Externo

Links e referências

Segurança / Autenticação

Consumo das APIs

Composição da URL da API