LojaAjusteEstoque (STATUS: DOCUMENTADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Ajuste de Estoque Loja)
Biblioteca	wosk_loja_ajuste_estoque
Data	26/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
26/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo Loja Ajuste de Estoque (LINX → ILLI).

Descrição

Este serviço de ajuste de estoque no LINX envia contagens ajustadas e itens de grade para o ILLI, alinhando o estoque da loja ao processo corporativo.
Garante que apenas filiais previstas participem, respeitando datas de transferência e o estado de cada captura antes de enfileirar e processar o envio.

Capturador

Descrição Conceitual

A captura automática consulta ESTOQUE_PROD_CONTAGEM quando o estado do serviço LojaAjusteEstoque está apto, com filtro por DATA_PARA_TRANSFERENCIA, ESTOQUE_AJUSTADO, filiais permitidas e exclusões de filiais centrais, ordenação por data e paginação conforme o limite configurado para o serviço LojaAjusteEstoque, alinhada ao processamento cronológico de captura. Para cada linha, monta a chave NOME_CONTAGEM-FILIAL, anexa os itens de ESTOQUE_PROD_CTG_AJUSTE e grava na fila de integração com serviço LojaAjusteEstoque.

A captura por chave aceita uma ou mais chaves no padrão NOME_CONTAGEM-FILIAL; para cada chave válida, relê o cabeçalho da contagem em ESTOQUE_PROD_CONTAGEM, recarrega os itens em ESTOQUE_PROD_CTG_AJUSTE e reenfileira preservando o token quando já existir para o mesmo registro na fila.

Fonte

Origem consultada: tabela ESTOQUE_PROD_CONTAGEM.

Consulta principal:

SELECT
    NOME_CONTAGEM,
    FILIAL,
    EMISSAO,
    RESPONSAVEL,
    OBS,
    ESTOQUE_AJUSTADO,
    DATA_AJUSTE,
    TIPO,
    SALDO_ARMAZENADO,
    CONTAGEM_POR_AREA_FECHADA,
    DATA_PARA_TRANSFERENCIA,
    NOME_CONTAGEM_ANTERIOR
FROM
    ESTOQUE_PROD_CONTAGEM (NOLOCK)

Operações com Dados

Leitura: Consulta da tabela ESTOQUE_PROD_CONTAGEM conforme SQL da seção Fonte; itens de linha carregados a partir de ESTOQUE_PROD_CTG_AJUSTE pela mesma NOME_CONTAGEM usada no registro atual.

Consulta dinâmica (captura automática): reutiliza a projeção com WHERE FILIAL IN (...) (lista derivada de FILIAIS excluindo códigos fixos de estoque central e centro de distribuição), ESTOQUE_AJUSTADO = '1', DATA_PARA_TRANSFERENCIA >= o filtro efetivo (padrão de data quando não informado), ORDER BY DATA_PARA_TRANSFERENCIA ASC e paginação OFFSET ... ROWS FETCH NEXT ... ROWS ONLY conforme o limite configurado para o serviço LojaAjusteEstoque e o estado do capturador (offset, chave e data de posição).

Consulta dinâmica (captura por chave): mesma projeção com WHERE NOME_CONTAGEM = ... AND FILIAL = ... obtidos ao partir a chave informada.

Validação (captura por chave): a chave deve conter exatamente duas partes separadas por hífen (NOME_CONTAGEM e FILIAL); caso contrário o fluxo interrompe com erro de chave inválida.

Persistência: grava itens pendentes na Fila de Processamento, com serviço LojaAjusteEstoque e chave NOME_CONTAGEM-FILIAL (preservando token existente quando aplicável na recaptura); o estado do capturador mantém offset, chave de posição, data de posição, filtro e situação (parado, em execução, concluído ou erro).

Fila de Processamento

Descrição Conceitual

A fila recupera um registro pendente e utiliza o conteúdo do registro como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e realiza a chamada ao ILLI.
O fluxo marca o registro como em envio, envia o JSON ao endpoint ILLI de ajuste de estoque, interpreta o retorno (success, message) e grava situação final, mensagem, tempo e auditoria de requisição na tabela da fila de integração.

