Ir para o conteúdo principal

CLIENTE (LojaCliente)

Documentação Técnica

Nome do cliente TO-DO
Nome do projeto TO-DO
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 ?

Sumário

Histórico de Versões

Data Versão Modificado por Descrição da Mudança
? 1.0 Maykon Estrutura inicial da especificação.

Descrição Geral dos Processos

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum

Monitor

Processo: 
simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum

Queue

1. DESCRIÇÃO DO FLUXO

O componente Queue é responsável pelo processamento assíncrono das mensagens de integração relacionadas ao contexto "LojaCliente". O método run() é acionado com um token identificador da mensagem a ser processada.

Inicialmente, o sistema recupera um item da fila utilizando o token informado. Caso exista conteúdo pendente, o registro é imediatamente atualizado para o status "Enviando", garantindo rastreabilidade e evitando reprocessamentos simultâneos.

Em seguida, o sistema inicia o processamento do payload (conteudo), realizando:

- Montagem dos dados de contato (telefone, celular, e-mail)
- Normalização dos números telefônicos
- Composição do logradouro completo
- Validação de códigos obrigatórios (IBGE / BACEN)
- Construção da estrutura final de integração
- Identificação do tipo de pessoa (Física / Jurídica)

Após a montagem do objeto final, é realizada a chamada ao endpoint externo de integração (setIlli).

Dependendo do retorno:

- Sucesso → registro atualizado com situacao = 2
- Erro → registro atualizado com situacao = 4

Ao final, o tempo de execução é calculado e persistido junto ao resultado do processamento.

2. DADOS NECESSÁRIOS PARA O ENDPOINT

O processamento da fila pressupõe que o conteúdo já tenha sido previamente estruturado. Os seguintes campos são esperados:

Campos relevantes:

- CODIGO_CLIENTE
- CLIENTE_VAREJO
- CPF_CGC
- RG_IE
- ENDERECO
- TIPO_LOGRADOURO
- NUMERO
- COMPLEMENTO
- BAIRRO
- CIDADE
- UF
- CEP
- PAIS
- PAIS_BC
- IBGE
- TELEFONE
- DDD
- CELULAR
- DDD_CELULAR
- EMAIL
- SEXO
- STATUS
- ANIVERSARIO
- CADASTRAMENTO
- DATA_PARA_TRANSFERENCIA
- FILIAL
- TIPO_VAREJO
- ESTRANGEIRO

Observação:
Campos como IBGE e PAIS_BC devem estar previamente resolvidos. A ausência desses dados pode interromper o processamento.

3. REESTRUTURAÇÃO DOS DADOS

3.1 Atualização de status inicial da fila
Momento: Imediatamente após recuperar o item

Regra:
- situacao ← 1 (Enviando)

3.2 Montagem dos contatos
Momento: Início do processamento do payload

Transformações:

- Remove caracteres não numéricos de:
  • DDD
  • TELEFONE
  • DDD_CELULAR
  • CELULAR

- Concatenação:
  • TELEFONE → DDD + TELEFONE
  • CELULAR → DDD_CELULAR + CELULAR

- Inclusão condicional:
  • Apenas se houver valor informado

3.3 Composição do logradouro
Momento: Antes da montagem do endereço

Regra:
- logradouro ← TIPO_LOGRADOURO + ENDERECO

3.4 Normalização do CEP
Momento: Montagem da estrutura final

Regra:
- CEP → somente números
- CEP → preenchido à esquerda até 8 dígitos

3.5 Normalização de campos numéricos
Momento: Montagem do endereço

Transformações:

- NUMERO → somente números
- RG_IE → somente números

3.6 Validação de código IBGE
Momento: Pré-integração

Regra:
- Obrigatório para clientes nacionais
- Se ausente → exceção

3.7 Validação de código BACEN
Momento: Pré-integração

Regra:
- PAIS_BC obrigatório
- Se ausente → exceção

3.8 Normalização da UF
Momento: Montagem do endereço

Regra:
- Se UF inválida ou vazia:
    • Estrangeiro → "EX"
    • Nacional → vazio

3.9 Definição do código IBGE
Momento: Montagem do endereço

Regra:
- Nacional → usa IBGE informado
- Estrangeiro → "9999999"

3.10 Conversão do STATUS
Momento: Montagem do objeto final

Regra:
- STATUS ≠ '1' → situacao ← '0'
- STATUS = '1' → situacao ← '1'

3.11 Identificação do tipo de pessoa
Momento: Montagem final

Regra:

