DAGROFRAME-5126 DT - API Hub :: Redesenvolver (expor) serviços e APIs via TOTVS Agro API Hub

01. DADOS GERAIS

Produto:	TOTVS Agro API Hub
Linha de Produto:	Linha PIMS
Segmento:	Agroindústria
Módulo:	Framework
Função:	Todas
País:	Brasil
Ticket:
Requisito/Story/Issue (informe o requisito relacionado) :	DAGROFRAME-5126 - Obtendo detalhes do item... STATUS

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 API Hub, incluindo, entre elas, a exposição de APIs a partir de um catálogo estruturado de serviços e formula.

03. SOLUÇÃO

Criação 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):

[
  {
    "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:

[
  {
    "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):

[
  {
    "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.

04. DEMAIS INFORMAÇÕES

Não se aplica.

05. ASSUNTOS RELACIONADOS

Arquitetura e Tecnologia - TOTVS Agro API Hub

Árvore de páginas