Histórico da Página

...

02. SITUAÇÃO/REQUISITO

A descontinuação do TOTVS Agro Portal Mobile está relacionada à reestruturação da topologia do ecossistema TOTVS Agro Bioenergia na T-Cloud, bem como à revisão da arquitetura, componentes e soluções do portfólio TOTVS Agro. Essa iniciativa faz parte da jornada contínua de modernização do produto TOTVS Agro Bioenergia, alinhada às diretrizes de evolução tecnológica da plataforma.

Nesse contexto, as principais funcionalidades atualmente disponíveis no TOTVS Agro Portal Mobile serão migradas para o TOTVS Agro APIHub, incluindo, entre elas, a exposição de APIs a partir de um catálogo estruturado de serviços e formulaFoi realizada a transferência dos serviços do TOTVS Agro Bioenergia para o TOTVS Agro API Hub, em função da descontinuação do TOTVS Agro Portal Mobile.
O objetivo foi redesenvolver e publicar os serviços e APIs no TOTVS Agro API Hub, garantindo continuidade, padronização e governança das integrações.

03. SOLUÇÃO

• Criação da planilha de Mapeamento de Serviços TOTVS Agro Bioenergia no TOTVS Agro Portal Mobile.
• Transcrição dos serviços anteriormente disponíveis no TOTVS Agro Portal Mobile para listas estruturadas em formato JSON, possibilitando sua execução na aplicação e o redesenvolvimento dos serviços no TOTVS Agro API Hub;
• Validação das queries e parâmetros utilizados nos serviços, assegurando conformidade com os padrões do TOTVS Agro API Hub e consistência dos dados;
• de catalogo no TOTVS Agro Plataforma para armazenar serviços e formulas.
• Sincronismo no TOTVS Agro APIHub no startup e 6 em 6 horas de catalogo dos serviços/queries existente via APIs TOTVS Agro Plataforma

