DAGROFRAME-5373 DT - API Hub :: Objetos de Negócio (ADR010001)

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 para a recuperação das estruturas de dados de Entidades e Queries no TOTVS Agro API Hub, com ela, conseguimos recuperar informações especificas de Objeto de Negócio que vai ser utilizado futuramente, também sendo necessário estar habilitado por padrão via colunas . 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 desenvolvido para recuperação dos dados relacionado ao Objeto de Negócio enviado por parâmetro.

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

Passo a Passo - Objetos de Negócio do TOTVS Agro Bioenergia no Smart View (Smart View Agent 3.6 ou superior)