LojaAjusteEstoqueTransferencia (STATUS: DOCUMENTADO)

Documentação Técnica

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

Descrição

Este serviço de ajuste de estoque (transferência) identifica faturamentos de saída no LINX com natureza e série previstas para movimentação entre filiais e encaminha os dados ao ILLI.
Garante captura, fila e registro de resultado da integração.

Capturador

Descrição Conceitual

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

A captura por chave aceita três partes (FILIAL, SERIE_NF, NF_SAIDA), relendo cabeçalho e itens e reenfileirando com token preservado quando aplicável.

Fonte

Origem consultada: view FATURAMENTO. Itens: 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: cabeçalho em FATURAMENTO conforme Fonte; itens em FATURAMENTO_PROD por FILIAL, NF_SAIDA e SERIE_NF.

Consulta dinâmica (captura automática): FILIAL IN (...), NATUREZA_SAIDA = '120.01', SERIE_NF = '56', NOTA_CANCELADA = '0', DATA_PARA_TRANSFERENCIA >= filtro, ORDER BY DATA_PARA_TRANSFERENCIA ASC, OFFSET ... FETCH NEXT ... conforme limite do serviço LojaAjusteEstoqueTransferencia.

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

Validação (captura por chave): três partes na chave; senão erro de chave inválida.

Persistência: serviço LojaAjusteEstoqueTransferencia, chave FILIAL-SERIE_NF-NF_SAIDA e estado do capturador.

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 envio ocorre via setAjusteTransferencia; situação e mensagem são gravadas na tabela da fila de integração.

Estruturação de Dados

Campos do `conteudo` (cabeçalho + `ITENS`)
Campo no payload	Campo de origem
`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`	Array de `FATURAMENTO_PROD` (`F1` a `F48`, `PRECO`, etc.)

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": []
}

Tratamento de Dados

ITENS: linhas de FATURAMENTO_PROD para a mesma combinação FILIAL, NF_SAIDA e SERIE_NF, com F1 a F48 e PRECO.
Envio: conteudo como JSON sem mapeamento adicional no arquivo analisado.

Integração com o ILLI

Chamada: Requisição HTTP
Recurso: /bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteTransferencia
Método HTTP: POST
Corpo: conteudo do registro na fila, incluindo ITENS.

Tratamento de retorno

Ausência de resposta ou retorno sem success e sem message gera exceção e situação erro. Quando success não está vazio, situação sucesso; caso contrário situação erro. Em exceção, mensagem persistida; prefixo de JSON não reconhecido pode estruturar 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 LojaAjusteEstoqueTransferencia 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 filtrar `FATURAMENTO` com natureza `120.01`, série `56`, nota não cancelada, anexar `FATURAMENTO_PROD` e gravar na fila `LojaAjusteEstoqueTransferencia`.	Registro pendente com chave tríplice.
Capturador	Captura por chave	Deve validar três partes na chave e reenfileirar com token quando existir.	Chave inválida gera exceção.
Fila de Processamento	Integração ILLI	Deve enviar ao recurso `/bibliotecas/e3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjusteTransferencia`, interpretar sucesso ou erro com mensagem e persistir situação na tabela da fila de integração.	Situação e mensagem coerentes com o retorno do ILLI.