LojaAjusteEstoque (STATUS: CRIADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (ClienteAjuste de Estoque Loja)
Biblioteca	wosk_loja_clientewosk_loja_ajuste_estoque
Data	25/26/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
25/26/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo Loja ClienteAjuste de Estoque (LINX → ILLI).

Descrição

Este serviço de clientesajuste de varejoestoque no LINX aenvia partircontagens doajustadas PDVe integraitens comde grade para o ILLIILLI, viaalinhando filao quandoestoque necessário.da loja ao processo corporativo.
CoordenaGarante capturaque automáticaapenas oufiliais porprevistas código,participem, validarespeitando endereçodatas de transferência e documento e registra o resultadoestado de cada enviocaptura paraantes acompanhamento.de enfileirar e processar o envio.

Capturador

Descrição Conceitual

A captura automática consulta CLIENTES_VAREJOESTOQUE_PROD_CONTAGEM quando o estado do serviço LojaClienteLojaAjusteEstoque está apto, com filtro por DATA_PARA_TRANSFERENCIA, ESTOQUE_AJUSTADO, filiais permitidas e exclusões de filiais centrais, ordenação por data e código e paginação conforme o limite configurado para o serviço LojaClienteLojaAjusteEstoque, alinhada ao processamento cronológico. e ao semáforo de captura. Para cada linha, atualizamonta posição,a chave NOME_CONTAGEM-FILIAL, anexa os itens de ESTOQUE_PROD_CTG_AJUSTE e grava na fila de integração com serviço LojaClienteLojaAjusteEstoque e chave CODIGO_CLIENTE; ao final do lote ou em erro, atualiza o estado do capturador..

A origem dos dados é a tabela CLIENTES_VAREJO com enriquecimento por município e país via view W_LCF_LX_MUNICIPIO e tabela LCF_LX_PAIS. A captura por códigochave aceita umuma ou mais chaves no padrão CODIGO_CLIENTENOME_CONTAGEM-FILIAL; para cada chave válida, relê o cabeçalho da contagem em ESTOQUE_PROD_CONTAGEM, reutilizarecarrega aos mesma projeção com filtroitens em listaESTOQUE_PROD_CTG_AJUSTE e enfileira cada registro,reenfileira preservando o token quando já existir para ao mesmamesmo chave.registro na fila.

Fonte

Origem consultada: tabela ESTOQUE_PROD_CONTAGEM.

Consulta principal:

SELECT
    CLI.CODIGO_CLIENTE,NOME_CONTAGEM,
    CLI.CLIENTE_VAREJO,
    CLI.CPF_CGC,
    CLI.RG_IE,
    CLI.ANIVERSARIO,
    CLI.TIPO_LOGRADOURO,
    CLI.ENDERECO,
    CLI.NUMERO,
    CLI.COMPLEMENTO,
    CLI.BAIRRO,
    CLI.CIDADE,
    CLI.UF,
    CLI.CEP,
    CLI.PAIS,
    LLM.COD_MUNICIPIO_IBGE AS IBGE,
    LLP.COD_PAIS_BC AS PAIS_BC,
    CLI.DDD,
    CLI.TELEFONE,
    CLI.DDD_CELULAR,
    CLI.CELULAR,
    CLI.EMAIL,
    CLI.CODIGO_CONTATO,
    CLI.FILIAL,
    CLI.ESTRANGEIRO,EMISSAO,
    CLI.TIPO_VAREJO,RESPONSAVEL,
    CLI.TIPO_BLOQUEIO,
    CLI.CADASTRAMENTO,
    CLI.OBS,
    CLI.SEXO,ESTOQUE_AJUSTADO,
    CLI.STATUS,DATA_AJUSTE,
    CLI.DATA_PARA_TRANSFERENCIATIPO,
    SALDO_ARMAZENADO,
    CONTAGEM_POR_AREA_FECHADA,
    DATA_PARA_TRANSFERENCIA,
    NOME_CONTAGEM_ANTERIOR
FROM
    CLIENTES_VAREJO CLIESTOQUE_PROD_CONTAGEM (NOLOCK)
    LEFT JOIN W_LCF_LX_MUNICIPIO LLM (NOLOCK) ON (
        DBO.FX_REPLACE_CARACTER_ESPECIAL_NFE(DEFAULT, LTRIM(RTRIM(CLI.CIDADE))) = LLM.DESC_MUNICIPIO
        AND CLI.UF = LLM.UF
    )
    LEFT JOIN LCF_LX_PAIS LLP (NOLOCK) ON (CLI.PAIS = LLP.DESC_PAIS)

Operações com Dados

Leitura: Consulta da tabela CLIENTES_VAREJOESTOQUE_PROD_CONTAGEM com LEFT JOIN em W_LCF_LX_MUNICIPIO e LCF_LX_PAIS, conforme SQL da seção Fonte.; itens de linha carregados a partir de ESTOQUE_PROD_CTG_AJUSTE pela mesma NOME_CONTAGEM usada no registro atual.

Consulta dinâmica (captura automática): reutiliza a projeção com filtroWHERE emFILIAL IN (...) (lista derivada de FILIAIS excluindo códigos fixos de estoque central e centro de distribuição), ESTOQUE_AJUSTADO = '1', DATA_PARA_TRANSFERENCIA >= o filtro efetivo (padrão de data quando não informado), ordenaçãoORDER BY DATA_PARA_TRANSFERENCIA ASC e paginação (OFFSET ... ROWS FETCH NEXT ... ROWS ONLY/FETCH) conforme o limite configurado para o serviço LojaClienteLojaAjusteEstoque e o estado do capturador.capturador (offset, chave e data de posição).

Consulta dinâmica (captura por código)chave): mesma projeção com CODIGO_CLIENTEWHERE INNOME_CONTAGEM (= ... AND FILIAL = ... obtidos ao partir a chave informada.

Validação (captura por chave): a chave deve conter exatamente duas partes separadas por hífen (NOME_CONTAGEM e FILIAL).; caso contrário o fluxo interrompe com erro de chave inválida.

Persistência: grava itens pendentes na Fila de Processamento, com serviço LojaClienteLojaAjusteEstoque e chave CODIGO_CLIENTENOME_CONTAGEM-FILIAL (preservando token existente quando jáaplicável existirna para a mesma chave)recaptura); o estado do capturador mantém offset, chave de posiçãoo, data de posição, filtro e situação da(parado, captura.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, montaenvia o corpo JSON para oao endpoint ILLI de pessoa/cliente,ajuste validade IBGE e código BACEN quando aplicável,estoque, interpreta o retorno JSON (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 trecho do corpo enviado ao ILLI (estrutura resumida)alinhada ao conteudo):

{
  "codigo"NOME_CONTAGEM": "...<NOME_CONTAGEM>",
  "nome"FILIAL": "...<FILIAL>",
  "endereco": {
    "cep"EMISSAO": "00000000",
    "referencia": "<EMISSAO>",
  "logradouro"RESPONSAVEL": "...<RESPONSAVEL>",
  "numero"OBS": "...<OBS>",
  "complemento"ESTOQUE_AJUSTADO": "...<ESTOQUE_AJUSTADO>",
  "bairro"DATA_AJUSTE": "...<DATA_AJUSTE>",
  "cidade"TIPO": "...<TIPO>",
  "uf"SALDO_ARMAZENADO": "...<SALDO_ARMAZENADO>",
  "pais"CONTAGEM_POR_AREA_FECHADA": "...<CONTAGEM_POR_AREA_FECHADA>",
  "codigo_ibge"DATA_PARA_TRANSFERENCIA": "...<DATA_PARA_TRANSFERENCIA>",
  "codigo_bacen"NOME_CONTAGEM_ANTERIOR": "..."
  },
  "tipo_cliente": ["CLIENTE"],
  "filialCadastro": "...<NOME_CONTAGEM_ANTERIOR>",
  "contatos"ITENS": [
    {
      "tipo"NOME_CONTAGEM": "TELEFONE"<NOME_CONTAGEM>",
      "contato"PRODUTO": "11999999999"<PRODUTO>",
      "COR_PRODUTO": "<COR_PRODUTO>",
      "QTDE_AJUSTE": "<QTDE_AJUSTE>",
      "A1": "<A1>",
      "A2": "<A2>",
      "DATA_PARA_TRANSFERENCIA": "<DATA_PARA_TRANSFERENCIA_ITEM>"
    }
  ],
  "situacao": "1",
  "tipo": "FISICA",
  "cpf": "00000000000"
}

 

