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

• 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
?	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

Processo:
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

WebService

Processo:1.
DESCRIÇÃO DO FLUXOis

simply

O dummyWebService textrecebe ofuma therequisição printingcontendo andos typesettingdados industry.cadastrais Loremde Ipsumum hascliente beenvarejo. theAo industry'sser standardacionado, dummyo textmétodo everrun() sinceexecuta theinicialmente 1500s,o whenprocesso ande unknownvalidação printerdos tookparâmetros recebidos. Caso exista qualquer inconsistência (campo obrigatório ausente, tipo inválido ou tamanho excedido), a galleyexecução ofé typeinterrompida ande scrambleduma itexceção toé makeretornada.

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 typetransação specimené book.confirmada It(commit). hasEm survivedcaso notde onlyerro, fiveocorre centuries,rollback.

but

O alsoretorno thedo leapWebService intoinclui electronico typesetting,CODIGO_CLIENTE remainingdefinido essentiallye unchanged.mensagens Itde wasstatus popularised("OK" in/ the"Registrado 1960scom withsucesso.").

the

2. releaseDADOS ofNECESSÁRIOS LetrasetPARA sheetsO containingENDPOINT

Lorem

Campos Ipsumobrigatórios:

passages,

- andCLIENTE_VAREJO more(string, recentlymáx. with40)
 desktop publishingDescrição: softwareNome likedo Alduscliente.

PageMaker

- includingFILIAL versions(string, ofmáx. Lorem25)
 Ipsum Descrição: Nome ou código da filial.

- PF_PJ (bool / inteiro lógico)
  Descrição:
    1 = Pessoa Física
    2 = Pessoa Jurídica

- ESTRANGEIRO (bool / inteiro lógico)
  Descrição:
    1 = Estrangeiro
    0 = Nacional

Campos opcionais:

• ENDERECO (string, máx. 90)
  - UF (string, 2)
  - RG_IE (string, máx. 19)
  - CPF_CGC (string, máx. 19)
  - CIDADE (string, máx. 35)
  - COMPLEMENTO (string, máx. 20)
  - CEP (string, máx. 9)
  - TELEFONE (string, máx. 10)
  - ANIVERSARIO (datetime)
  - DDD (string, máx. 4)
  - SEXO (string, 1)
  - OBS (string, máx. 200)
  - EMAIL (string, máx. 100)
  - BAIRRO (string, máx. 35)
  - STATUS (number, 1)
  - PAIS (string, máx. 40)
  - TIPO_LOGRADOURO (string, máx. 10)
  - NUMERO (string, máx. 10)
  - DDD_CELULAR (string, máx. 4)
  - CELULAR (string, máx. 10)

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

CAMPO	TIPO	TAMANHO	CONTEÚDO	OBRIGATÓRIO
CLIENTE_VAREJO	C	36	Chave da API Key para autenticação	sim

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}"

CAMPO	TIPO	TAMANHO	CONTEÚDO	OBRIGATÓRIO
key	C	36	Chave da API Key para autenticação	sim

Exemplos de Request: 

{
    "key": "34a20688-1bb6-4fcd-9592-d58ca9876de5",
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0206",
    "ID": "00000007188082",
    "DATA_RETORNO": "2024-10-29 00:37:05",
    "SITUACAO": "1",
    "MENSAGEM": "GravaBatch Executado com Sucesso",
    "DETALHE": {
        "ZB_ID": "000000000004156",
        "LQ_DOC": "000051206",
        "LQ_PDV": "003",
        "ERGRVBT": "",
        "LQ_HORA": "20:41:19",
        "LQ_LOJA": "68",
        "LQ_VEND": "000001",
        "SITUAGB": "OK",
        "LQ_FORMA": "R$",
        "LQ_FRETE": 0,
        "LQ_SERIE": "65",
        "LQ_SITUA": "RX",
        "Mensagem": "OK",
        "LQ_CARTAO": 752.14,
        "LQ_CONDPG": "",
        "LQ_EMISNF": "27/07/2025",
        "LQ_FILIAL": "01LJ0299",
        "LQ_FORMPG": "CC",
        "LQ_NOMCLI": "XXXXXX",
        "LQ_OUTROS": 139.65,
        "LQ_SERSAT": "",
        "LQ_TPFRET": "S",
        "LQ_VALICM": 178.35,
        "LQ_VLRLIQ": 891.79,
        "LQ_VLRTOT": 891.79,
        "LQ_XCANAL": "VAREJO",
        "ZB_DATRET": "29/07/25",
        "ZB_FILIAL": "01LJ0299",
        "ZB_HORRET": "09:18:00",
        "LQ_CLIENTE": "XXXXX",
        "LQ_DINHEIR": 0,
        "LQ_EMISSAO": "27/07/2025",
        "LQ_ESPECIE": "NFCE",
        "LQ_KEYNFCE": "XXXXX",
        "LQ_NUMCFIS": "000051206",
        "LQ_OPERADO": "C24",
        "LQ_PARCELA": 0,
        "LQ_TIPOCLI": "F",
        "LQ_VALBRUT": 891.79,
        "LQ_VALMERC": 1044,
        "LQ_VENDTEF": "S",
        "LQ_VLRDEBI": 0,
        "LQ_XNATOPE": "100.80",
        "Mensagem Detalhada": "GravaBatch Executado com Sucesso"
    }
}

{
    "key": "34a20688-1bb6-4fcd-9592-d58ca9876de5",
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "MENSAGEM": "D2_TES: Tipo Operacao '', do Item '0001', Invalido."
}

Exemplos de Response: 

{
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "Mensagem Detalhada": "Registrado com sucesso.",
    "Mensagem": "OK"
}

{
    "success":false,
    "message":"Sess\u00e3o Expirou",
    "data":false,
    "errors":{"reason":"Sess\u00e3o Expirou"}
}

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada