Ir para o conteúdo principal

LojaVendedor

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

Visão geral do payload: a fila monta um objeto de vendedor com dados de identificação, documento (CPF/CNPJ), endereço, contatos, situação e datas. Quando existe CODIGO_CLIENTE, o subobjeto cliente também é enviado.

Campos do objeto raiz enviado ao ILLI
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 sim Lista de contatos em formato { tipo, contato }; pode ser vazia.
tipo string sim FISICA quando documento é CPF; JURIDICA quando documento é CNPJ.
cpf ou cnpj string sim Documento principal normalizado somente com dígitos e com padding (à esquerda) para 11/14 posições.
identidade ou ie string condicional identidade para pessoa física; ie (vazio) para pessoa jurídica.
tipo_vendedor array<string> sim Lista fixa: CLIENTE, FUNCIONARIO, VENDEDOR.
filialCadastro, filial string não Filiais de cadastro e operação do vendedor.
grupo, complemento, genero string não Dados complementares do vendedor.
situacao string sim 1 para ativo (sem DATA_DESATIVACAO) e 0 para inativo.
data_nascimento, data_cadastro, data_ativacao, data date/datetime/string não Datas de nascimento, cadastro, ativação e transferência para integração.
cliente object condicional Quando CODIGO_CLIENTE informado.

Estrutura do objeto endereco:

Campo Tipo Descrição
cep, referencia, logradouro, numero, complemento, bairro, cidade, uf, pais, codigo_ibge, codigo_bacen string Endereço normalizado; CEP e número com apenas dígitos, logradouro/complemento com limite de 250 caracteres, UF ajustada para EX em estrangeiro e validação de codigo_ibge/codigo_bacen quando aplicável.

Estrutura dos itens de contatos: cada item possui tipo (TELEFONE, CELULAR ou EMAIL) e contato (conteúdo normalizado).

Estrutura do objeto cliente (quando presente):

Campo Tipo Descrição
codigo, nome, tipo_cliente, grupo, situacao, data_cadastro, filialCadastro, genero string/array Dados do cadastro de cliente associados ao vendedor; tipo_cliente é enviado como lista com CLIENTE.

Exemplo de payload enviado para o endpoint (JSON):

{
  "key": "<OPCIONAL>",
  "id": false,
  "codigo": "<VENDEDOR>",
  "nome": "<NOME>",
  "tipo": "FISICA",
  "cpf": "00000000000",
  "identidade": "000000000",
  "tipo_vendedor": ["CLIENTE", "FUNCIONARIO", "VENDEDOR"],
  "filialCadastro": "<FILIAL_CADASTRO>",
  "filial": "<FILIAL>",
  "grupo": "<DESC_CARGO>",
  "complemento": "<OBS>",
  "endereco": {
    "cep": "00000000",
    "referencia": "",
    "logradouro": "<TIPO_LOGRADOURO ENDERECO>",
    "numero": "123",
    "complemento": "<COMPLEMENTO>",
    "bairro": "<BAIRRO>",
    "cidade": "<CIDADE>",
    "uf": "RJ",
    "pais": "BRASIL",
    "codigo_ibge": "3304557",
    "codigo_bacen": "1058"
  },
  "contatos": [
    { "tipo": "TELEFONE", "contato": "2122223333" },
    { "tipo": "CELULAR", "contato": "21999998888" },
    { "tipo": "EMAIL", "contato": "vendedor@dominio.com" }
  ],
  "situacao": "1",
  "data_nascimento": "<AAAA-MM-DD>",
  "data_cadastro": "<AAAA-MM-DD HH:MM:SS>",
  "data_ativacao": "<AAAA-MM-DD HH:MM:SS>",
  "data": "<AAAA-MM-DD HH:MM:SS>",
  "cliente": {
    "codigo": "<CODIGO_CLIENTE>",
    "nome": "<CLIENTE_VAREJO>",
    "tipo_cliente": ["CLIENTE"],
    "grupo": "<TIPO_VAREJO>",
    "situacao": "1",
    "data_cadastro": "<AAAA-MM-DD HH:MM:SS>",
    "filialCadastro": "<FILIAL_CADASTRO>",
    "genero": "<SEXO>"
  }
}
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/atualiza cadastro de vendedor
  • 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

wosk_loja_vendedor.drawio.xml.jpg


Critérios de Aceitação
Processo Subprocesso Descrição Situação esperada
Fila de Processamento ILLI Deve chamar atualiza cadastro de vendedor, interpretar sucesso ou erro com mensagem e persistir na tabela da fila de integração. Situação coerente com o retorno JSON.
Nenhum comentário
Voltar ao topo