Tratamento de Dados

Sobre o registroprocessamento atualna lidoclasse Queue antes do conteudo na fila:envio:

• DDD,Base do envio: o array TELEFONEconteudo, DDD_CELULAR,do CELULAR:registro normalizadosatual comé remoç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 dígitosreconhecido e(prefixo montagemtextual depadronizado entradasno emfluxo), contatoso retorno persistido pode incluir estrutura com tipos TELEFONE, CELULAR e EMAIL quando informados.
• TIPO_LOGRADOURO, ENDERECO: concatenados para formar o logradouro completo; se o resultado exceder 250 caracteres, aplicado substr até 250.
• COMPLEMENTO: se o comprimento exceder 250 caracteres, aplicado substr até 250.
• CEP: somente dígitos e preenchimento à esquerda com zeros até tamanho 8.
• NUMERO: somente dígitos no payload de endereço.
• UF: se vazio ou com mais de 2 caracteres, usa regra condicionada a ESTRANGEIRO (incluindo uso de EX para estrangeiro).
• CPF_CGC, RG_IE: documentos numéricos padronizados com zeros à esquerda conforme tipo físico ou jurídico; tipo derivado pelo tamanho numérico de CPF_CGC após normalização.
• Validação pré-envio: para não estrangeiro com UF diferente de EX, exige IBGE preenchido; para qualquer registro, exige PAIS_BC preenchido (mensagensindicador de erro específicase setrecho ausentes).de dados interpretado.

