Ir para o conteúdo principal

LojaAjusteEstoque (STATUS: CRIADO)

Documentação Técnica
Nome do cliente OSKLEN
Nome do projeto Integração LINX → ILLI (Ajuste de Estoque — Contagem)
Biblioteca wosk_loja_ajuste_estoque
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 (LINX → ILLI).

Descrição

Este serviço de ajuste de estoque por contagem no LINX encaminha ao ILLI os dados de contagens já marcadas para transferência, com o detalhe dos itens ajustados.
Garante fila, integração e registro de sucesso ou erro para cada contagem elegível por filial.

Capturador

Descrição Conceitual

A captura automática consulta a view ESTOQUE_PROD_CONTAGEM quando o estado do serviço LojaAjusteEstoque está apto (reinício a partir de situação concluída ou continuação em andamento), restringindo a filiais de loja definidas em ambiente (excluindo estoque central e centro de distribuição), ESTOQUE_AJUSTADO = '1', data mínima de transferência e processamento cronológico (ordenação e paginação por data) com ORDER BY DATA_PARA_TRANSFERENCIA ASC, OFFSET e FETCH NEXT conforme o limite de registros por lote configurado para o serviço LojaAjusteEstoque. Para cada linha retornada, obtém-se o detalhe em ESTOQUE_PROD_CTG_AJUSTE, compõe-se a chave NOME_CONTAGEM-FILIAL e o registro é gravado na Fila de Processamento com serviço LojaAjusteEstoque, atualizando offset, chave e data de posição até concluir o ciclo.

A captura por chave aceita uma ou mais chaves no formato NOME_CONTAGEM-FILIAL; se a chave não tiver duas partes, o fluxo interrompe com erro de chave inválida. Para cada chave válida, consulta-se ESTOQUE_PROD_CONTAGEM com filtro fixo por nome de contagem e filial, enriquece-se o registro com ITENS a partir de ESTOQUE_PROD_CTG_AJUSTE e grava-se na Fila de Processamento, preservando o token quando já existir para a mesma chave.

Fonte

Origem consultada: view ESTOQUE_PROD_CONTAGEM. Complemento de linhas de produto: tabela ESTOQUE_PROD_CTG_AJUSTE.

Consulta principal:

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)

Operações com Dados

Leitura: consulta da view ESTOQUE_PROD_CONTAGEM conforme SQL da seção Fonte; detalhamento de itens por NOME_CONTAGEM na tabela ESTOQUE_PROD_CTG_AJUSTE.

Consulta dinâmica (captura automática): reutiliza a projeção com WHERE FILIAL IN (...) (lista de filiais de loja, excluindo as removidas no código), ESTOQUE_AJUSTADO = '1', DATA_PARA_TRANSFERENCIA maior ou igual ao filtro do capturador, ORDER BY DATA_PARA_TRANSFERENCIA ASC, OFFSET e FETCH NEXT com o limite de registros por lote configurado para o serviço LojaAjusteEstoque.

Consulta dinâmica (captura por chave): mesma projeção com WHERE NOME_CONTAGEM = '{parte1}' AND FILIAL = '{parte2}' obtidas da chave.

Detalhamento de itens por contagem: consulta à tabela ESTOQUE_PROD_CTG_AJUSTE com WHERE NOME_CONTAGEM = '{NOME_CONTAGEM}', retornando colunas de produto, grade A1 a A48, custos CUSTO1 a CUSTO4, CM_OPERACAO, DATA_PARA_TRANSFERENCIA, QTDE_AJUSTE, COR_PRODUTO e PRODUTO.

Persistência: estado do capturador pelo serviço LojaAjusteEstoque (offset, chave de posição, datas, filtro e situação); registros pendentes na tabela da fila de integração com serviço LojaAjusteEstoque e chave NOME_CONTAGEM-FILIAL.

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 recurso ILLI de ajuste de estoque, interpreta o JSON de 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

O conteudo gravado na fila corresponde ao registro atual da view ESTOQUE_PROD_CONTAGEM após inclusão da chave ITENS com o array de linhas lidas de ESTOQUE_PROD_CTG_AJUSTE para o mesmo NOME_CONTAGEM.

  • Chamada: Requisição HTTP
  • Recurso: e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjuste
  • Método HTTP: POST

Exemplo de payload enviado ao ILLI (JSON):

