LojaAjusteEstoqueDevolucao (STATUS: CRIANDO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Ajuste de Estoque — Devolução)
Biblioteca	wosk_loja_ajuste_estoque_devolucao
Data	12/02/2026

Histórico de Versões

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

Descrição

Esta biblioteca identifica no LINX entradas de estoque com perfil de devolução e encaminha o detalhamento ao ILLI para ajuste de estoque.
Garante fila, integração e registro de sucesso ou erro para cada romaneio elegível.

Capturador

Descrição Conceitual

A captura automática consulta a view ESTOQUE_PROD_ENT quando o estado interno está apto (situação reiniciada de concluído para parado ou em andamento), restringindo a filiais de loja (excluindo estoque central e centro de distribuição), ACERTO_ENTRADA = '1', TIPO_ENTRADA = '4', data mínima de transferência e ordenação/paginação por DATA_PARA_TRANSFERENCIA e ROMANEIO_PRODUTO, conforme conceito de ordenação e paginação por data. Para cada registro retornado, obtém-se as linhas em ESTOQUE_PROD1_ENT, compõe-se a chave FILIAL-ROMANEIO_PRODUTO e o registro é encaminhado à fila do serviço LojaAjusteEstoqueDevolucao, atualizando posição e repetindo 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 (FILIAL e ROMANEIO_PRODUTO), consulta ESTOQUE_PROD_ENT com WHERE fixo por filial e romaneio e, para cada linha retornada, inclui o detalhamento de ESTOQUE_PROD1_ENT antes de gravar na fila com o token já existente quando houver.

Fonte

Origem consultada: view ESTOQUE_PROD_ENT.
Complemento de linhas de produto: tabela ESTOQUE_PROD1_ENT.

Operações com Dados

Leitura principal (base da consulta de captura):

SELECT
    ROMANEIO_PRODUTO,
    FILIAL,
    EMISSAO,
    OBS,
    ACERTO_ENTRADA,
    TIPO_ENTRADA,
    DATA_DIGITACAO,
    DATA_PARA_TRANSFERENCIA
FROM
    ESTOQUE_PROD_ENT (NOLOCK)

Consulta dinâmica na captura automática (filtro e paginação montados em tempo de execução):

SELECT
    ROMANEIO_PRODUTO,
    FILIAL,
    EMISSAO,
    OBS,
    ACERTO_ENTRADA,
    TIPO_ENTRADA,
    DATA_DIGITACAO,
    DATA_PARA_TRANSFERENCIA
FROM
    ESTOQUE_PROD_ENT (NOLOCK)
WHERE FILIAL IN ('...')
  AND ACERTO_ENTRADA = '1'
  AND TIPO_ENTRADA = '4'
  AND DATA_PARA_TRANSFERENCIA >= '{filtro_DATA_PARA_TRANSFERENCIA}'
ORDER BY DATA_PARA_TRANSFERENCIA ASC, ROMANEIO_PRODUTO ASC
OFFSET {offset} ROWS FETCH NEXT {limite} ROWS ONLY

Consulta dinâmica na captura por chave:

SELECT
    ROMANEIO_PRODUTO,
    FILIAL,
    EMISSAO,
    OBS,
    ACERTO_ENTRADA,
    TIPO_ENTRADA,
    DATA_DIGITACAO,
    DATA_PARA_TRANSFERENCIA
FROM
    ESTOQUE_PROD_ENT (NOLOCK)
WHERE FILIAL = '{FILIAL}'
  AND ROMANEIO_PRODUTO = '{ROMANEIO_PRODUTO}'

Detalhamento de produtos por romaneio:

SELECT
    PRODUTO,
    COR_PRODUTO,
    EN_1, EN_2, EN_3, EN_4, EN_5, EN_6, EN_7, EN_8, EN_9, EN_10,
    EN_11, EN_12, EN_13, EN_14, EN_15, EN_16, EN_17, EN_18, EN_19, EN_20,
    EN_21, EN_22, EN_23, EN_24, EN_25, EN_26, EN_27, EN_28, EN_29, EN_30,
    EN_31, EN_32, EN_33, EN_34, EN_35, EN_36, EN_37, EN_38, EN_39, EN_40,
    EN_41, EN_42, EN_43, EN_44, EN_45, EN_46, EN_47, EN_48,
    CUSTO1
FROM
    ESTOQUE_PROD1_ENT (NOLOCK)
WHERE
    ROMANEIO_PRODUTO = '{ROMANEIO_PRODUTO}'

Persistência: estado da captura pelo serviço LojaAjusteEstoqueDevolucao; registros na tabela wosk_queue com serviço LojaAjusteEstoqueDevolucao.

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 ilx_ajuste_estoque/setAjusteDevolucao, 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_ENT mais a chave ITENS com o array de linhas de ESTOQUE_PROD1_ENT.

Exemplo ilustrativo de estrutura do conteudo:

{
  "ROMANEIO_PRODUTO": "...",
  "FILIAL": "...",
  "ITENS": []
}

Tratamento de Dados

Sobre o registro atual retornado de ESTOQUE_PROD_ENT:

• ITENS: passa a conter o array de linhas obtidas da consulta a ESTOQUE_PROD1_ENT para o mesmo ROMANEIO_PRODUTO, cada linha com os campos PRODUTO, COR_PRODUTO, EN_1, EN_2, EN_3, EN_4, EN_5, EN_6, EN_7, EN_8, EN_9, EN_10, EN_11, EN_12, EN_13, EN_14, EN_15, EN_16, EN_17, EN_18, EN_19, EN_20, EN_21, EN_22, EN_23, EN_24, EN_25, EN_26, EN_27, EN_28, EN_29, EN_30, EN_31, EN_32, EN_33, EN_34, EN_35, EN_36, EN_37, EN_38, EN_39, EN_40, EN_41, EN_42, EN_43, EN_44, EN_45, EN_46, EN_47, EN_48, CUSTO1.

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:

• Chamada: Requisição HTTP (encapsulada pela rotina de envio ao ILLI).
• Recurso: e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteDevolucao
• Corpo de entrada: objeto/array conteudo do registro da fila (cabeçalho da entrada + ITENS).
• Processamento: envio do payload e leitura da resposta JSON com indicadores success e message.

{
  "FILIAL": "...",
  "ROMANEIO_PRODUTO": "...",
  "ITENS": [ { "PRODUTO": "...", "CUSTO1": "..." } ]
}

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 LojaAjusteEstoqueDevolucao, ordenando pelo horário de processamento para priorizar ocorrências mais antigas.

Assunto da mensagem conforme definido no código: "Erros na Integração do LINX para o ILLI - Ajuste de Estoque - Devolução"; destinatários fixos no código; colunas exibidas incluem chave decomposta em FILIAL e ROMANEIO_PRODUTO, EMISSAO extraída do conteúdo e normalização de quebras de linha na mensagem de erro.

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_ENT com ACERTO_ENTRADA = '1' e TIPO_ENTRADA = '4', enriquecer com linhas de ESTOQUE_PROD1_ENT e gravar na fila com chave FILIAL-ROMANEIO_PRODUTO.	Registro pendente na fila com conteúdo completo e chave consistente.
Capturador	Captura por chave	Para cada chave no formato FILIAL-ROMANEIO_PRODUTO, deve consultar a entrada 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/setAjusteDevolucao, 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.