Histórico da Página

...

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

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.

Requisitos de Software

Sistema Operacional:

Windows Server 2019 Standard;
Windows Server 2022 Standard;

Requisitos de Banco de Dados

PostgreSQL 15
- Permissão de Banco
  - 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>;

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

Acesso à internet (com acesso liberado ao endereço 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 TOTVS Agro API Hub será instalado:

Liberações de IPs do TOTVS iPaaS

- https://tdn.totvs.com/display/public/IPAAS/TOTVS+iPaaS+%7C+Lista+de+IPs

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.

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

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

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]

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.

Páginas filhas

Versões comparadas

Versão antiga 1

Nova versão 2

Chave