{
  "NOME_CONTAGEM": "<NOME_CONTAGEM>",
  "FILIAL": "<FILIAL>",
  "EMISSAO": "<EMISSAO>",
  "RESPONSAVEL": "<RESPONSAVEL>",
  "OBS": "<OBS>",
  "ESTOQUE_AJUSTADO": "<ESTOQUE_AJUSTADO>",
  "DATA_AJUSTE": "<DATA_AJUSTE>",
  "TIPO": "<TIPO>",
  "SALDO_ARMAZENADO": "<SALDO_ARMAZENADO>",
  "CONTAGEM_POR_AREA_FECHADA": "<CONTAGEM_POR_AREA_FECHADA>",
  "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA>",
  "NOME_CONTAGEM_ANTERIOR": "<NOME_CONTAGEM_ANTERIOR>",
  "ITENS": [
    {
      "NOME_CONTAGEM": "<NOME_CONTAGEM>",
      "PRODUTO": "<PRODUTO>",
      "COR_PRODUTO": "<COR_PRODUTO>",
      "QTDE_AJUSTE": "<QTDE_AJUSTE>",
      "A1": "<A1>",
      "A48": "<A48>",
      "CUSTO1": "<CUSTO1>",
      "CM_OPERACAO": "<CM_OPERACAO>",
      "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA_ITEM>"
    }
  ]
}
Campos raiz do conteudo enviado ao ILLI
Campo Tipo Obrigatório Descrição
key string não Chave interna da fila quando aplicável à plataforma; o envio ao ILLI usa o array de conteúdo montado na captura.
NOME_CONTAGEM string sim Identificador da contagem na view ESTOQUE_PROD_CONTAGEM.
FILIAL string sim Código da filial na view ESTOQUE_PROD_CONTAGEM.
EMISSAO string não Data ou referência de emissão conforme origem.
RESPONSAVEL string não Responsável informado na contagem.
OBS string não Observações da contagem.
ESTOQUE_AJUSTADO string sim Indicador de estoque ajustado (1 na seleção do capturador).
DATA_AJUSTE string não Data do ajuste conforme origem.
TIPO string não Tipo da contagem.
SALDO_ARMAZENADO string não Saldo armazenado informado.
CONTAGEM_POR_AREA_FECHADA string não Indicador de contagem por área fechada.
DATA_PARA_TRANSFERENCIA string sim Data e hora mínima de transferência usada no filtro e ordenação do capturador.
NOME_CONTAGEM_ANTERIOR string não Referência de contagem anterior quando existir.
ITENS array sim Linhas de ESTOQUE_PROD_CTG_AJUSTE para o NOME_CONTAGEM; ver tabela de elementos.
Estrutura de cada elemento de ITENS
Campo Tipo Obrigatório Descrição
NOME_CONTAGEM string sim Repete o identificador da contagem na linha de item.
PRODUTO string sim Código do produto.
COR_PRODUTO string sim Cor do produto.
QTDE_AJUSTE string sim Quantidade ajustada.
A1 string não Quantidade de grade posição 1.
A2 string não Quantidade de grade posição 2.
A3 string não Quantidade de grade posição 3.
A4 string não Quantidade de grade posição 4.
A5 string não Quantidade de grade posição 5.
A6 string não Quantidade de grade posição 6.
A7 string não Quantidade de grade posição 7.
A8 string não Quantidade de grade posição 8.
A9 string não Quantidade de grade posição 9.
A10 string não Quantidade de grade posição 10.
A11 string não Quantidade de grade posição 11.
A12 string não Quantidade de grade posição 12.
A13 string não Quantidade de grade posição 13.
A14 string não Quantidade de grade posição 14.
A15 string não Quantidade de grade posição 15.
A16 string não Quantidade de grade posição 16.
A17 string não Quantidade de grade posição 17.
A18 string não Quantidade de grade posição 18.
A19 string não Quantidade de grade posição 19.
A20 string não Quantidade de grade posição 20.
A21 string não Quantidade de grade posição 21.
A22 string não Quantidade de grade posição 22.
A23 string não Quantidade de grade posição 23.
A24 string não Quantidade de grade posição 24.
A25 string não Quantidade de grade posição 25.
A26 string não Quantidade de grade posição 26.
A27 string não Quantidade de grade posição 27.
A28 string não Quantidade de grade posição 28.
A29 string não Quantidade de grade posição 29.
A30 string não Quantidade de grade posição 30.
A31 string não Quantidade de grade posição 31.
A32 string não Quantidade de grade posição 32.
A33 string não Quantidade de grade posição 33.
A34 string não Quantidade de grade posição 34.
A35 string não Quantidade de grade posição 35.
A36 string não Quantidade de grade posição 36.
A37 string não Quantidade de grade posição 37.
A38 string não Quantidade de grade posição 38.
A39 string não Quantidade de grade posição 39.
A40 string não Quantidade de grade posição 40.
A41 string não Quantidade de grade posição 41.
A42 string não Quantidade de grade posição 42.
A43 string não Quantidade de grade posição 43.
A44 string não Quantidade de grade posição 44.
A45 string não Quantidade de grade posição 45.
A46 string não Quantidade de grade posição 46.
A47 string não Quantidade de grade posição 47.
A48 string não Quantidade de grade posição 48.
CUSTO1 string não Custo 1.
CUSTO2 string não Custo 2.
CUSTO3 string não Custo 3.
CUSTO4 string não Custo 4.
CM_OPERACAO string não Custo médio ou operação associada conforme origem.
DATA_PARA_TRANSFERENCIA string não Data e hora para transferência na linha do item.
 
