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.

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:

• • • 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.

...

• • • 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ões 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=201

• • 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  http:127.0.0.1:8080/api/query/v1/baixaConsumiveisMativ?page=1&pagesize=25

As definições detalhadas e a estrutura de cada API podem ser consultadas na página 🔗APIs Padrões 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 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);

  
  

...

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;

Requisitos de Banco de Dados

TOTVS Agro API HUB

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

...

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

...

• • 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:
    • https://tcserver-supplyagro.totvs.app/
    • http://engenharia.agro.totvs.com.br:8080/*
    • https://agro.totvs.app/*
  • 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?

...

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

• 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