LojaCliente (STATUS: CRIADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Cliente Loja)
Biblioteca	wosk_loja_cliente
Data	25/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
25/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo Loja Cliente (LINX → ILLI).
25/03/2026	1.1	Maykon/Gustavo	Inclusão explícita de método HTTP e payload de entrada na seção Endpoint (API).
25/03/2026	1.2	Maykon/Gustavo	Padronização do Endpoint: bloco Chamada, Recurso, Método e Cabeçalhos em lista.

Descrição

Esta biblioteca mantém o cadastro de clientes de varejo no LINX a partir do PDV e encaminha os dados para o ILLI quando há necessidade de integração em fila.
Ela organiza captura automática ou por código, valida dados de endereço e documento e registra o resultado de cada envio para acompanhamento.

Capturador

Descrição Conceitual

A captura automática recupera o estado do serviço LojaCliente (offset, chave, datas e filtro), reinicia o ciclo quando a situação anterior estava concluída e, enquanto o estado for parado ou em execução, consulta clientes em CLIENTES_VAREJO com DATA_PARA_TRANSFERENCIA a partir do filtro, ordenando por data e código e paginando com limite configurado (woskLimiteCaptura::LojaCliente), em linha com o conceito de semáforo e com processamento cronológico (ordenação e paginação por data). Para cada linha retornada, atualiza o filtro interno com CODIGO_CLIENTE e DATA_PARA_TRANSFERENCIA, grava o registro na fila de processamento identificada pelo serviço LojaCliente e avança posição até não haver mais linhas na página; ao final marca o ciclo como concluído ou, em erro, como problema com detalhes no filtro.

A captura por código aceita um ou mais CODIGO_CLIENTE, monta a consulta com WHERE CLI.CODIGO_CLIENTE IN (...) sobre a mesma projeção da captura automática e, para cada linha, inclui na fila preservando o token já existente quando houver registro anterior para a mesma chave.

Fonte

Origem consultada: tabela CLIENTES_VAREJO com enriquecimento por município e país via view W_LCF_LX_MUNICIPIO e tabela LCF_LX_PAIS.

Operações com Dados

Consulta base utilizada na captura (projeção compartilhada entre execução automática e captura por código):

SELECT
    CLI.CODIGO_CLIENTE,
    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,
    CLI.TIPO_VAREJO,
    CLI.TIPO_BLOQUEIO,
    CLI.CADASTRAMENTO,
    CLI.OBS,
    CLI.SEXO,
    CLI.STATUS,
    CLI.DATA_PARA_TRANSFERENCIA
FROM
    CLIENTES_VAREJO CLI ( 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)

Consulta dinâmica na captura automática (mesmo SELECT do bloco anterior, com WHERE, ORDER BY, OFFSET e FETCH montados em tempo de execução):

SELECT
    CLI.CODIGO_CLIENTE,
    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,
    CLI.TIPO_VAREJO,
    CLI.TIPO_BLOQUEIO,
    CLI.CADASTRAMENTO,
    CLI.OBS,
    CLI.SEXO,
    CLI.STATUS,
    CLI.DATA_PARA_TRANSFERENCIA
FROM
    CLIENTES_VAREJO CLI ( 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)
WHERE CLI.DATA_PARA_TRANSFERENCIA >= '{filtro_DATA_PARA_TRANSFERENCIA}'
ORDER BY CLI.DATA_PARA_TRANSFERENCIA ASC, CLI.CODIGO_CLIENTE ASC
OFFSET {offset} ROWS FETCH NEXT {limite} ROWS ONLY

Consulta dinâmica na captura por código (lista de códigos informada):

SELECT
    CLI.CODIGO_CLIENTE,
    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,
    CLI.TIPO_VAREJO,
    CLI.TIPO_BLOQUEIO,
    CLI.CADASTRAMENTO,
    CLI.OBS,
    CLI.SEXO,
    CLI.STATUS,
    CLI.DATA_PARA_TRANSFERENCIA
FROM
    CLIENTES_VAREJO CLI ( 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)
