LojaAjusteEstoqueDevolucao (STATUS: DOCUMENTANDO)

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	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 Estoque Devolução (LINX → ILLI).

Descrição

Este serviço de ajuste de estoque (devolução) identifica entradas de estoque no LINX com perfil de devolução e encaminha o cabeçalho e itens ao ILLI.
Garante captura cronológica, fila e registro de sucesso ou erro na integração.

Capturador

Descrição Conceitual

A captura automática consulta ESTOQUE_PROD_ENT quando o estado do serviço LojaAjusteEstoqueDevolucao está apto, com ACERTO_ENTRADA = '1', TIPO_ENTRADA = '4', filiais de loja (excluindo estoque central e centro de distribuição), DATA_PARA_TRANSFERENCIA mínima, ordenação por DATA_PARA_TRANSFERENCIA e ROMANEIO_PRODUTO e paginação conforme o limite configurado para o serviço LojaAjusteEstoqueDevolucao, alinhada ao processamento cronológico e ao semáforo. Para cada linha, anexa ITENS a partir de ESTOQUE_PROD1_ENT, monta a chave FILIAL-ROMANEIO_PRODUTO e grava na Fila de Processamento.

A captura por chave aceita chaves no padrão FILIAL-ROMANEIO_PRODUTO; para cada chave válida, relê o cabeçalho e os itens e reenfileira preservando o token quando já existir.

Fonte

Origem consultada: tabela ESTOQUE_PROD_ENT. Itens: tabela ESTOQUE_PROD1_ENT.

Consulta principal:

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

Operações com Dados

Leitura: consulta de ESTOQUE_PROD_ENT conforme seção Fonte; itens em ESTOQUE_PROD1_ENT por ROMANEIO_PRODUTO.

Consulta dinâmica (captura automática): WHERE FILIAL IN (...), ACERTO_ENTRADA = '1', TIPO_ENTRADA = '4', DATA_PARA_TRANSFERENCIA >= filtro efetivo, ORDER BY DATA_PARA_TRANSFERENCIA ASC, ROMANEIO_PRODUTO ASC, OFFSET ... FETCH NEXT ... conforme limite do serviço LojaAjusteEstoqueDevolucao.

Consulta dinâmica (captura por chave): WHERE FILIAL = ... AND ROMANEIO_PRODUTO = ....

Validação (captura por chave): a chave deve ter duas partes (FILIAL, ROMANEIO_PRODUTO); caso contrário o fluxo interrompe com erro de chave inválida.

Persistência: grava na Fila de Processamento com serviço LojaAjusteEstoqueDevolucao e chave FILIAL-ROMANEIO_PRODUTO; estado do capturador com offset, chave de posição, data de posição e situação.

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 envia o JSON ao ILLI (setAjusteDevolucao), interpreta success e message e persiste situação final, mensagem e tempo na tabela da fila de integração.

Estruturação de Dados

Campos do `conteudo` (cabeçalho `ESTOQUE_PROD_ENT` + `ITENS`)
Campo no payload	Campo de origem
`ROMANEIO_PRODUTO`	`ROMANEIO_PRODUTO`
`FILIAL`	`FILIAL`
`EMISSAO`	`EMISSAO`
`OBS`	`OBS`
`ACERTO_ENTRADA`	`ACERTO_ENTRADA`
`TIPO_ENTRADA`	`TIPO_ENTRADA`
`DATA_DIGITACAO`	`DATA_DIGITACAO`
`DATA_PARA_TRANSFERENCIA`	`DATA_PARA_TRANSFERENCIA`
`ITENS`	Array de `ESTOQUE_PROD1_ENT` (campos `EN_1` a `EN_48`, `CUSTO1`, etc.)

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

{
  "ROMANEIO_PRODUTO": "<ROMANEIO_PRODUTO>",
  "FILIAL": "<FILIAL>",
  "EMISSAO": "<EMISSAO>",
  "OBS": "<OBS>",
  "ACERTO_ENTRADA": "<ACERTO_ENTRADA>",
  "TIPO_ENTRADA": "<TIPO_ENTRADA>",
  "DATA_DIGITACAO": "<DATA_DIGITACAO>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA>",
  "ITENS": [
    {
      "PRODUTO": "<PRODUTO>",
      "COR_PRODUTO": "<COR_PRODUTO>",
      "EN_1": "<EN_1>",
      "CUSTO1": "<CUSTO1>"
    }
  ]
}

Tratamento de Dados

ITENS: preenchido com as linhas de ESTOQUE_PROD1_ENT para o ROMANEIO_PRODUTO do registro atual, incluindo EN_1 a EN_48 e CUSTO1 conforme a consulta de itens.

Base do envio na fila: o conteudo é enviado ao ILLI sem mapeamento adicional declarado no arquivo analisado.

Exceção de retorno: quando a mensagem indica JSON não reconhecido, o retorno persistido pode incluir estrutura de erro e dados parseados.

Integração com o ILLI

Chamada de integração com o ILLI:

Chamada: Requisição HTTP

Recurso: /bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteDevolucao

Método HTTP: POST

Cabeçalhos: os definidos internamente pela rotina de integração ILLI (não fixados neste arquivo).

Corpo: objeto JSON correspondente ao conteudo do registro da fila, incluindo ITENS.

Tratamento de retorno

Ausência de resposta ou retorno sem success e sem message gera exceção e situação 4. Quando success não está vazio, situação 2; caso contrário situação 4. Em exceção, a mensagem é persistida; prefixo de JSON não reconhecido pode gerar retorno estruturado com erro e dados.

Notificação

A notificação de erros consulta registros com falha na tabela da fila de integração para o serviço LojaAjusteEstoqueDevolucao 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 automática	Deve selecionar `ESTOQUE_PROD_ENT` com `ACERTO_ENTRADA = '1'` e `TIPO_ENTRADA = '4'`, anexar `ESTOQUE_PROD1_ENT` e gravar na fila com serviço `LojaAjusteEstoqueDevolucao`.	Registro pendente com chave `FILIAL`-`ROMANEIO_PRODUTO`.
Capturador	Captura por chave	Deve validar duas partes na chave e reenfileirar com token preservado quando existir.	Chave inválida gera exceção; válida atualiza a fila.
Fila de Processamento	Integração ILLI	Deve enviar `conteudo` ao recurso `/bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteDevolucao`, interpretar sucesso ou erro com mensagem e persistir situação final na tabela da fila de integração.	Situação e mensagem coerentes com o retorno do ILLI.