ProtheusCliente

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

DOCUMENTAÇÃO – WEBSERVICE / MONITOR PROTHEUS CLIENTE

1. Histórico de Versões

   Data	Versão	Modificado por	Descrição da Mudança
   ?	1.0	Maykon/Gustavo	Documentação inicial

   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: 
   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 é executadoacionado viapor cron e realiza:

captura

•periodicamente Leituraregistros incrementalda baseadaview WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES que possuem DATA_PARA_TRANSFERENCIA a partir do filtro configurado. Recupera o estado anterior (offset, chave_posicao, data_posicao, filtro, situação). Se a situação estiver concluída (2), redefine para parado (0) para permitir novo ciclo. Se parado (0) ou em DATA_PARA_TRANSFERENCIA.
•execução Controle(1), denormaliza offsetos filtros (A1_LOJA, A1_COD, CGC_CPF, DATA_PARA_TRANSFERENCIA), monta a query com paginação (OFFSET/FETCH NEXT) usando o limite woskLimiteCaptura::ProtheusCliente, executa a consulta e para cada registro sanitiza os campos (trim), monta a chave deA1_LOJA-A1_COD-CGC_CPF, enfileira na Queue com status "Aguardando Integração" e atualiza incrementalmente a posição.
•o Paginaçdo monitor. Ao final marca situação viacomo OFFSETconcluída /(2). FETCH.
•Em Enfileiramentoerro, para processamento assíncrono.

Ele garante:
• Continuidaderegistra 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, auditoriafiltro[ERRORS] e histórico.

marca

Asituação filacomo garante:problema (4).
•
2. Escalabilidade.
• Reprocessamento controlado.
• Tolerância a falhas.
• Rastreabilidade completa.

2. DADOS NECESSÁRIOS PARA O ENDPOINTMONITOR
   Configuração: woskLimiteCaptura::ProtheusCliente (WEBSERVICE)

   inteiro)
–

quantidade

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
Tipomáxima de pessoa.

registros

STATUS
Situaçpor lote (top). Estado persistido: data_posicao, data_iniciado, offset, chave_posicao, filtro, situação, token. Filtros utilizados: A1_LOJA (opcional), A1_COD (opcional), CGC_CPF (opcional), DATA_PARA_TRANSFERENCIA (opcional; padrão cadastral.

2023-05-01

DATA_PARA_TRANSFERENCIA00:00:00).
Data
3. 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()

monitor
O

Dadosmétodo recuperados via _get(get("ProtheusCliente"):

offsetrecupera do controle do monitor: data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situação (0=parado, 1=executando, 2=concluído, 4=problema).
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.3.2 Reset deao iniciar execução
Momento:Se Quandosituação situacaofor ≠2 (concluído), é redefinida para 0 (parado) via set(..., 0, ...). Se situação for 0 (parado), antes de processar são resetados: dataPosicao e dataIniciado para new DateTime(), offset para 0, chavePosicao para string vazia. Se situação for 1

dataPosicao(executando), ←nenhum datareset atualé feito.
dataIniciado ← data atual
offset ← 0
chavePosicao ← ''

4.3.3 Normalização dos filtros
Momento:A1_LOJA, AntesA1_COD dae query

A1_LOJA ← ''CGC_CPF: se vazio
A1_CODvazios, ←ficam ''como string vazia. DATA_PARA_TRANSFERENCIA: se vazio
CGC_CPFvazio, ←é ''definido secomo vazio
DATA_PARA_TRANSFERENCIA ←
• valor informado → convertido
• vazio → '2023-05-01 00:00:00'

00;

4.caso contrário é convertido de string para DateTime e formatado em "Y-m-d H:i:s".
3.4 Atualização do estado para EXECUTANDO
Momento: Antes dade cada consulta

situacaoà ←view, 1

é

4.5chamado Consultaset(offset, paginada
Momento:chavePosicao, ExecuçdataPosicao, filtro, 1, dataIniciado, token), marcando situação dacomo 1 (executando).
3.5 Paginação dos registros
A query

Fonte:
WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES

é

Regra:
montada com WHERE DATA_PARA_TRANSFERENCIA >= filtro
'{filtro[DATA_PARA_TRANSFERENCIA]}', ORDER BY DATA_PARA_TRANSFERENCIA ASC
ASC, OFFSET offset
{offset} ROWS FETCH NEXT limiteConfigurado

{top}

4.ROWS ONLY. A view consultada é WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES (campos: A1_COD, A1_LOJA, CGC_CPF, NOME, PESSOA, 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, STATUS, DATA_PARA_TRANSFERENCIA).
3.6 Sanitização dos dados
Momento: Ao lerPara cada registro

linha

Transformação:
•retornada trim()(fetch recursivoASSOC), é aplicado array_walk_recursive com trim em todos os campos.

valores

4.do array.
3.7 ConstruçAtualização dado filtro de posição
O array novoFiltro recebe A1_LOJA, A1_COD, CGC_CPF e DATA_PARA_TRANSFERENCIA do registro atual; DATA_PARA_TRANSFERENCIA é formatada via setDateTime()->format("Y-m-d H:i:s").
3.8 Enfileiramento
A chave única
Momento:de Dentroenfileiramento doé loop

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

CGC_CPF.

4.8É Enfileiramento
Momento:chamado DentroqueueClass->set(key, dor, loop

Operação:
Queue::set()

Tabela de persistência:
wosk_queue

Campos gravados:

chave
conteudo (payload completo do registro)
status =[], 'Aguardando Integração', '', 0, 0, setDateTime(novoFiltro[DATA_PARA_TRANSFERENCIA])). Se set retornar false, é lançada exceção.
situacao = 0
data_referencia = DATA_PARA_TRANSFERENCIA
token (se houver)

4.3.9 Atualização incremental da posição
Momento: Após inserircada na fila

offset ←enfileiramento: offset +é 1
incrementado; chavePosicao ←= key
key; dataPosicao ←= DATA_PARA_TRANSFERENCIA

setDateTime(novoFiltro[DATA_PARA_TRANSFERENCIA]);

Persistidoset(offset, via:chavePosicao, dataPosicao, filtro, 1, dataIniciado, token).
_set("ProtheusCliente")

4.3.10 Finalização
Momento:Ao Fimsair do loop

situacao(stop=true ←ou offset < top), é chamado set(offset, chavePosicao, dataPosicao, novoFiltro, 2, dataIniciado, token), definindo situação como 2 (Concluíconcluído)

4..
3.11 Tratamento de erro
Momento:No catch(Exception)

catch:

situacaoerrorByexception(e); ←se 4
filtro['ERRORS'][]ERRORS] ←
não existir, é inicializado como array; é adicionado em filtro[ERRORS] um objeto com DATE
 (DateTime atual formatado) e MESSAGE