Tratamento de Dados

Sobre o registro atual retornado de ESTOQUE_PROD_CONTAGEM antes do envio à fila:

  • ITENS: passa a conter o array de linhas obtidas da consulta a ESTOQUE_PROD_CTG_AJUSTE para o mesmo NOME_CONTAGEM, preservando 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 e 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 além do conteúdo já montado na captura.

 
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/setAjuste
  • Método HTTP: POST
  • Corpo de entrada: objeto ou array correspondente ao conteudo do registro da fila (cabeçalho da contagem + ITENS).
  • Processamento: envio do payload e leitura da resposta JSON com indicadores success e message.
 
Tratamento de retorno

Ausência de resposta JSON: lança exceção indicando que não houve resposta; situação final 4 na tabela da fila de integração.
Resposta sem success e sem message: tratada como retorno não reconhecido (exceção), situação 4.
Sucesso: quando success não está vazio, situação 2; caso contrário situação 4 com mensagem em message quando existir.
Em exceção genérica, a mensagem é persistida; se a mensagem indicar trecho após prefixo de JSON não reconhecido, o retorno estruturado pode incluir error e data com o conteúdo analisado.

 
Notificação

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

Endpoint (API)

O endpoint publica a biblioteca para instanciar dinamicamente as classes internas (por exemplo, capturador ou fila) via parâmetro de classe no padrão da plataforma. O caminho declarado no arquivo da biblioteca é usado como base do recurso HTTP.

 
Estruturação de Dados

A invocação segue o contrato de publicação de biblioteca: corpo ou parâmetros conforme a plataforma para selecionar a classe alvo e a operação desejada.

  • Chamada: Requisição HTTP
  • Recurso: /bibliotecas/01a79ef5-24bc-4bdc-b797-512284913153/wosk_loja_ajuste_estoque
  • Método HTTP: POST

Exemplo de payload enviado para o endpoint (JSON):

{
  "key": "<API_KEY_OU_VAZIO>",
  "class": "Monitor",
  "method": "run",
  "params": []
}
Contrato ilustrativo do payload de chamada à biblioteca
Campo Tipo Obrigatório Descrição
key string não Chave ou identificador conforme exigência da plataforma de publicação do serviço.
class string sim Nome da classe interna a carregar via fábrica da biblioteca (ex.: Monitor, Queue).
method string variável Método a executar na instância retornada, conforme contrato da plataforma.
params array não Parâmetros do método quando aplicável.
 
Tratamento de Dados

O carregamento dinâmico instancia a classe em WOSK\LojaAjusteEstoque\ conforme o nome informado após normalização do segmento recebido; não há transformação adicional de negócio nesta camada além da resolução da classe.

 
Fluxo do Processo

Diagrama sem nome.jpg


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', filiais de loja permitidas e data mínima de transferência, enriquecer com linhas de ESTOQUE_PROD_CTG_AJUSTE e gravar na fila de integração com chave NOME_CONTAGEM-FILIAL e serviço LojaAjusteEstoque. 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; chave inválida gera erro imediato.
Fila de Processamento Integração ILLI Ao processar registro pendente, deve enviar o conteudo ao recurso ilx_ajuste_estoque/setAjuste, 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 (2 ou 4), a mensagem retornada e o tempo de processamento. Fila atualizada com situação final, mensagem e auditoria de requisição coerentes com o retorno do ILLI.
Endpoint (API) Publicação da biblioteca Ao receber requisição válida para o caminho da biblioteca, deve resolver a classe solicitada e permitir a execução dos métodos expostos (Monitor, Queue) conforme contrato da plataforma. Instância obtida sem erro de reflexão e operação encaminhada conforme parâmetros.
Voltar ao topo