- CPF_CGC > 11 dígitos →
    tipo ← JURIDICA
    cnpj ← normalizado (14 dígitos)
    ie ← RG_IE normalizado

- CPF_CGC ≤ 11 dígitos →
    tipo ← FISICA
    cpf ← normalizado (11 dígitos)
    identidade ← RG_IE normalizado

3.12 Controle de truncamento
Momento: Montagem do endereço

Regra:
- logradouro → máx. 250 caracteres
- COMPLEMENTO → máx. 250 caracteres


4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)

Tabela de controle da fila:
→ wosk_queue

Operações realizadas:

- Atualização ao iniciar processamento
  Método: set(..., 'Enviando', situacao = 1)

- Atualização ao finalizar processamento
  Método: set(..., retorno, mensagem, tempo, situacao)

Situações possíveis:

- 2 → Processado com sucesso
- 4 → Erro no processamento

Dados registrados:

- Conteúdo original
- Retorno do endpoint externo
- Mensagem de erro/sucesso
- Dump da requisição (CURL)
- Tempo de execução

5. RESULTADO DO PROCESSAMENTO

Sucesso:

- situacao = 2
- Mensagem retornada pelo serviço externo

Erro:

- situacao = 4
- Mensagem detalhada do erro
- Retorno estruturado indicando falha

6. ROTINAS AUXILIARES

prepare():
- Prepara o contexto da fila "LojaCliente"

notificar():
- Consulta registros com erro (situacao = 4)
- Envia notificação por e-mail

get():
- Recupera itens pendentes ou específicos

set():
- Persiste atualizações da fila

getConteudo():
- Extrai conteúdo normalizado do payload

WebService

1. DESCRIÇÃO DO FLUXO

O WebService recebe uma requisição contendo os dados cadastrais de um cliente varejo. Ao ser acionado, o método run() executa inicialmente o processo de validação dos parâmetros recebidos. Caso exista qualquer inconsistência (campo obrigatório ausente, tipo inválido ou tamanho excedido), a execução é interrompida e uma exceção é retornada.

Após validação bem-sucedida, os dados são encaminhados ao método setClientesVarejo(), onde o processamento principal ocorre dentro de uma transação de banco de dados. Nesse estágio, o sistema:

- Define automaticamente as datas de CADASTRAMENTO e DATA_PARA_TRANSFERENCIA.
- Ajusta o TIPO_VAREJO caso o valor informado não exista na tabela de tipos válidos.
- Determina o status de ESTRANGEIRO com base na UF.
- Remove o campo SEXO se estiver vazio.
- Normaliza o CEP quando necessário.
- Determina o CODIGO_CLIENTE conforme regras de prioridade.

Em seguida, o sistema verifica se já existe um cliente cadastrado:

- Se NÃO existir: realiza INSERT na tabela CLIENTES_VAREJO.
- Se EXISTIR: realiza UPDATE conforme regras de atualização.

Ao final, a transação é confirmada (commit). Em caso de erro, ocorre rollback.

O retorno do WebService inclui o CODIGO_CLIENTE definido e mensagens de status ("OK" / "Registrado com sucesso.").

2. DADOS PARA O ENDPOINT

CAMPO TIPO TAMANHO  CONTEÚDO OBRIGATÓRIO
CLIENTE_VAREJO
 STRING 40
Nome do cliente


 sim
FILIAL
 STRING

25
Nome ou código da filial
 sim
PF_PJ
 INT 1
Pessoa Física / 
Pessoa Jurídica
 sim
ESTRANGEIRO
 INT 1
Estrangeiro / 
Nacional
 sim
ENDERECO
 STRING
90
 Nome da via/logradouro sem o tipo. não
UF
 STRING
2
 Sigla da unidade federativa ou indicador de estrangeiro. não
RG_IE
 STRING
19
 Documento de identificação (RG ou Inscrição Estadual). não
CPF_CGC
 STRING
19

 Documento fiscal (CPF ou CNPJ). não
CIDADE
 STRING
35
 Nome da cidade do cliente. não
COMPLEMENTO
 STRING
20
 Informação adicional do endereço. não
CEP
 STRING
9
 Código de endereçamento postal. não
TELEFONE
 STRING
10
 Número do telefone sem DDD. não
ANIVERSARIO
 DATETIME DATETIME Data de nascimento ou referência cadastral. não
DDD
 STRING
4
 Código de área do telefone fixo. não
SEXO
 STRING
1
 Identificação de gênero. não
OBS
 STRING