Integração com o ILLI

Chamada de integração com o ILLI (via rotina de integração):

• Chamada: Requisição HTTP (encapsulada pela rotina de envio ao ILLI).
• Recurso: /bibliotecas/48df1d4a-2a73-4afc-be75-a8104533cda0/ilx_pessoa/setClientee3a6737d-ac74-4ed6-9668-e3921320c29f/ilx_ajuste_estoque/setAjuste
• Método HTTP: POST
• Cabeçalhos: os definidos internamente pela rotina de integração ILLI (não fixados neste arquivo).
• Corpo: objeto JSON comcorrespondente os campos mapeados a partir doao conteudo do registro da fila, incluindo endereco,o array contatosITENS, documentos e metadados de cadastro..

Exemplo de corpo enviado (estrutura alinhada ao objeto montado no código; valores ilustrativos):

{
  "id": false,
  "codigo": "00000000000123",
  "nome": "Cliente Exemplo",
  "endereco": {
    "cep": "01310100",
    "referencia": "",
    "logradouro": "RUA EXEMPLO 100",
    "numero": "100",
    "complemento": "SALA 1",
    "bairro": "CENTRO",
    "cidade": "SAO PAULO",
    "uf": "SP",
    "pais": "BRASIL",
    "codigo_ibge": "3550308",
    "codigo_bacen": "1058"
  },
  "tipo_cliente": ["CLIENTE"],
  "filialCadastro": "FILIAL01",
  "genero": "M",
  "grupo": "CLIENTE VAREJO",
  "complemento": "OBS",
  "contatos": [
    { "tipo": "TELEFONE", "contato": "11999999999" }
  ],
  "situacao": "1",
  "data_nascimento": "1990-01-01 00:00:00",
  "data_cadastro": "2024-01-01 10:00:00",
  "data": "2024-01-02 08:00:00",
  "tipo": "FISICA",
  "cpf": "12345678901",
  "identidade": "1234567"
}

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 vazia decom success e message: ambos vazios: 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 JSON não reconhecido, o retorno estruturado pode incluir errorcampos de erro e datadados com o trecho analisado.parseados.

Notificação

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

Endpoint (API)

O endpoint processa o cadastro de cliente de varejo a partir do corpo da requisição: o fluxo de entrada é o array de parâmetros no processamento principal, validado contra tipo e obrigatoriedade conforme o schema do serviço, com persistência em CLIENTES_VAREJO e regras de inclusão, atualização, filial e documento. O payload de entrada é um objeto JSON (ou equivalente) cujas chaves correspondem aos campos da tabela ao final da subseção Estruturação de Dados; campos adicionais usados apenas no fluxo interno (CODIGO_CLIENTE, TIPO_VAREJO, OMS, entre outros) podem acompanhar o mesmo corpo quando o chamador os informar.

Estruturação de Dados

Campos adicionais tratados no fluxo interno de gravação (validação complementar e insert/update em CLIENTES_VAREJO): CODIGO_CLIENTE, TIPO_VAREJO, CADASTRAMENTO, DATA_PARA_TRANSFERENCIA, OMS, entre outros previstos no processamento de persistência.

Exemplo de payload enviado para o endpoint (JSON):

