LojaAjusteEstoque (STATUS: CRIANDO)

Documentação Técnica

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

Histórico de Versões

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

Descrição

Esta biblioteca envia ao ILLI os ajustes de estoque originados de contagens no LINX, após selecionar contagens elegíveis e montar o detalhamento por produto.
Ela garante que cada lote siga fila de processamento, integração e registro de sucesso ou falha para acompanhamento.

Capturador

Descrição Conceitual

A captura automática consulta a view ESTOQUE_PROD_CONTAGEM quando o estado interno está apto (situação reiniciada de concluído para parado ou em andamento), aplicando filtro por filiais de loja (excluindo estoque central e centro de distribuição), ESTOQUE_AJUSTADO = '1', data mínima de transferência e ordenação/paginação por data, conforme conceito de ordenação e paginação por data. Para cada registro retornado, obtém-se as linhas de ajuste em ESTOQUE_PROD_CTG_AJUSTE, compõe-se a chave NOME_CONTAGEM-FILIAL e o registro é encaminhado à fila de processamento identificada pelo serviço LojaAjusteEstoque, atualizando-se posição e repetindo-se a leitura enquanto a regra de paginação indicar nova página.

A captura dirigida por chaves percorre uma lista informada, valida o formato em duas partes (NOME_CONTAGEM e FILIAL), consulta a mesma view com WHERE fixo por contagem e filial e, para cada linha retornada, inclui o detalhamento de ESTOQUE_PROD_CTG_AJUSTE antes de gravar na fila com o token já existente quando houver.

Fonte

Origem consultada: view ESTOQUE_PROD_CONTAGEM.
Complemento de detalhes por contagem: tabela ESTOQUE_PROD_CTG_AJUSTE.

Operações com Dados

Leitura principal (base da consulta de captura):

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)

Consulta dinâmica na captura automática (filtro e paginação montados em tempo de execução; lista de filiais e valores de data/offset/limit conforme estado e configuração):

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)
WHERE FILIAL IN ('...')
  AND ESTOQUE_AJUSTADO = '1'
  AND DATA_PARA_TRANSFERENCIA >= '{filtro_DATA_PARA_TRANSFERENCIA}'
ORDER BY DATA_PARA_TRANSFERENCIA ASC
OFFSET {offset} ROWS FETCH NEXT {limite} ROWS ONLY

Consulta dinâmica na captura por chave (WHERE por NOME_CONTAGEM e FILIAL da chave):

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)
WHERE NOME_CONTAGEM = '{NOME_CONTAGEM}'
  AND FILIAL = '{FILIAL}'

Detalhamento de produtos por contagem (NOME_CONTAGEM informado):

SELECT
    NOME_CONTAGEM,
    PRODUTO,
    COR_PRODUTO,
    QTDE_AJUSTE,
    A1, A2, A3, A4, A5, A6, A7, A8, A9, A10,
    A11, A12, A13, A14, A15, A16, A17, A18, A19, A20,
    A21, A22, A23, A24, A25, A26, A27, A28, A29, A30,
    A31, A32, A33, A34, A35, A36, A37, A38, A39, A40,
    A41, A42, A43, A44, A45, A46, A47, A48,
    CUSTO1,
    CUSTO2,
    CUSTO3,
    CUSTO4,
    CM_OPERACAO,
    DATA_PARA_TRANSFERENCIA
FROM
    ESTOQUE_PROD_CTG_AJUSTE (NOLOCK)
WHERE
    NOME_CONTAGEM = '{NOME_CONTAGEM}'

Persistência: estado da captura mantido pelo mecanismo do serviço LojaAjusteEstoque (offset, chave, datas, filtro, situação); registros pendentes e processados armazenados na tabela wosk_queue com serviço LojaAjusteEstoque.

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 conteúdo ao endpoint ILLI de ajuste de estoque, interpreta o JSON de retorno e grava situação final, mensagem, tempo e auditoria de requisição na própria fila. Não há rotinas inteligentes associadas a este arquivo.

Estruturação de Dados

O payload enviado ao ILLI corresponde ao array conteudo do registro na fila, construído a partir da linha de ESTOQUE_PROD_CONTAGEM mais a chave ITENS com o array de linhas retornadas de ESTOQUE_PROD_CTG_AJUSTE.

