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


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:

Fluxo:

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.


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


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


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

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


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.

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

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

Bases de dados - TOTVS Agro API Hub

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;
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;
  • Versão
    • Postgres 15 (recomendado)

  • Definição do Banco
    • Encoding :  UTF8
    • Collation :  pt_BR.UTF-8
    • Character Type :  pt_BR.UTF-8

    • (aviso) Em sistema operacional Windows Server, a Collation e Character Type devem ser utilizadas como Portuguese_Brazil.1252 ou English_United States.1252

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.

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;


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

Links e referências

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

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

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

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

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