200
 Observações gerais do cadastro. não
EMAIL
 STRING
100
 Endereço eletrônico do cliente. não
BAIRRO
 STRING
35
 Nome do bairro do endereço. não
STATUS
 INT
1
 Situação do cadastro do cliente. não
PAIS
 STRING
40
 Nome do país do cliente. não
TIPO_LOGRADOURO
 STRING
10
 Tipo do logradouro. não
NUMERO
 STRING
10
 Número do imóvel. não
DDD_CELULAR
 STRING
4
 Código de área do telefone celular. não
CELULAR
 STRING
10
 Número do celular sem DDD. não

Observação importante:
Mesmo não sendo informado diretamente, o campo CODIGO_CLIENTE torna-se obrigatório após a fase de reestruturação.

3. REESTRUTURAÇÃO DOS DADOS

3.1 Datas automáticas
Momento: Início do processamento em setClientesVarejo()

- CADASTRAMENTO = Data/hora atual
- DATA_PARA_TRANSFERENCIA = Data/hora atual

3.2 Validação e ajuste do TIPO_VAREJO
Momento: Antes de persistir os dados

Regra:
- Se TIPO_VAREJO não existir em CLIENTE_VAR_TIPOS:
  TIPO_VAREJO = "CLIENTE VAREJO"

3.3 Determinação de ESTRANGEIRO
Momento: Antes da validação final

Regra:
- Se ESTRANGEIRO vazio:
    ESTRANGEIRO = '0'
- Se UF = 'EX':
    ESTRANGEIRO = '1'

3.4 Remoção do campo SEXO
Momento: Pré-validação

Regra:
- Se SEXO vazio:
    Campo removido do payload

3.5 Normalização do CEP
Momento: Pré-validação

Regra:
- Se CEP informado e valor numérico = 0:
    CEP = 'NULL()'

3.6 Definição do CODIGO_CLIENTE
Momento: Pré-validação obrigatória

Regra de prioridade:

1) CODIGO_CLIENTE informado: utilizado após trim()
2) Se vazio:
      CODIGO_CLIENTE = CPF_CGC
3) Se ESTRANGEIRO = 1:
      CODIGO_CLIENTE = RG_IE

3.7 Validação obrigatória do CODIGO_CLIENTE
Momento: Após reestruturação

Regra:
- Deve existir
- Tipo string
- Máx. 14 caracteres

3.8 Filtro de busca (identificação do registro)
Momento: Antes de INSERT/UPDATE

Regra:
- Nacional:
    filtro = CPF_CGC
- Estrangeiro:
    filtro = CODIGO_CLIENTE

3.9 Verificação de existência e controle de duplicidade

Momento: Após definição do filtro e antes e durante o processo que decide entre INSERT ou UPDATE

Durante o processamento em setClientesVarejo(), após a definição e normalização dos campos obrigatórios, o sistema executa uma consulta na tabela CLIENTES_VAREJO com o objetivo de identificar se o cliente já possui cadastro.

A busca é realizada utilizando um filtro dinâmico:

- Cliente nacional: filtro por CPF_CGC
- Cliente estrangeiro: filtro por CODIGO_CLIENTE

O registro mais recente é recuperado com ordenação decrescente por CADASTRAMENTO e limite de 1 resultado.

Caso NÃO seja encontrado um CODIGO_CLIENTE válido:

1) Validação de duplicidade (somente para clientes nacionais)

   O sistema realiza uma segunda consulta verificando se já existe algum registro com o mesmo CODIGO_CLIENTE informado.  
   Essa validação evita inconsistências onde um CODIGO_CLIENTE esteja associado a um CPF_CGC diferente.

   Se encontrado: A execução é interrompida com exceção indicando conflito de identidade.

2) Normalização do campo FILIAL

   Se o valor de FILIAL for numérico: O sistema converte o código para o nome correspondente na tabela FILIAIS.

3) Complemento automático do campo OBS

   O sistema prefixa o texto: "Cadastrado Pelo PDV ILLIMITAR."

4) Persistência dos dadosÉ executado um INSERT na tabela CLIENTES_VAREJO utilizando sqlPrepareInsert().

Caso SEJA encontrado um registro existente: O fluxo segue para a lógica de atualização (UPDATE), preservando dados críticos conforme regras definidas.

3.10 Conversão de FILIAL numérica
Momento: Apenas em INSERT

Regra:
- Se FILIAL numérica: FILIAL = Nome correspondente na tabela FILIAIS

3.11 Complemento automático de OBS
Momento: INSERT

