LojaAjusteEstoqueBaixaFurto (STATUS: CRIADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Ajuste de Estoque — Baixa Furto)
Biblioteca	wosk_loja_ajuste_estoque_baixa_furto
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 Baixa Furto (LINX → ILLI).

Descrição

Esta biblioteca identifica no LINX faturamentos com natureza de saída compatível com baixa por furto e encaminha o detalhamento ao ILLI para ajuste de estoque.
Garante fila, integração e registro de sucesso ou erro para cada nota fiscal de saída elegível.

Capturador

Descrição Conceitual

A captura automática consulta a view FATURAMENTO 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), NATUREZA_SAIDA = '171.05', data mínima de transferência e ordenação/paginação por DATA_PARA_TRANSFERENCIA e NF_SAIDA, conforme conceito de ordenação e paginação por data. Para cada registro retornado, obtém-se as linhas de produto em FATURAMENTO_PROD, compõe-se a chave FILIAL-SERIE_NF-NF_SAIDA e o registro é encaminhado à fila de processamento do serviço LojaAjusteEstoqueBaixaFurto, 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 três partes (FILIAL, SERIE_NF, NF_SAIDA), consulta FATURAMENTO com WHERE fixo por filial, série e nota e, para cada linha retornada, inclui o detalhamento de FATURAMENTO_PROD antes de gravar na fila com o token já existente quando houver.

Fonte

Origem consultada: view FATURAMENTO.
Complemento de linhas de produto: tabela FATURAMENTO_PROD.

Operações com Dados

Leitura principal (base da consulta de captura):

SELECT
    NF_SAIDA,
    SERIE_NF,
    FILIAL,
    EMISSAO,
    OBS,
    NATUREZA_SAIDA,
    TIPO_FATURAMENTO,
    DATA_SAIDA,
    DATA_PARA_TRANSFERENCIA
FROM
    FATURAMENTO (NOLOCK)

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

SELECT
    NF_SAIDA,
    SERIE_NF,
    FILIAL,
    EMISSAO,
    OBS,
    NATUREZA_SAIDA,
    TIPO_FATURAMENTO,
    DATA_SAIDA,
    DATA_PARA_TRANSFERENCIA
FROM
    FATURAMENTO (NOLOCK)
WHERE FILIAL IN ('...')
  AND NATUREZA_SAIDA = '171.05'
  AND DATA_PARA_TRANSFERENCIA >= '{filtro_DATA_PARA_TRANSFERENCIA}'
ORDER BY DATA_PARA_TRANSFERENCIA ASC, NF_SAIDA ASC
OFFSET {offset} ROWS FETCH NEXT {limite} ROWS ONLY

Consulta dinâmica na captura por chave:

SELECT
    NF_SAIDA,
    SERIE_NF,
    FILIAL,
    EMISSAO,
    OBS,
    NATUREZA_SAIDA,
    TIPO_FATURAMENTO,
    DATA_SAIDA,
    DATA_PARA_TRANSFERENCIA
FROM
    FATURAMENTO (NOLOCK)
WHERE FILIAL = '{FILIAL}'
  AND SERIE_NF = '{SERIE_NF}'
  AND NF_SAIDA = '{NF_SAIDA}'

Detalhamento de produtos por nota:

SELECT
    PRODUTO,
    COR_PRODUTO,
    F1, F2, F3, F4, F5, F6, F7, F8, F9, F10,
    F11, F12, F13, F14, F15, F16, F17, F18, F19, F20,
    F21, F22, F23, F24, F25, F26, F27, F28, F29, F30,
    F31, F32, F33, F34, F35, F36, F37, F38, F39, F40,
    F41, F42, F43, F44, F45, F46, F47, F48,
    PRECO
FROM
    FATURAMENTO_PROD (NOLOCK)
WHERE
    FILIAL = '{FILIAL}'
    AND NF_SAIDA = '{NF_SAIDA}'
    AND SERIE_NF = '{SERIE_NF}'

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

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/setAjusteBaixaFurto, 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 FATURAMENTO mais a chave ITENS com o array de linhas de FATURAMENTO_PROD.

Exemplo ilustrativo de estrutura do conteudo:

{
  "NF_SAIDA": "...",
  "SERIE_NF": "...",
  "FILIAL": "...",
  "ITENS": []
}

Tratamento de Dados

Sobre o registro atual retornado de FATURAMENTO:

• ITENS: passa a conter o array de linhas obtidas da consulta a FATURAMENTO_PROD para a mesma combinação FILIAL, NF_SAIDA e SERIE_NF, cada linha com os campos PRODUTO, COR_PRODUTO, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24, F25, F26, F27, F28, F29, F30, F31, F32, F33, F34, F35, F36, F37, F38, F39, F40, F41, F42, F43, F44, F45, F46, F47, F48, PRECO.

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/setAjusteBaixaFurto
• Corpo de entrada: objeto/array conteudo do registro da fila (cabeçalho do faturamento + ITENS).
• Processamento: envio do payload e leitura da resposta JSON com indicadores success e message.

{
  "FILIAL": "...",
  "NF_SAIDA": "...",
  "SERIE_NF": "...",
  "ITENS": [ { "PRODUTO": "...", "PRECO": "..." } ]
}

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 LojaAjusteEstoqueBaixaFurto, 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 - Saída Normal"; destinatários fixos no código; colunas exibidas incluem chave decomposta em FILIAL, SERIE_NF, NF_SAIDA, 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 FATURAMENTO com NATUREZA_SAIDA = '171.05', enriquecer com linhas de FATURAMENTO_PROD e gravar na fila com chave FILIAL-SERIE_NF-NF_SAIDA.	Registro pendente na fila com conteúdo completo e chave consistente.
Capturador	Captura por chave	Para cada chave no formato FILIAL-SERIE_NF-NF_SAIDA, deve consultar o faturamento 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/setAjusteBaixaFurto, 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.