{
  "key": "<API_KEY_OU_VAZIO>",
  "CLIENTE_VAREJO": "Nome do Cliente",
  "FILIAL": "01",
  "PF_PJ": true,
  "ESTRANGEIRO": false,
  "CPF_CGC": "12345678901",
  "ENDERECO": "Rua Exemplo",
  "UF": "SP",
  "CEP": "01310100"
}

 

Tratamento de Dados

No método de gravação do cadastro (pré-insert/update e persistência):

• CADASTRAMENTO, DATA_PARA_TRANSFERENCIA: definidos com data/hora atual no início do processamento da requisição.
• TIPO_VAREJO: se não existir na lista carregada de CLIENTE_VAR_TIPOS, forçado para CLIENTE VAREJO.
• ESTRANGEIRO: se vazio, definido como 0; se UF for EX, definido como 1.
• SEXO: se vazio, removido do conjunto de parâmetros antes da gravação.
• CEP: se informado e numericamente zero após avaliação, substituído por sentinela NULL() para o insert.
• CODIGO_CLIENTE: se vazio após normalização, preenchido com CPF_CGC ou, para estrangeiro, com RG_IE; validação específica de obrigatoriedade e tamanho aplicada em seguida.
• Inclusão: verifica duplicidade de documento versus código para não estrangeiro; converte FILIAL numérica para nome via FILIAIS; prefixa OBS com texto fixo de origem PDV; executa insert parametrizado em CLIENTES_VAREJO conforme colunas previstas para o cadastro.
• Alteração: reaproveita CODIGO_CLIENTE, FILIAL, CADASTRAMENTO e TIPO_VAREJO do registro localizado; se OMS for diferente de 1, recalcula DATA_PARA_TRANSFERENCIA e aplica estratégia de mesclagem campo a campo conforme CADASTRAMENTO anterior antes do UPDATE; se OMS for 1, o bloco de atualização é ignorado.

Persistência no LINX

Chamada de persistência no banco LINX:

• Chamada: Operação em banco (insert ou update parametrizado).
• Tabelas: CLIENTES_VAREJO (principal); consultas auxiliares a CLIENTE_VAR_TIPOS e FILIAIS para listas e resolução de filial.
• Processamento: transação com commit ao sucesso ou rollback em falha; erros encapsulados com prefixo CLIENTES_VAREJO: na mensagem.

Tratamento de retorno

Sucesso: retorno com Mensagem igual a OK e Mensagem Detalhada indicando registro com sucesso, além dos campos CODIGO_CLIENTE, CADASTRAMENTO e DATA_PARA_TRANSFERENCIA atualizados no array de resposta.
Falha de validação inicial: exceção com mensagens concatenadas dos erros de campo.
Falha na gravação: exceção com mensagem originada do banco ou regra de negócio (incluindo conflito de documento/código).

O endpoint não implementa envio de notificação de erros; o acompanhamento de falhas da integração em fila é tratado na Fila de Processamento.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura e enfileiramento	Com estado apto e filtro de datafiltros válido,lidos, deve ler CLIENTES_VAREJOESTOQUE_PROD_CONTAGEM com joinscritérios de municípiofilial permitida, ESTOQUE_AJUSTADO, data mínima de transferência e país,paginação, paginaranexar peloitens limitede configuradoESTOQUE_PROD_CTG_AJUSTE e gravar cada registrocontagem na fila de integração com serviço LojaClienteLojaAjusteEstoque e chave CODIGO_CLIENTENOME_CONTAGEM-FILIAL.	Registro pendente na fila com conteúdo alinhado às consultaconsultas e posição de captura atualizada.
Capturador	Captura por códigochave	Para cada chave no padrão CODIGO_CLIENTENOME_CONTAGEM informado,-FILIAL, deve consultarreler ao mesma projeçãocabeçalho e gravaritens e regravar na fila preservando token existente quando houver.já existir.	Registros reenfileiradosReenfileiramento com chave consistente e token reutilizado quando aplicável.
Fila de Processamento	Integração ILLI	Ao processar registro pendente, deve montarenviar o JSON,conteudo chamar oao recurso /bibliotecas/48df1d4a-2a73-4afc-be75-a8104533cda0/ilx_pessoa/setClientee3a6737d-ac74-4ed6-9668-e3921320c29f/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 (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.
Endpoint (API)	Cadastro PDV	Ao receber payload válido, deve inserir ou atualizar CLIENTES_VAREJO conforme regras de documento, filial e OMS, retornando Mensagem OK em sucesso.	Registro gravado no LINX e resposta com código e datas coerentes com a operação.