ProtheusCliente

DOCUMENTAÇÃO – WEBSERVICE / MONITOR PROTHEUS CLIENTE

1. DESCRIÇÃO GERAL DO FLUXO FIM-A-FIM

A arquitetura de integração é composta por três camadas sequenciais e independentes:

1. WebService (acionado por Endpoint)

2. Monitor (acionado por execução via cron)

3. Queue (acionada por execução via cron)

O fluxo ocorre da seguinte forma:

ETAPA 1 – WEBSERVICE (Entrada síncrona)
O WebService expõe um endpoint responsável por receber dados de clientes destinados ao Protheus. Ao receber a requisição:

• Valida estrutura obrigatória.
• Aplica regras de negócio.
• Normaliza e padroniza dados.
• Persiste os dados na base interna.
• Garante integridade, rastreabilidade e idempotência.

Os dados são persistidos na origem lógica representada pela view:

WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES

Essa view é a base consumida posteriormente pelo Monitor.

ETAPA 2 – MONITOR (Captura incremental)
O Monitor é executado via cron e realiza:

• Leitura incremental baseada em DATA_PARA_TRANSFERENCIA.
• Controle de offset e chave de posição.
• Paginação via OFFSET / FETCH.
• Enfileiramento para processamento assíncrono.

Ele garante:
• Continuidade em caso de parada.
• Evita duplicidade.
• Controle transacional de posição.

ETAPA 3 – QUEUE (Processamento assíncrono)
A Queue processa os registros enfileirados:

• Realiza validações finais.
• Aplica transformações adicionais.
• Monta payload final.
• Integra com sistema externo (Protheus).
• Atualiza status, auditoria e histórico.

A fila garante:
• Escalabilidade.
• Reprocessamento controlado.
• Tolerância a falhas.
• Rastreabilidade completa.

2. DADOS NECESSÁRIOS PARA O ENDPOINT (WEBSERVICE)

Parâmetros obrigatórios:

A1_LOJA
Identificador da filial.

A1_COD
Código do cliente.

CGC_CPF
Documento fiscal (CPF/CNPJ).

NOME
Nome/Razão Social.

PESSOA
Tipo de pessoa.

STATUS
Situação cadastral.

DATA_PARA_TRANSFERENCIA
Data base para captura incremental.

Demais campos tratados:

NOME_REDUZ
ENDERECO
BAIRRO
COMPLEMENTO
TIPO
UF
COD_MUNICIPIO_IBGE
CEP
DDI
DDD
TELEFONE
CONTATO
A1_PFISICA
A1_INSCR
INSC_MUNICIPAL
DATA_NASC
EMAIL
COD_PAIS_SISCOMEX
COD_PAIS_BC
A1_CONTA
A1_CONTRIB
A1_TPESSOA
A1_SUFRAMA
A1_CALCSUF
A1_CODMUN

3. REESTRUTURAÇÃO E VALIDAÇÃO DOS DADOS – WEBSERVICE

3.1 Pré-validação estrutural
Momento: Antes de qualquer persistência

Regras:
• Campos obrigatórios não podem ser nulos.
• DATA_PARA_TRANSFERENCIA deve ser data válida.
• CPF/CNPJ deve possuir formato válido.
• A1_LOJA + A1_COD + CGC_CPF formam chave lógica única.

3.2 Normalização
Momento: Pré-insert / Pré-update

Transformações aplicadas:
• trim() em todos os campos texto.
• Datas convertidas para formato Y-m-d H:i:s.
• Campos vazios convertidos para string vazia.
• Documentos removem caracteres especiais.
• UF convertida para maiúsculo.
• EMAIL convertido para minúsculo.

3.3 Persistência
Momento: Insert ou Update

Tabela base:
WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES (via camada interna)

Regra:
• Se já existir registro com mesma chave lógica → UPDATE.
• Caso contrário → INSERT.

Controle:
• Atualização obrigatória de DATA_PARA_TRANSFERENCIA.
• Registro de data de modificação.
• Registro de origem e token transacional.

Resultado:
Registro disponível para captura pelo Monitor.

4. MONITOR – PROCESSO DE CAPTURA INCREMENTAL

Classe responsável: Monitor (ProtheusCliente)

4.1 Recuperação do estado
Momento: Início do run()

Dados recuperados via _get("ProtheusCliente"):

offset
chave_posicao
data_posicao
filtro
situacao
data_iniciado
token

Situações:
0 → Parado
1 → Executando
2 → Concluído
4 → Problema

Regra:
Se situacao = 2 → redefinir para 0.

4.2 Reset de execução
Momento: Quando situacao ≠ 1

dataPosicao ← data atual
dataIniciado ← data atual
offset ← 0
chavePosicao ← ''

