LojaAjusteEstoqueBaixaFurto (STATUS: DOCUMENTADO)

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

Este serviço de ajuste de estoque (baixa por furto) identifica no LINX faturamentos com natureza de saída compatível e encaminha o detalhamento ao ILLI.
Garante captura ordenada, fila de processamento e registro de sucesso ou erro para cada nota elegível.

Capturador

Descrição Conceitual

A captura automática consulta a view FATURAMENTO quando o estado do serviço LojaAjusteEstoqueBaixaFurto está apto, com filtro por filiais de loja (excluindo códigos fixos de estoque central e centro de distribuição), NATUREZA_SAIDA = '171.05', DATA_PARA_TRANSFERENCIA mínima, ordenação por DATA_PARA_TRANSFERENCIA e NF_SAIDA e paginação conforme o limite configurado para o serviço LojaAjusteEstoqueBaixaFurto, alinhada ao processamento cronológico de captura. Para cada linha, anexa ITENS a partir de FATURAMENTO_PROD, monta a chave FILIAL-SERIE_NF-NF_SAIDA e grava na Fila de Processamento com serviço LojaAjusteEstoqueBaixaFurto.

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

Fonte

Origem consultada: view FATURAMENTO. Complemento de itens: tabela FATURAMENTO_PROD.

Consulta principal:

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

Operações com Dados

Leitura: consulta da view FATURAMENTO conforme SQL da seção Fonte; itens de linha carregados a partir de FATURAMENTO_PROD pela mesma combinação FILIAL, NF_SAIDA e SERIE_NF do registro atual.

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

Consulta dinâmica (captura por chave): mesma projeção com WHERE FILIAL = ... AND SERIE_NF = ... AND NF_SAIDA = ... obtidos ao partir a chave informada em três partes.

Validação (captura por chave): a chave deve conter exatamente três partes separadas por hífen (FILIAL, SERIE_NF, NF_SAIDA); caso contrário o fluxo interrompe com erro de chave inválida.

Persistência: grava itens pendentes na Fila de Processamento, com serviço LojaAjusteEstoqueBaixaFurto e chave FILIAL-SERIE_NF-NF_SAIDA (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 serviço ILLI de ajuste de estoque (baixa furto), 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):

{
  "NF_SAIDA": "<NF_SAIDA>",
  "SERIE_NF": "<SERIE_NF>",
  "FILIAL": "<FILIAL>",
  "EMISSAO": "<EMISSAO>",
  "OBS": "<OBS>",
  "NATUREZA_SAIDA": "<NATUREZA_SAIDA>",
  "TIPO_FATURAMENTO": "<TIPO_FATURAMENTO>",
  "DATA_SAIDA": "<DATA_SAIDA>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA>",
  "ITENS": [
    {
      "PRODUTO": "<PRODUTO>",
      "COR_PRODUTO": "<COR_PRODUTO>",
      "F1": "<F1>",
      "F2": "<F2>",
      "PRECO": "<PRECO>"
    }
  ]
}

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 a F48 e PRECO.
• Base do envio na fila: 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/setAjusteBaixaFurto
• 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 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 LojaAjusteEstoqueBaixaFurto 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 FATURAMENTO com NATUREZA_SAIDA = '171.05', enriquecer com linhas de FATURAMENTO_PROD e gravar na fila de integração com serviço LojaAjusteEstoqueBaixaFurto e 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 o conteudo ao recurso /bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteBaixaFurto, 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.