• Criado exposição de APIs genéricas GET/POST 

  GET	/mobile/{version}/**	Consulta genérica de um serviço mobile baseado na URL dinâmica.
  POST	/mobile/{version}/**	Execução de comandos (INSERT/UPDATE/DELETE/PROCESSOS) sobre um ou mais serviços mobile.

• 1. GET Dinâmico

  O endpoint captura a URL completa e identifica o serviço a partir do segmento da seção (índice 4 da URL) somado ao primeiro queryParam.

  Estrutura base:

  
  /mobile/{version}/{algumContexto}/{secao}?chaveBase=valorBase&outrosParametros=...
  

  • {secao} → Nome lógico do serviço (mapeado como urlAccess).
  • O primeiro parâmetro de query (chaveBase=valorBase) é incorporado à chave do serviço: /{secao}?chaveBase=valorBase.
  • Demais parâmetros são enviados como lista de parâmetros (Parameter) para substituição nas fórmulas e SQL.

  Parâmetros reservados (ignorados na execução lógica de substituição):

  • uniqueID → Correlation ID. É devolvido (quando aplicável) no campo UniqueID do ResponseDTO em chamadas POST e utilizado em respostas de erro do GET.
  • useSi / usesi → Reservado para comportamento futuro (não participa da filtragem de SQL).

  Regras de retorno:

  • Se o serviço possuir query vazia: retorna um objeto com as chaves definidas em structureFields preenchidas com valores padrão e MOB_STATUS = "N".
  • Se a consulta não retornar linhas: retorna objeto com campos em "0" e MOB_STATUS = "Nenhum registro à ser exibido.".
  • Caso haja linhas: cada linha é convertida para Map<String,Object> onde:
    • Nomes dos campos seguem o identify definido em structureFields (upper-case no JSON final).
    • Campo adicional: MOB_STATUS = "N".

  Exemplo de chamada:

  
  GET /mobile/v1/contextoX/produtos?instancia=TST&codigo=10&uniqueID=ABC-123
  

  Serviço resolvido: /produtos?instancia=TST Parâmetros enviados: codigo=10

  Exemplo de retorno (ilustrativo):

  Bloco de código
  language java
  [ { "CODIGO": 10, "DESCRICAO": "Produto Teste", "TIPO": "INS", "MOB_STATUS": "N" } ]

  2. POST Dinâmico

  Permite enviar uma lista de objetos descrevendo serviços a serem executados em sequência (incluindo hierarquias através de Detalhes). Cada item (DetalheDTO) referencia um serviço (Url) e os campos a serem aplicados na montagem dos parâmetros SQL.

  Endpoint genérico: /mobile/{version}/qualquer/coisa/... (mesma lógica do GET para resolução do contexto)

  Body:

  • Bloco de código
    language java
    [ { "NomeObjeto": "APTO001", "Url": "/servicoPrincipal?instancia=TST", "Campos": [ { "Nome": "codigo", "Valor": 100 }, { "Nome": "descricao", "Valor": "Teste" } ], "Detalhes": [ { "NomeObjeto": "APTO001-DET1", "Url": "/servicoFilho?instancia=TST", "Campos": [ { "Nome": "codigoItem", "Valor": 1 }, { "Nome": "quantidade", "Valor": 50 } ], "Detalhes": [] } ] }, { "NomeObjeto": "APTO002", "Url": "/servicoPrincipal?instancia=TST", "Campos": [ { "Nome": "codigo", "Valor": 101 }, { "Nome": "descricao", "Valor": "Outro" } ], "Detalhes": [] } ]

  Observações:

  • Campo Url deve incluir o serviço + primeiro parâmetro base (mesma regra do GET) ex: /servicoX?instancia=PRD.
  • Lista Campos é confrontada com o mapeamento structureFields do serviço; qualquer campo não mapeado é ignorado.
  • Campo Detalhes suporta recursividade (árvore ilimitada). A implementação “achata” a hierarquia internamente (fattenDetalhes).
  • Cada serviço é executado isoladamente. Falhas individuais são registradas no array Processo da resposta.

  Retorno: sempre uma lista com um único objeto ResponseDTO.

  Estrutura de Resposta (POST):

  • Bloco de código
    language java
    [ { "Url": "/mobile/v1/...", "Detalhes": null, "IDProcesso": null, "Conteudo": null, "Usuario": null, "NomeObjeto": "RetornoServico", "Campos": [ { "Nome": "ServicosChamados", "Valor": "/servicoPrincipal?instancia=TST;/servicoFilho?instancia=TST;" }, { "Nome": "Mensagem", "Valor": "" }, { "Nome": "RegistrosAfetados", "Valor": 2 }, { "Nome": "QtdServicosChamados", "Valor": 2 }, { "Nome": "QtdRegistroEnviados", "Valor": 3 } ], "Processo": [ { "apto": "APTO001", "result": "SUCCESS", "error": null }, { "apto": "APTO001-DET1", "result": "SUCCESS", "error": null }, { "apto": "APTO002", "result": "FAILURE", "error": "Mensagem de erro específica" } ], "UniqueID": "ABC-123" } ]

  Principais Campos (Campos -> Nome):

  • ServicosChamados: Lista concatenada de URLs únicas executadas.
  • Mensagem: Mensagens agregadas de exceções gerais.
  • RegistrosAfetados: Soma de linhas afetadas nas execuções (quando aplicável).
  • QtdServicosChamados: Quantidade de serviços distintos (Url).
  • QtdRegistroEnviados: Total de itens (após flatten) processados.

  Processo (itens do array Processo):

  • apto: Valor vindo de NomeObjeto do DetalheDTO original.
  • result: SUCCESS ou FAILURE.
  • error: Detalhe da falha (quando houver).

  Regras de erro:

  • Cada falha individual não interrompe o processamento dos demais serviços.
  • Exceções gerais populam Mensagem e ServicosChamados permanece preenchido.
  • Requisição sem body ou body vazio retorna campos com contagens zeradas
  Mapeamento de relacionamento entre Tabelas e Produtos, proporcionando melhor entendimento das dependências e otimização no consumo das APIs
  • .

04. DEMAIS INFORMAÇÕES

Não se aplica.

...