CLIENTE (LojaCliente) (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	INTEGRAÇÃO LINX → ILLI
Biblioteca	wosk_loja_cliente
Token da Biblioteca	1be199d8-98e8-4de7-a92c-e59c2f08edd6
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/1be199d8-98e8-4de7-a92c-e59c2f08edd6/wosk_loja_cliente
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/1be199d8-98e8-4de7-a92c-e59c2f08edd6/wosk_loja_cliente
Data	24/02/2026

Sumário

• Documentação Técnica
  
• Sumário
• Histórico de Versões
• Descrição Geral dos Processos
  • Monitor
  • Queue
  • WebService
• Fluxo do Processo
• Critérios de Aceitação

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
24/02/2026	1.0	Maykon/Gustavo	Criação da documentação do processo de integração de cadastro de cliente.

Descrição Geral dos Processos

Este processo centraliza o cadastro e a atualização de clientes, garantindo que as informações recebidas sejam validadas e armazenadas de forma consistente.

Quando um cliente é incluído ou alterado, os registros ficam disponíveis para captura periódica (cron), que organiza a fila de processamento para integração assíncrona.

Por fim, a fila monta os dados no formato esperado pelo destino, realiza validações essenciais e registra o resultado, permitindo acompanhamento e tratamento de falhas.

Monitor

Descrição Conceitual

Descrição do fluxo

Entrada de dados (query)

A entrada é realizada via query sobre a base de clientes e tabelas auxiliares. O filtro por data é aplicado na coluna DATA_PARA_TRANSFERENCIA, caracterizando um filtro cronológico (Conceito Cronológico).

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 >= '<DATA_REFERENCIA>'
ORDER BY
    CLI.DATA_PARA_TRANSFERENCIA ASC
OFFSET <OFFSET> ROWS
FETCH NEXT <LIMITE> ROWS ONLY;

Observação: o WHERE é montado dinamicamente com base na data de referência persistida pelo Monitor.

Reestruturação e alteração de dados

Operações com dados (Banco de Dados)

Resultado do processamento

Ao final do ciclo, os registros elegíveis ficam organizados para processamento assíncrono, e a posição do Monitor é salva para continuidade no próximo acionamento.

Queue

Descrição Conceitual

Descrição do fluxo

Reestruturação e alteração de dados

Operações com dados (Banco de Dados)

Resultado do processamento

WebService

Descrição Conceitual

Descrição do fluxo

Reestruturação e alteração de dados

Operações com dados (Banco de Dados)

Resultado do processamento

Quando não há erros de validação ou de persistência, o endpoint retorna confirmação de registro do cliente e disponibiliza a data de transferência para rastreabilidade.

CAMPO	TIPO	TAMANHO	CONTEÚDO	OBRIGATÓRIO
key	C	36	Chave da API Key para autenticação	sim
CLIENTE_VAREJO	C	40	Nome do cliente	sim
FILIAL	C	25	Nome ou código da filial	sim
CODIGO_CLIENTE	C	14	Identificação do cliente (derivada do documento quando não informada)	sim
PF_PJ	L	1	Indica se o cadastro é de pessoa física ou jurídica	sim
ESTRANGEIRO	L	1	Indica se o cadastro é de estrangeiro	sim

Exemplos de Request: 

{
  "key": "<API_KEY>",
  "CLIENTE_VAREJO": "CLIENTE TESTE",
  "FILIAL": "ESTOQUE CENTRAL",
  "PF_PJ": true,
  "ESTRANGEIRO": false,
  "CPF_CGC": "99999999999",
  "RG_IE": "94987713999",
  "EMAIL": "t.teste@gmail.com",
  "DDD": "21",
  "TELEFONE": "999999999",
  "DDD_CELULAR": "21",
  "CELULAR": "999999999",
  "UF": "RJ",
  "CIDADE": "RIO DE JANEIRO",
  "BAIRRO": "CENTRO",
  "CEP": "20000000",
  "TIPO_LOGRADOURO": "RUA",
  "ENDERECO": "EXEMPLO",
  "NUMERO": "100",
  "COMPLEMENTO": "SALA 10",
  "PAIS": "BRASIL",
  "ANIVERSARIO": "1993-07-04 00:00:00",
  "OBS": "Cadastro via integração"
}

Exemplos de Response: 

{
  "Mensagem": "OK",
  "Mensagem Detalhada": "Registrado com sucesso.",
  "CODIGO_CLIENTE": "99999999999",
  "CADASTRAMENTO": "2026-02-24 12:00:00",
  "DATA_PARA_TRANSFERENCIA": "2026-02-24 12:00:00"
}

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
WebService	Validação e persistência	Ao receber requisição com os campos obrigatórios, deve validar e gravar o cliente em CLIENTES_VAREJO (criando ou atualizando conforme existência).	Registro persistido e retorno de confirmação ao chamador.
Monitor	Captura cronológica	Quando acionado por cron, deve buscar clientes a partir de DATA_PARA_TRANSFERENCIA, paginando resultados e mantendo a continuidade pela data/offset.	Itens selecionados por data e organizados para processamento assíncrono; posição salva em wosk_monitor.
Queue	Integração assíncrona	Deve converter o item para o formato do destino (contatos, endereço e documentos), realizar validações essenciais e registrar o resultado na fila.	Fila atualizada com sucesso ou erro, mantendo mensagem e retorno para rastreabilidade.