Campo no payload	Campo de origem
`NOME_CONTAGEM`	`NOME_CONTAGEM` da view `ESTOQUE_PROD_CONTAGEM`
`FILIAL`	`FILIAL` da view `ESTOQUE_PROD_CONTAGEM`
`EMISSAO`	`EMISSAO` da view `ESTOQUE_PROD_CONTAGEM`
`RESPONSAVEL`	`RESPONSAVEL` da view `ESTOQUE_PROD_CONTAGEM`
`OBS`	`OBS` da view `ESTOQUE_PROD_CONTAGEM`
`ESTOQUE_AJUSTADO`	`ESTOQUE_AJUSTADO` da view `ESTOQUE_PROD_CONTAGEM`
`DATA_AJUSTE`	`DATA_AJUSTE` da view `ESTOQUE_PROD_CONTAGEM`
`TIPO`	`TIPO` da view `ESTOQUE_PROD_CONTAGEM`
`SALDO_ARMAZENADO`	`SALDO_ARMAZENADO` da view `ESTOQUE_PROD_CONTAGEM`
`CONTAGEM_POR_AREA_FECHADA`	`CONTAGEM_POR_AREA_FECHADA` da view `ESTOQUE_PROD_CONTAGEM`
`DATA_PARA_TRANSFERENCIA`	`DATA_PARA_TRANSFERENCIA` da view `ESTOQUE_PROD_CONTAGEM` (uso também para data do registro na fila)
`NOME_CONTAGEM_ANTERIOR`	`NOME_CONTAGEM_ANTERIOR` da view `ESTOQUE_PROD_CONTAGEM`
`ITENS`	Conjunto de linhas projetadas de `ESTOQUE_PROD_CTG_AJUSTE` (campos listados na secção Tratamento de Dados)

Exemplo ilustrativo de estrutura do conteudo (valores fictícios):

{
  "NOME_CONTAGEM": "...",
  "FILIAL": "...",
  "EMISSAO": "...",
  "RESPONSAVEL": "...",
  "OBS": "...",
  "ESTOQUE_AJUSTADO": "...",
  "DATA_AJUSTE": "...",
  "TIPO": "...",
  "SALDO_ARMAZENADO": "...",
  "CONTAGEM_POR_AREA_FECHADA": "...",
  "DATA_PARA_TRANSFERENCIA": "...",
  "NOME_CONTAGEM_ANTERIOR": "...",
  "ITENS": []
}

Tratamento de Dados

Sobre o registro atual retornado da view ESTOQUE_PROD_CONTAGEM no laço de captura:

ITENS: passa a conter o array de linhas obtidas da consulta a ESTOQUE_PROD_CTG_AJUSTE para o mesmo NOME_CONTAGEM, composto por objetos com os campos: NOME_CONTAGEM, PRODUTO, COR_PRODUTO, QTDE_AJUSTE, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15, A16, A17, A18, A19, A20, A21, A22, A23, A24, A25, A26, A27, A28, A29, A30, A31, A32, A33, A34, A35, A36, A37, A38, A39, A40, A41, A42, A43, A44, A45, A46, A47, A48, CUSTO1, CUSTO2, CUSTO3, CUSTO4, CM_OPERACAO, DATA_PARA_TRANSFERENCIA.

Na fila, o processamento utiliza o conteúdo do registro como corpo enviado ao ILLI, sem reestruturação adicional de campos no código analisado.

Integração com o ILLI

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

Chamada: Requisição HTTP (encapsulada pela rotina de envio ao ILLI).

Recurso: e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjuste

Método HTTP: conforme implementação padrão da rotina de integração ILLI (corpo JSON com o array conteudo).

Corpo de entrada: objeto/array conteudo do registro da fila (campos da contagem + ITENS).

Processamento: envio do payload e leitura da resposta JSON com indicadores success e message.

Exemplo de corpo enviado (estrutura mínima, mesma forma do conteudo na fila):

{
  "NOME_CONTAGEM": "...",
  "FILIAL": "...",
  "ITENS": [ { "PRODUTO": "...", "QTDE_AJUSTE": "..." } ]
}

Tratamento de retorno

Ausência de resposta JSON: situação de erro (exceção) e situação final 4 na fila.
Resposta sem success e sem message: tratada como retorno não reconhecido (exceção), situação 4.
Sucesso: quando success não está vazio no JSON, situação 2; caso contrário situação 4 com mensagem retornada em message quando existir.
Em exceção, a mensagem de erro é persistida e o retorno estruturado pode incluir error e data quando a mensagem contém prefixo indicando JSON não reconhecido.

Encaminhamento em cenário de erro

Não há, neste fluxo, encaminhamento automático para outro serviço ou biblioteca após falha na integração com o ILLI; o registro permanece com o estado de erro registrado na fila.

Notificação

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

Destinatários e assunto são definidos no código; os campos exibidos incluem datas de captura e processamento, chave, mensagem de erro e DATA_AJUSTE extraída do conteúdo, com normalização de quebras de linha na mensagem de erro para exibição.

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 `ESTOQUE_AJUSTADO = '1'`, enriquecer com linhas de `ESTOQUE_PROD_CTG_AJUSTE` e gravar na fila com chave `NOME_CONTAGEM-FILIAL`.	Registro pendente na fila com conteúdo completo e chave consistente.
Capturador	Captura por chave	Para cada chave no formato `NOME_CONTAGEM-FILIAL`, deve consultar a contagem e reproduzir o encaminhamento à fila com token preservado quando existir.	Chave inválida interrompe com exceção; chave válida gera atualização na fila.
Fila de Processamento	Integração ILLI	Ao processar registro pendente, deve enviar `conteudo` ao endpoint `ilx_ajuste_estoque/setAjuste`, interpretar `success`/`message` e persistir situação 2 ou 4 com mensagem e tempo na `wosk_queue`.	Fila atualizada com situação final, mensagem e auditoria de requisição coerentes com o retorno.