WHERE CLI.CODIGO_CLIENTE IN ('...')

Persistência: estado da captura mantido pelo mecanismo do serviço LojaCliente (offset, chave de posição, datas, filtro e situação); registros pendentes e resultados de processamento ficam na tabela da fila de integração com serviço LojaCliente.

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, monta o corpo JSON para o endpoint ILLI de pessoa/cliente, valida IBGE e código BACEN quando aplicável, 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

O array conteudo do registro na fila reproduz os campos retornados pela consulta de captura sobre CLIENTES_VAREJO (incluindo IBGE e PAIS_BC vindos dos joins). Na integração, esses campos alimentam um objeto distinto enviado ao ILLI; a tabela abaixo relaciona os principais campos do conteudo ao uso no payload enviado.

Campo no payload ILLI	Campo de origem
`codigo`	`CODIGO_CLIENTE`
`nome`	`CLIENTE_VAREJO`
`endereco.cep`	`CEP` (somente dígitos, completado à esquerda até 8 posições)
`endereco.logradouro`	`TIPO_LOGRADOURO` concatenado a `ENDERECO` (limitado a 250 caracteres)
`endereco.numero`	`NUMERO` (somente dígitos)
`endereco.complemento`	`COMPLEMENTO` (limitado a 250 caracteres)
`endereco.bairro`	`BAIRRO`
`endereco.cidade`	`CIDADE`
`endereco.uf`	`UF` (regra especial quando vazio ou com mais de 2 caracteres; estrangeiro usa `EX`)
`endereco.pais`	`PAIS`
`endereco.codigo_ibge`	`IBGE` ou valor fixo para estrangeiro quando aplicável
`endereco.codigo_bacen`	`PAIS_BC`
`tipo_cliente`	Constante `CLIENTE`
`filialCadastro`	`FILIAL`
`genero`	`SEXO`
`grupo`	`TIPO_VAREJO`
`complemento`	`OBS`
`contatos`	Montado a partir de `DDD`, `TELEFONE`, `DDD_CELULAR`, `CELULAR`, `EMAIL`
`situacao`	`STATUS` (ativo `1` ou inativo conforme regra)
`data_nascimento`	`ANIVERSARIO`
`data_cadastro`	`CADASTRAMENTO`
`data`	`DATA_PARA_TRANSFERENCIA`
`tipo`, `cnpj`, `ie`	Pessoa jurídica quando `CPF_CGC` com mais de 11 caracteres; `RG_IE` como inscrição
`tipo`, `cpf`, `identidade`	Pessoa física quando `CPF_CGC` com até 11 caracteres; `RG_IE` como identidade

Exemplo ilustrativo de trecho do corpo enviado ao ILLI (estrutura resumida):

{
  "codigo": "...",
  "nome": "...",
  "endereco": {
    "cep": "00000000",
    "referencia": "",
    "logradouro": "...",
    "numero": "...",
    "complemento": "...",
    "bairro": "...",
    "cidade": "...",
    "uf": "...",
    "pais": "...",
    "codigo_ibge": "...",
    "codigo_bacen": "..."
  },
  "tipo_cliente": ["CLIENTE"],
  "filialCadastro": "...",
  "contatos": [],
  "situacao": "1",
  "tipo": "FISICA",
  "cpf": "00000000000"
}

Tratamento de Dados

Sobre o registro atual $p lido do conteudo na fila:

DDD, TELEFONE, DDD_CELULAR, CELULAR: normalizados com remoção de não dígitos e montagem de entradas em contatos 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 (mensagens de erro específicas se ausentes).

Integração com o ILLI

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

Chamada: Requisição HTTP (encapsulada pela rotina de envio ao ILLI).
Recurso: 48df1d4a-2a73-4afc-be75-a8104533cda0/ilx_pessoa/setCliente
Método HTTP: conforme implementação padrão da rotina de integração ILLI (corpo JSON montado no array descrito em Estruturação de Dados).
Cabeçalhos: os definidos internamente pela rotina de integração ILLI (não fixados neste arquivo).
Corpo: objeto JSON com os campos mapeados a partir do conteudo do registro da fila, incluindo endereco, contatos, 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 de success e 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 JSON não reconhecido, o retorno estruturado pode incluir error e data com o trecho analisado.