4.3 Normalização dos filtros
Momento: Antes da query

A1_LOJA ← '' se vazio
A1_COD ← '' se vazio
CGC_CPF ← '' se vazio
DATA_PARA_TRANSFERENCIA ←
• valor informado → convertido
• vazio → '2023-05-01 00:00:00'

4.4 Atualização para EXECUTANDO
Momento: Antes da consulta

situacao ← 1

4.5 Consulta paginada
Momento: Execução da query

Fonte:
WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES

Regra:
WHERE DATA_PARA_TRANSFERENCIA >= filtro
ORDER BY DATA_PARA_TRANSFERENCIA ASC
OFFSET offset
FETCH NEXT limiteConfigurado

4.6 Sanitização
Momento: Ao ler cada registro

Transformação:
• trim() recursivo em todos os campos.

4.7 Construção da chave única
Momento: Dentro do loop

key ← A1_LOJA + '-' + A1_COD + '-' + CGC_CPF

4.8 Enfileiramento
Momento: Dentro do loop

Operação:
Queue::set()

Tabela de persistência:
wosk_queue

Campos gravados:

chave
conteudo (payload completo do registro)
status = 'Aguardando Integração'
situacao = 0
data_referencia = DATA_PARA_TRANSFERENCIA
token (se houver)

4.9 Atualização incremental da posição
Momento: Após inserir na fila

offset ← offset + 1
chavePosicao ← key
dataPosicao ← DATA_PARA_TRANSFERENCIA

Persistido via:
_set("ProtheusCliente")

4.10 Finalização
Momento: Fim do loop

situacao ← 2 (Concluído)

4.11 Tratamento de erro
Momento: catch(Exception)

situacao ← 4
filtro['ERRORS'][] ←
DATE
MESSAGE

Persistência do erro realizada via _set.

5. PROCESSAMENTO DA QUEUE

5.1 Captura via cron
Momento: Execução assíncrona

Busca registros na tabela:
wosk_queue

Critério:
situacao = 0
status = 'Aguardando Integração'

5.2 Validação final
Momento: Pré-envio

Regras:
• Confirma existência de campos obrigatórios.
• Revalida CPF/CNPJ.
• Verifica consistência de município e país.
• Verifica duplicidade externa se aplicável.

5.3 Transformações finais
Momento: Pré-envio

• Conversão de datas para padrão aceito pelo Protheus.
• Ajuste de estrutura JSON/XML.
• Remoção de campos internos.
• Inclusão de campos obrigatórios do layout externo.

5.4 Envio ao sistema externo
Momento: Envio

• Chamada HTTP/REST ou outro protocolo configurado.
• Registro do payload enviado.
• Armazenamento da resposta.

5.5 Atualização de status
Momento: Pós-envio

Sucesso:
situacao ← 2
status ← 'Integrado'

Erro:
situacao ← 4
status ← 'Erro'

Persistência realizada em:
wosk_queue

Campos atualizados:
status
situacao
mensagem_retorno
data_processamento

6. PERSISTÊNCIA DE CONTROLE

6.1 Controle do Monitor

Armazenado via:
_set("ProtheusCliente")

Dados persistidos:

offset
chave_posicao
data_posicao
filtro
situacao
data_iniciado
token

6.2 Fila de Integração

Tabela:
wosk_queue

Campos:

chave
conteudo
status
situacao
data_referencia
token
data_processamento
mensagem_retorno

7. OPERAÇÃO MANUAL – capturar()

Permite reenfileiramento manual de registros específicos.

Entrada:
chave no formato:

A1_LOJA-A1_COD-CGC_CPF

Fluxo:

1. Valida formato da chave.

2. Consulta direta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES.

3. Sanitiza dados (trim).

4. Reenvia para Queue.

Regra adicional:
Se já existir registro na fila → reaproveita token existente.

Persistência:
wosk_queue (INSERT ou UPDATE).

8. RESULTADO DO PROCESSAMENTO

Execução normal:

• WebService persiste dados normalizados.
• Monitor captura incrementalmente.
• Queue processa e integra com sistema externo.
• Monitor marcado como CONCLUÍDO (2).
• Queue marcada como Integrado.

Execução com erro:

• Monitor marcado como PROBLEMA (4).
• Erro armazenado em filtro.
• Queue marcada como Erro.
• Registro disponível para reprocessamento.

CONCLUSÃO

A arquitetura garante:

• Separação de responsabilidades.
• Processamento escalável.
• Controle transacional de posição.
• Evita duplicidade.
• Alta rastreabilidade.
• Continuidade automática em caso de falhas.
• Integridade e consistência dos dados até a integração final com o Protheus.