Regra:
- OBS = "Cadastrado Pelo PDV ILLIMITAR. {OBS}"

4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)

Tabela principal: CLIENTES_VAREJO

Operações possíveis:

- INSERT
  Quando: Cliente não localizado
  Método: sqlPrepareInsert()

- UPDATE
  Quando: Cliente já existente
  Método: sqlPrepareUpdate()

Campos controlados automaticamente:
- CODIGO_CLIENTE
- CADASTRAMENTO
- DATA_PARA_TRANSFERENCIA
- FILIAL (em update preserva valor original)
- TIPO_VAREJO (em update preserva valor original)

5. RESULTADO DO PROCESSAMENTO

Retorno padrão (sucesso):

- Mensagem: OK
- Mensagem Detalhada: Registrado com sucesso.
- CODIGO_CLIENTE
- CADASTRAMENTO
- DATA_PARA_TRANSFERENCIA

Em caso de erro:

- Transação revertida (rollback)
- Exceção com prefixo:
  "CLIENTES_VAREJO: {detalhes do erro}"

Método: POST para Registro Recebido
Chave Primária: FILIAL, ID
Observação: O campo ID será único por FILIAL.
CAMPO TIPO TAMANHO  CONTEÚDO OBRIGATÓRIO
key C 36 Chave da API Key para autenticação

 sim

Exemplos de Request: 

{
  "UF": "MG",
  "CEP": "06845330",
  "DDD": "21",
  "OBS": "",
  "OMS": "0",
  "key": "609d9139-3439-45ae-ad00-a3e5a9f835f1",
  "PAIS": "BRASIL",
  "SEXO": "M",
  "EMAIL": "T.TESTE@GMAIL.COM",
  "PF_PJ": "1",
  "RG_IE": "94987713999",
  "BAIRRO": "PADRE EUSTÁQUIO",
  "CIDADE": "BELO HORIZONTE",
  "FILIAL": "ESTOQUE CENTRAL",
  "NUMERO": "370",
  "STATUS": "1",
  "CELULAR": "",
  "CPF_CGC": "99999999999",
  "eventId": "d061d60d-d2bc-4181-a224-881ebf4ded07",
  "ENDERECO": "CESÁRIO ALVIM",
  "TELEFONE": "999999999",
  "ANIVERSARIO": "1993-07-04 00:00:00",
  "COMPLEMENTO": "",
  "DDD_CELULAR": "",
  "ESTRANGEIRO": "0",
  "TIPO_VAREJO": "VENDEDOR (C)",
  "CLIENTE_VAREJO": "LOREM IPSUM",
  "CODIGO_CLIENTE": "94987713999",
  "TIPO_LOGRADOURO": "RUA"
}

Exemplos de Response: 

{
  "UF": "MG",
  "CEP": "06845330",
  "DDD": "21",
  "OBS": "",
  "OMS": "0",
  "key": "609d9139-3439-45ae-ad00-a3e5a9f835f1",
  "PAIS": "BRASIL",
  "SEXO": "M",
  "EMAIL": "T.TESTE@GMAIL.COM",
  "PF_PJ": "1",
  "RG_IE": "94987713999",
  "BAIRRO": "PADRE EUSTÁQUIO",
  "CIDADE": "BELO HORIZONTE",
  "FILIAL": "ESTOQUE CENTRAL",
  "NUMERO": "999",
  "STATUS": "1",
  "CELULAR": "",
  "CPF_CGC": "99999999999",
  "eventId": "d061d60d-d2bc-4181-a224-881ebf4ded07",
  "ENDERECO": "CESÁRIO ALVIM",
  "Mensagem": "OK",
  "TELEFONE": "999999999",
  "ANIVERSARIO": "1993-07-04 00:00:00",
  "COMPLEMENTO": "",
  "DDD_CELULAR": "",
  "ESTRANGEIRO": "0",
  "TIPO_VAREJO": "VENDEDOR (C)",
  "CADASTRAMENTO": "2025-09-25 15:58:07.000",
  "CLIENTE_VAREJO": "LOREM IPSUM",
  "CODIGO_CLIENTE": "94987713999",
  "TIPO_LOGRADOURO": "RUA",
  "Mensagem Detalhada": "Registrado com sucesso.",
  "DATA_PARA_TRANSFERENCIA": "2026-02-03 11:41:39"
}

Fluxo do Processo

wosk_loja_cliente.jpg

Critérios de Aceitação

Processo Subprocesso Descrição Situação esperada






Voltar ao topo