Encaminhamento em cenário de erro

Não há, neste fluxo, encaminhamento automático para outro serviço ou biblioteca após falha na integração com o ILLI; o registro permanece com o estado de erro registrado na tabela da fila de integração.

Notificação

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

Destinatários e assunto são definidos no código; os campos exibidos incluem token, serviço, chave, datas de captura e processamento, mensagem de erro e nome do cliente e documento extraídos do conteúdo, com normalização de quebras de linha na mensagem de erro para exibição.

Endpoint (API)

Chamada: Requisição HTTP

Recurso: /rest/cliente

Método: POST

Cabeçalhos:
- tenantId: 01,01SD0001

O Endpoint (API) ~~exposto por esta biblioteca~~ processa o cadastro de cliente de varejo a partir do corpo da requisição: o fluxo de entrada é o array de parâmetros ~~recebido~~ no processamento principal do endpoint, validado contra as regras de tipo e obrigatoriedade descritas adiante, com persistência em CLIENTES_VAREJO e regras de inclusão, atualização, filial e documento.
~~Método HTTP:~~ POST ~~— padrão para envio de corpo com dados estruturados na execução da biblioteca no ISNAPP (rota da biblioteca conforme token no código).~~ Payload de entrada: objeto JSON (ou equivalente) cujas chaves correspondem aos campos da tabela abaixo; campos adicionais usados apenas no fluxo interno (ex.: CODIGO_CLIENTE, TIPO_VAREJO, OMS) podem acompanhar o mesmo corpo quando o chamador os informar.

Estruturação de Dados

Contrato do payload enviado ao endpoint (validação principal dos nomes de campo abaixo):

Campo	Tipo / tamanho	Obrigatório
`CLIENTE_VAREJO`	string, 40	sim
`FILIAL`	string, 25	sim
`ENDERECO`	string, 90	não
`UF`	string, 2	não
`PF_PJ`	bool, 1	sim
`RG_IE`	string, 19	não
`CPF_CGC`	string, 19	não
`CIDADE`	string, 35	não
`COMPLEMENTO`	string, 20	não
`CEP`	string, 9	não
`TELEFONE`	string, 10	não
`ANIVERSARIO`	datetime, 19	não
`DDD`	string, 4	não
`SEXO`	string, 1	não
`OBS`	string, 200	não
`EMAIL`	string, 100	não
`BAIRRO`	string, 35	não
`STATUS`	number, 1	não
`PAIS`	string, 40	não
`TIPO_LOGRADOURO`	string, 10	não
`NUMERO`	string, 10	não
`ESTRANGEIRO`	bool, 1	sim
`DDD_CELULAR`	string, 4	não
`CELULAR`	string, 10	não

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

Exemplo ilustrativo de corpo JSON (valores fictícios; incluir apenas chaves necessárias ao cenário):

{
  "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 em CLIENTES_VAREJO com o mapeamento de hidratação previsto no código para insert.
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).

Encaminhamento em cenário de erro

Não há encaminhamento para outro fluxo ou biblioteca após erro na persistência pelo endpoint; a operação encerra com exceção.

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 data válido, deve ler `CLIENTES_VAREJO` com joins de município e país, paginar pelo limite configurado e gravar cada registro na fila de integração com serviço `LojaCliente` e chave `CODIGO_CLIENTE`.	Registro pendente na fila com conteúdo alinhado à consulta e posição de captura atualizada.
Capturador	Captura por código	Para cada `CODIGO_CLIENTE` informado, deve consultar a mesma projeção e gravar na fila preservando token existente quando houver.	Registros reenfileirados com chave consistente e token reutilizado quando aplicável.
Fila de Processamento	Integração ILLI	Ao processar registro pendente, deve montar o JSON, chamar `ilx_pessoa/setCliente`, interpretar `success` e `message` e persistir situação 2 ou 4 com mensagem e tempo na tabela da fila de integração.	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.