LojaVendedor (STATUS: DOCUMENTADO)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → ILLI (Vendedor Loja)
Biblioteca	wosk_loja_vendedor
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 Vendedor (LINX → ILLI).

Descrição

Este serviço de vendedores da loja lê LOJA_VENDEDORES com enriquecimento de filial e, quando aplicável, dados do cadastro em CLIENTES_VAREJO pelo CPF, e envia ao ILLI o payload de pessoa/vendedor.
O fluxo valida IBGE e código BACEN para endereço nacional e monta contatos a partir de telefone, celular e e-mail.

Capturador

Descrição Conceitual

A captura automática consulta a projeção principal quando o serviço LojaVendedor está apto, com filtro em LV.DATA_PARA_TRANSFERENCIA e paginação conforme o limite configurado para o serviço LojaVendedor. A chave na fila é o código VENDEDOR.

A captura por código reprocessa o mesmo vendedor com a projeção completa.

Fonte

Origem: LOJA_VENDEDORES com LEFT JOIN em LOJAS_VAREJO, FILIAIS, CLIENTES_VAREJO (match por CPF), W_LCF_LX_MUNICIPIO e LCF_LX_PAIS.

Consulta principal (trecho inicial):

SELECT
    LV.VENDEDOR,
    LV.CODIGO_FILIAL,
    LV.NOME_VENDEDOR,
    LV.CPF,
    LV.DATA_ATIVACAO,
    LV.DATA_DESATIVACAO,
    LV.DATA_PARA_TRANSFERENCIA,
    FL.FILIAL,
    CLI.CODIGO_CLIENTE,
    CLI.CLIENTE_VAREJO,
    CLI.CIDADE,
    CLI.UF,
    CLI.CEP,
    LLM.COD_MUNICIPIO_IBGE AS IBGE,
    LLP.COD_PAIS_BC AS PAIS_BC
FROM
    LOJA_VENDEDORES LV (NOLOCK)
    LEFT JOIN LOJAS_VAREJO LVJ (NOLOCK) ON (LVJ.CODIGO_FILIAL = LV.CODIGO_FILIAL)
    LEFT JOIN FILIAIS FL (NOLOCK) ON (FL.FILIAL = LVJ.FILIAL)
    LEFT JOIN CLIENTES_VAREJO CLI (NOLOCK)
        ON (CLI.CPF_CGC = LV.CPF AND LEN(LV.CPF) > 0 AND LV.CPF <> '00000000000')
    LEFT JOIN W_LCF_LX_MUNICIPIO LLM (NOLOCK) ON (...)
    LEFT JOIN LCF_LX_PAIS LLP (NOLOCK) ON (CLI.PAIS = LLP.DESC_PAIS)

Operações com Dados

Leitura: conforme Fonte.

Consulta dinâmica (captura automática): filtro e paginação conforme limite do serviço LojaVendedor.

Persistência: grava na Fila de Processamento com serviço LojaVendedor e chave VENDEDOR.

Fila de Processamento

Descrição Conceitual

Monta objeto com identificação, endereço, contatos, tipo de pessoa (física/jurídica), documentos, situação ativo/inativo e sub-objeto cliente quando há CODIGO_CLIENTE. Valida IBGE para não estrangeiro e BACEN para país. Envia ao ILLI e persiste retorno na tabela da fila de integração.

Estruturação de Dados

Campos principais do payload ILLI (raiz)
Campo	Tipo	Obrigatório	Descrição
`key`	string	não	Chave de API quando exigida pela plataforma.
`codigo`	string	sim	`VENDEDOR`.
`nome`	string	sim	`NOME_VENDEDOR`.
`endereco`	object	sim	Montado a partir dos dados de cliente quando existirem.
`contatos`	array	condicional	Telefone, celular e e-mail.
`cliente`	object	condicional	Quando `CODIGO_CLIENTE` informado.

Exemplo de payload enviado para o endpoint (JSON) — resumo:

{
  "id": false,
  "codigo": "<VENDEDOR>",
  "nome": "<NOME>",
  "endereco": { "cep": "00000000", "logradouro": "..." },
  "contatos": [],
  "situacao": "1",
  "tipo": "FISICA",
  "cpf": "00000000000"
}

Tratamento de Dados

Contatos: montados com DDD e número somente dígitos; e-mail quando existir.
Endereço: logradouro com tipo; CEP com oito dígitos; IBGE e BACEN obrigatórios nas regras de validação quando aplicáveis.
Documento: CPF ou CNPJ conforme tamanho e presença de caracteres no campo de origem.

Integração com o ILLI

Chamada: Requisição HTTP
Recurso: /bibliotecas/48df1d4a-2a73-4afc-be75-a8104533cda0/ilx_pessoa/setVendedor
Método HTTP: POST
Corpo: objeto montado no processamento da fila.

Tratamento de retorno

Padrão success/message; situação sucesso ou 4 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 LojaVendedor 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
Fila de Processamento	ILLI	Deve chamar `setVendedor`, interpretar sucesso ou erro com mensagem e persistir na tabela da fila de integração.	Situação coerente com o retorno JSON.