Persistência(e->getMessage()); doem erroseguida realizadaset(offset, viachavePosicao, _set.

dataPosicao,

filtro,
5. 4,

   PROCESSAMENTOdataIniciado, DAtoken), QUEUE

   marcando

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

como

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(problema).

4. 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 DOS DADOS (BANCO DE CONTROLE

6.DADOS)
4.1 Controle do Monitor

monitor
O

Armazenadoestado via:
do monitor (offset, chave_posicao, data_posicao, filtro, situação, data_iniciado, token) é persistido através do método _set("ProtheusCliente", ...)

,

Dadosque persistidos:

grava

offsetno armazenamento de controle do monitor (tabela/estrutura definida pelo trait WOSK\Commons\Monitor).
chave_posicao
data_posicao
filtro
situacao
data_iniciado
token

6.4.2 Fila de integração
Cada registro capturado é inserido na fila via Queue::set(), com chave A1_LOJA-A1_COD-CGC_CPF, payload do registro, status "Aguardando Integração", e data de referência DATA_PARA_TRANSFERENCIA. A persistência da fila é feita pela classe Queue (tabela/estrutura própria da fila).

5. RESULTADO DO PROCESSAMENTO
Ao concluir sem erro: situação

Tabela:2 (concluído); estado atualizado com último offset, chave_posicao e data_posicao; todos os registros do lote enfileirados para processamento assíncrono pela Queue. Em caso de exceção: situação 4 (problema); filtro[ERRORS] com data e mensagem do erro; estado do monitor mantém offset/chave/data até o último registro processado com sucesso.
wosk_queue

6.

Campos:

chave
conteudo
status
situacao
data_referencia
token
data_processamento
mensagem_retorno

7. OPERAÇÃO MANUAL – capturar()

   
   O
método

capturar($chave)

Permitepermite reenfileiramentoincluir manualmanualmente um ou vários itens na fila. O parâmetro chave pode ser uma string (uma chave) ou um array de registroschaves. específicos.

Cada

Entrada:
chave nodeve formato:

ter

o formato A1_LOJA-A1_COD ou A1_LOJA-A1_COD-CGC_CPF

Fluxo:

(2

ou
1. 3

   Validapartes formatoseparadas por '-'). Para cada chave: é obtido o registro atual da chave.

   Queue
(get)
2. para

   Consultapreservar diretao token; a chave é quebrada em partes (explode '-', 3); é montada a query na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES.

   WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES
com
3. WHERE

   SanitizaA1_LOJA, dadosA1_COD e opcionalmente CGC_CPF; os registros retornados são sanitizados (trim).

   ,
monta-se
4. novoFiltro

   Reenviae parakey, Queue.

   e
são

Regra adicional:
Se já existir registroinseridos na fila →via 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 finalQueue::set com o Protheus.mesmo token. Chave inválida (menos de 2 ou mais de 3 partes) gera exceção. Exceções são tratadas com errorByexception.

Queue

Processo:
PROCESSO_QUEUE

WebService

Processo:
PROCESSO_WEBSERVICE

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