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

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:

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