01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

Criar a partir das Entidades & Queries a listagem, schemas e a recuperação de dados para criação de Objetos de Negócios no TOTVS API Hub, seguindo a ADR010001.

Conector/APIs de "Objetos de Negócio" Smart View (Bioenergia / TOTVS Agro API Hub) - ADR010001

https://arquitetura.totvs.io/architectural-records/ADRs/Framework/ADR010001/#contexto

Específicos:

• • Revisitar nomenclaturas e rotas no API-Hub para não usar "/smartview/" e sim "/business-objects" (deixar agnóstico no API-Hub, sem vínculo) 
  • Implementar segurança (header Authorization) no API-Hub para "/business-objects/" para dois níveis de autenticação:
    • 1. via credenciais padrão do API-Hub (assim como já acontece nas demais APIs do Bioenergia) e, caso dê 401 (ou token expirado, enfim), seguir para o modelo
    • 2. via T-Provider & Keycloak (únido modelo que seria chamado pelo Smart View)
  • Trocar "isEnableSmartView" para "isBusinessObject" (no modelo de dados) - revisar colunas (banco de dados) para não usar palavra "smart_view", por exemplo, "enable_smart_view"
  • Incrementar APIs de Objetos de Negócio (ON) para que, além do modelo de Entidades (Entity), também se permita usar o conceito de ON para o modelo Consulta (Query);
  • Revisitar abordagem de "v1" e/ou "versão de API de release" para permitir uma recuperação mais dinâmica e inteligente das APIs e suas versões;
  • Concatenar, no nome do objeto de negócio, a versão, por exemplo "Fazenda (v1)", "Fazenda (v2)" ...
  • Quando for utilizar/implementar modelo Query, avaliar uso de nova tabela "query_filters" ou evoluir "query_fields" - objetivo: melhor controlar/catalogar os possíveis filters de APIs GET do tipo Query, para serem utilizadas como filters ou parameters (objetos de negócio)
  • Implementar POST na camada de abstração para chamar GET (da API Padrão, seja Entity ou Query, e depois EntryPoint), para properties =[], filters = [] e parametros = [] ou com filtros utilizados no GET da API Padrão (por exemplo, ?codigoTurma=123)

03. SOLUÇÃO

Foi desenvolvido a partir da documentação ADR010001 as três APIs que são necessárias para criarmos os Objetos de Negócios no produto TOTVS Agro API Hub.

• Listagem de Objetos de Negócios

Foi desenvolvida a partir da recuperação de informações e listagem de Entidades e Queries no TOTVS Agro API Hub, com ela, conseguimos listar todos os Objetos de Negócios que forem habilitados por padrão. Com as tabelas de Entidades e Queries, foi necessário criar soluções especificas para recuperar e converter corretamente esses dados e responder as requisições seguindo a ADR010001.

• • • Caminho: /business-objects/v1/searchobjects
    • Método: GET
    • Autenticação: Token JWT padrão do TOTVS API Hub ou Token JWT padrão do TOTVS Agro Provider
    • Tabelas: entity_api, entity_de, entity_he, query_he, query_de e query_fields
    • Resposta: name, displayName, description, areas, schemaUrl e dataUrl

• Schemas de Objetos de Negócios

Foi desenvolvida a partir da recuperação de informações de Entidades e Queries no TOTVS Agro API Hub, com ela, conseguimos recuperar informações especificas de estrutura do Objeto de Negócio que vai ser recuperado futuramente, também sendo necessário estar habilitado por padrão via coluna. Com essas informações disponíveis do Objeto de Negócio que foi pedido por parâmetro, devolveremos as informações da estrutura de dados ao converter corretamente, além de responder as requisições seguindo a ADR010001.

• • • Caminho: /business-objects/v1/{businessObjectName}/schema?type=entity
    • Método: GET
    • Autenticação: Token JWT padrão do TOTVS API Hub ou Token JWT padrão do TOTVS Agro Provider
    • Parâmetros: 
      • businessObjectName: Nome do Objeto de Negócio a ser recuperado
      • type: Tipo de Objeto de Negócio está relacionado no TOTVS Agro API Hub (entity ou query)
    • Tabelas: entity_api, entity_de, entity_he, query_he, query_de e query_fields
    • Resposta: name, displayName, description, areas, schemaUrl, dataUrl, properties e parameters

• Data de Objetos de Negócios

Foi desenvolvida a partir da recuperação de informações e listagem de Entidades e Queries no TOTVS Agro API Hub, com ela, conseguimos listar todos os Objetos de Negócios que forem habilitados por padrão. Com as tabelas de Entidades e Queries, foi necessário criar soluções especificas para recuperar e converter corretamente esses dados e responder as requisições seguindo a ADR010001.

• • • Caminho: /business-objects/v1/{businessObjectName}/data?page=1&pagesize=25&type=entity
    • Método: POST
    • Autenticação: Token JWT padrão do TOTVS API Hub ou Token JWT padrão do TOTVS Agro Provider
    • Parâmetros: 
      • businessObjectName: Nome do Objeto de Negócio a ser recuperado
      • type: Tipo de Objeto de Negócio está relacionado no TOTVS Agro API Hub (entity ou query)
    • Tabelas: entity_api, entity_de, entity_he, query_he, query_de e query_fields
    • Corpo: properties, filter e parameters
    • Resposta: Depende de cada Objeto de Negócio cadastrado

Soluções especificas:

• Trocar rotas de "/smartview/" por "/business-objects"
  • Solução: URLs padronizadas para /business-objects/v1 (base), com caminhos de schema e data usando esse prefixo.
• Implementar segurança (header Authorization) em dois níveis: 1) credenciais API-Hub; 2) fallback T-Provider & Keycloak
  • Solução: Fluxo de autenticação em duas camadas implementado — primeiro tenta credenciais do API-Hub; em caso de 401/expiração faz fallback para T-Provider/Keycloak.
• Trocar isEnableSmartView para isBusinessObject e revisar colunas do BD
  • Solução: Mudanças a nível de banco (migrations/colunas antigas contendo "smart_view").

• Permitir Objetos de Negócio também para modelo Query (além de Entity)

• • Solução: Modelo de Query à listagem; geram schema (properties/parameters) e endpoint de dados. Parâmetros da query são extraídos automaticamente (tokens ::campo) e expostos como parameters.

• Revisitar versão de API e concatenar versão no nome do objeto (ex.: "Fazenda (v1)")

• • Solução: displayName do Business Object concatena nome com versão do endpoint (ex.: Nome (v1)); as URLs usam a versão no caminho base (/v1).

• Ao usar Query: avaliar query_filters ou evoluir query_fields para catalogar filters/parameters

• • Solução: mantém-se hoje o uso de query_fields (muitos migrations já populam essa estrutura). A extração de filtros é feita a partir da própria query (padrão ::field) e convertida em parâmetros.

• Implementar POST na camada de abstração para chamar GET (body: properties=[], filters=[], parameters=[])

• • Solução: Implementado fluxo que retorna os dados, mescla parâmetros do body com query string da requisição, e usa properties para filtrar campos que serão retornados para o response. Assim, um POST pode acionar o GET subjacente (Entity ou Query) com parâmetros vindos do body.
  • Observação: suporte a ENTRYPOINT e a estrutura de filters da requisição serão feitas futuramente.

Observações finais

• Filtragem por properties atua em campos de primeiro nível; estruturas aninhadas podem exigir lógica adicional se for necessário filtrar internamente.
• Parâmetros expostos ao cliente vêm com sufixo Param (ex.: campoParam) e esse sufixo é removido ao montar os parâmetros enviados para a API subjacente.
• Data/time com timezone teve tratamento específico.

04. DEMAIS INFORMAÇÕES

Não se aplica.

05. ASSUNTOS RELACIONADOS

Arquitetura e Tecnologia - TOTVS Agro API Hub

Smart View (TReports) & TOTVS Agro