Estruturação de Dados

Exemplo ilustrativo de corpo enviado ao ILLI (estrutura alinhada ao conteudo):

{
  "NOME_CONTAGEM": "<NOME_CONTAGEM>",
  "FILIAL": "<FILIAL>",
  "EMISSAO": "<EMISSAO>",
  "RESPONSAVEL": "<RESPONSAVEL>",
  "OBS": "<OBS>",
  "ESTOQUE_AJUSTADO": "<ESTOQUE_AJUSTADO>",
  "DATA_AJUSTE": "<DATA_AJUSTE>",
  "TIPO": "<TIPO>",
  "SALDO_ARMAZENADO": "<SALDO_ARMAZENADO>",
  "CONTAGEM_POR_AREA_FECHADA": "<CONTAGEM_POR_AREA_FECHADA>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA>",
  "NOME_CONTAGEM_ANTERIOR": "<NOME_CONTAGEM_ANTERIOR>",
  "ITENS": [
    {
      "NOME_CONTAGEM": "<NOME_CONTAGEM>",
      "PRODUTO": "<PRODUTO>",
      "COR_PRODUTO": "<COR_PRODUTO>",
      "QTDE_AJUSTE": "<QTDE_AJUSTE>",
      "A1": "<A1>",
      "A2": "<A2>",
      "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA_ITEM>"
    }
  ]
}

Tratamento de Dados

Sobre o processamento na classe Queue antes do envio:

• Base do envio: o array conteudo do registro atual é utilizado diretamente como corpo da requisição ao ILLI, sem mapeamento adicional declarado em lista de campos no arquivo analisado.
• Registro atual em exceção: quando a mensagem de exceção indica retorno JSON não reconhecido (prefixo textual padronizado no fluxo), o retorno persistido pode incluir estrutura com indicador de erro e trecho de dados interpretado.

Integração com o ILLI

Chamada de integração com o ILLI (via rotina de integração):

• Chamada: Requisição HTTP
• Recurso: /bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjuste
• Método HTTP: POST
• Corpo: objeto JSON correspondente ao conteudo do registro da fila, incluindo o array ITENS.

Tratamento de retorno

Ausência de resposta: lança exceção indicando que não houve resposta JSON; situação final 4 na tabela da fila de integração.
Resposta com success e message ambos vazios: tratada como retorno não reconhecido (exceção), situação erro.
Sucesso: quando success não está vazio, situação de sucesso; caso contrário situação erro com mensagem em message quando existir.
Em exceção genérica, a mensagem é persistida; se a mensagem indicar JSON não reconhecido, o retorno estruturado pode incluir campos de erro e dados parseados.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaAjusteEstoque e situação de erro, ordenando pelo horário de processamento para priorizar ocorrências mais antigas.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura e enfileiramento	Com estado apto e filtros válidos, deve ler ESTOQUE_PROD_CONTAGEM com critérios de filial permitida, ESTOQUE_AJUSTADO, data mínima de transferência e paginação, anexar itens de ESTOQUE_PROD_CTG_AJUSTE e gravar cada contagem na fila de integração com serviço LojaAjusteEstoque e chave NOME_CONTAGEM-FILIAL.	Registro pendente na fila com conteúdo alinhado às consultas e posição de captura atualizada.
Capturador	Captura por chave	Para cada chave no padrão NOME_CONTAGEM-FILIAL, deve reler o cabeçalho e itens e regravar na fila preservando token quando já existir.	Reenfileiramento com chave consistente e token reutilizado quando aplicável.
Fila de Processamento	Integração ILLI	Ao processar registro pendente, deve enviar o conteudo ao recurso /bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjuste, interpretar o retorno quanto à situação de sucesso ou erro com mensagem (success, message) e persistir na tabela da fila de integração a situação final (códigos 2 ou 4 conforme o caso), a mensagem retornada e o tempo de processamento.	Fila atualizada com situação final e auditoria coerentes com o retorno do ILLI.