ProtheusClientePadrao (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	TO-DO
Nome do projeto	TO-DO
Biblioteca	wosk_protheus_cliente_padrao
Token da Biblioteca	31e42d08-2d8e-4d74-b4ec-e66ef85f3c66
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/31e42d08-2d8e-4d74-b4ec-e66ef85f3c66/wosk_protheus_cliente_padrao
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/31e42d08-2d8e-4d74-b4ec-e66ef85f3c66/wosk_protheus_cliente_padrao
Data	23/02/2026

Sumário

• Documentação Técnica
  
• Sumário
• Histórico de Versões
• Descrição Geral dos Processos
  • Monitor
  • Queue
• Fluxo do Processo
• Critérios de Aceitação

Histórico de Versões

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

Descrição Geral dos Processos

Escopo deste arquivo:

- Este documento foi gerado exclusivamente a partir de wosk_protheus_padrao/wosk_protheus_padrao.php.
- Classes presentes neste arquivo: Monitor e Queue.
- Classe ausente neste arquivo: Webservice (semnão há endpoint implementado aqui).

Monitor

Processo: 
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: capturar (de forma pontual/manual) registros de clienteclientes porda chavefonte SQL WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO e enfileirar cada registro para integração assíncrona no Protheus.ncrona.
- Disparo: operação manual via Monitor::capturar(chave).
- Observação crítica: o método Monitor::run() está vazio neste arquivo; portanto, não há captura automática/cron implementada aqui.
Para
No fluxo manual, para cada chave recebida,informada, o processo executa:
- Normaliza a entrada para lista de chaves (suporta chave única ou array).processo:
- Reaproveita token existente dona fila (quando houver item dejá fila,criado) consultando Queue::get('', chaveOriginal)chave) quando houver registro.
- Valida formato da chave e deriva filtros (A1_LOJA e A1_COD).
- ExecutaConsulta consulta naa fonte de dados do monitor (viewQuery)SQL filtrando por A1_LOJA e A1_COD.
- Sanitiza o registro retornado com trim() recursivo em todos os campos.
- Reestrutura o controle de posiçãoposicionamento (novoFiltro) com aA1_LOJA, chave do clienteA1_COD e a DATA_PARA_TRANSFERENCIA normalizada.(normalizada).
- Monta a chave da fila no formato A1_LOJA-A1_COD e gravaenfileira ovia item para processamento assíncronoQueue::set() com status Aguardando Integração e situacao = 0.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Este arquivo nãNão implementahá endpoint (WebService). implementado neste arquivo. Para o Monitor, oos dadodados necessáriorios para execução manual é a chave do cliente.são:

Entrada do processo:processo manual:
- Parâmetro chave: string ou array.
- Formato obrigatório:rio da chave: A1_LOJA-A1_COD.
- Regra: se a chave precisanão conterpossuir exatamente 2 segmentossegmentos, o processo lança exceção (separadosChave por -inválida).

Fonte de dados (captura):dados:
- View/Tabela lógica: WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO

Campos capturados (conjunto completo do viewQuery):
- Identificação: A1_COD, A1_LOJA
- Cadastro: CGC_CPF, NOME, PESSOA, NOME_REDUZ, TIPO, STATUS
- Endereço: ENDERECO, BAIRRO, COMPLEMENTO, UF, CEP, COD_MUNICIPIO_IBGE
- Contato: DDI, DDD, TELEFONE, CONTATO, EMAIL
- Documentos/Complementos: A1_PFISICA, A1_INSCR, INSC_MUNICIPAL, DATA_NASC
- País/Tributos/Outros: COD_PAIS_SISCOMEX, COD_PAIS_BC, A1_CONTA, A1_CONTRIB, A1_TPESSOA, A1_SUFRAMA, A1_CALCSUF, A1_CODMUN
- Controle incremental: DATA_PARA_TRANSFERENCIA


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: InícioNão doaplicado no fluxo atual (capturar(run()
- Constrói a lista de execução (chaves) a partir do parâmetro chavevazio).
- RecuperaO token prévio do itemcontrole de filaestado (existe via Monitor::get()/Monitor::set(), persistindo em wosk_monitor quando existir),utilizado garantindopor rastreabilidadeintegrações naque regravaçãoexigem do item.retomada/continuidade.

3.2 Reset ao iniciar execução
Momento: InícioNão doaplicado loopno defluxo chaves
- Para cada chave, prepara variáveis de contextoatual (chaverun() atual, token associado e filtros derivados)vazio).

3.3 Normalização dos filtros
Momento: Pré-consulta no fluxo manual (por chave)capturar()).
- DivideDeriva afiltros diretamente da chave em: A1_LOJA e A1_COD.
- Monta a consulta SQL com filtros exatos para recuperar o registro correspondente.

3.4 Atualização do estado para EXECUTANDO
Momento: AntesNão doaplicado enfileiramento
-no Ofluxo itematual é(não gravado com status textualpersiste Aguardando Integraçãosituacao e situação inicialno 0capturar(), estabelecendo o ponto de partida do processamento assíncrono.).

3.5 Paginação dos registros
Momento: ExecuçãNão da consultaaplicável.
- A consulta émanual executadafiltra por chave;chave e processa o processamento percorre as linhas retornadasresultado via fetch(). sem paginação/offset.

3.6 Sanitização dos dados
Momento: Ao ler cada registro (loop de fetch).
- Aplica trim() recursivamente em todos os campos do registro.

3.7 Atualização do filtro de posição
Momento: Após ler o registro (fluxo manual).
- Define novoFiltronovoFiltro['A1_LOJA'] com:e novoFiltro['A1_COD'] com valores do registro.
    - A1_LOJA
    -Normaliza A1_COD
    - DATA_PARA_TRANSFERENCIAnovoFiltro['DATA_PARA_TRANSFERENCIA'] normalizada empara Y-m-d H:i:s.

3.8 Enfileiramento
Momento: Pós-sanitizaçãoDentro (pordo registro)loop do capturar().
- Monta akey chave:no padrão A1_LOJA-A1_COD.
- Enfileira via Queue::set(chave,key, registro, [], 'Aguardando Integração', ...).
- QuandoReaproveita houvertoken tokense prévio,o eleitem éjá reaproveitadoexistir na gravaçãofila do(obtido item.via Queue::get).

3.9 Atualização incremental da posição
Momento: ApósNão inserir na filaaplicável.
- O controle incremental deste fluxo manual ficanão registrado no próprio item de fila, via chave eatualiza data_adicionadooffset/chave_posicao doem item gravado/atualizado.wosk_monitor.

3.10 Finalização
Momento: ConclusãoFinal do processamentocapturar().
- Não há persistência de todas as chaves
- Encerramentoencerramento do lotemonitor (situação) neste fluxo manual; a finalização é implícita após enfileirar todos os registros encontrados para as chaves informadas.enfileirar.

3.11 Tratamento de erro
Momento: catch(Exception) do capturar().
- Registra a exceçãoerro via errorByexception e encerra o cicloprocessamento do lote em execução.atual.


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

4.1 Controle do monitor
Momento: PersistênciaQuando deMonitor::set() estadoé do monitorutilizado (não ocorre no capturar()).
- Tabela persistida (implementação da trait wosk_monitor)
- Tabela:: {$this->bancoIntegrador}.wosk_monitor.
- Campos persistidos: token, evento, offset, filtro, chave_posicao, situacao, data_posicao, data_iniciado.

4.2 Fila de integração
Momento: Enfileiramento (3.8).
- Tabela:Tabela persistida (biblioteca wosk_queue): {$this->bancoIntegrador}.wosk_queue.


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Itens gravados na fila com status Aguardando Integração para envioprocessamento posterior ao Protheus pela Queue.

Execução com erro:
- ExceçãoO registradaerro é registrado e o loteitem pode encerrar antesdeixar de enfileirarser todosenfileirado os(dependendo registrosdo planejados.ponto de falha).


6. OPERAÇÃO MANUAL – capturar()

Objetivo: enfileirar manualmente um ou mais clientes apara partirintegração, dausando chave.chave conhecida.

Fluxo:
- Entrada: chave string ou array, no padrão A1_LOJA-A1_COD.
- Para cada chave:
    - ReaproveitaConsulta a fila para reaproveitar token do item (quando existir na fila.existir).
    - Consulta o registro correspondente naa fonte SQL filtrando por WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAOA1_LOJA e A1_COD.
    - Sanitiza o registro ecom enfileiratrim() pararecursivo.
    integração- Enfileira via Queue::set() com status Aguardando Integração e situacao = 0.

Queue

Processo:
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: consumir um item da fila, reestruturar/normalizar dadoso do clientepayload para o padrão Protheus e executar o envio, persistindo retorno, tempo e situaçãostatus dona processamento.própria fila.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, ao filaprocesso busca um item via get(token). Se houver registro:
- Atualiza o itemmesmo para status Enviando e situacao = 1 antes do envio.envio (marcando consumo em andamento).
- Converte o conteudoconteúdo persistido em payload de integração via getConteudo() (internamente _getConteudo), aplicando o mapeamento de campos definido em $field.

Transformações e normalizações pré-envio:envio (aplicadas no payload Protheus):
- A1_NOME e A1_NREDUZ: remove o caractere | e remove acentos.
- A1_END, A1_BAIRRO, A1_CONTATO: remove acentos.
- A1_CODPAIS: converte para inteiro e aplica zero-pad à esquerda até 5 dígitos (STR_PAD_LEFT).gitos.

Envio ao Protheus:
- Executa integração via setProtheus('cliente', payload, 'POST', headers).
- Header aplicado: tenantId fixo no formato "01,01SD0001" (derivado de 01SD0001).

Validação e classificação do retorno:
- Se anão houver resposta vier→ vazia,erro: o processamento gera erro de integração (JSON: NÃO HOUVE RESPOSTA.).
- Se a resposta não puder ser interpretada comofor array ou não contiver Mensagem, o→ processamentoerro: geraJSON: erroNÃO deFOI decodificação.POSSÍVEL DECODIFICAR A RESPOSTA.
- A mensagem persistida prioriza Mensagem Detalhada quando existir.
- A situacaoSituação final édo definida por:item:
    - 2 quando sucesso.sucesso (sem code e Mensagem diferente de ERRO).
    - 4 quando houver erro (por code no retorno ou quando Mensagem = "ERRO").
- Mensagem gravada prioriza Mensagem Detalhada (quando presente).

Ações pós-sucesso:adicionais por resultado:
- MarcaSucesso o(situacao cliente= 2): marca como integrado via setProtheusClienteIntegrado(chave, true).
- Removee sinaliza remoção de itens correlatos na fila.
- Pós-sucesso (limpeza de filafila): paratenta evitarremover duplicidade,registros executando exclusõesrelacionados em wosk_queue para as ações ProtheusCliente (por SUBSTRING_INDEX(chave, '-', 2)) e ProtheusClienteFull (chavespor derivadaschave), daevitando chaveduplicidade original).de processamento.

Persistência do resultadostatus do item:item (fila):
- Atualiza o próprio item de fila com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação final.final (2 ou 4).

Notificação de erros:
- O método notificar() consulta itens com acao = 'ProtheusClientePadrao' e situacao = 4 na tabela wosk_queue, formata a mensagem e aciona o mecanismo interno de notificação interno (_getNotificarErros).


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Este arquivo nãNão implementahá endpoint (WebService). implementado neste arquivo. Para a Queue, os dados de entradanecessários são os itens persistidos na fila.

Estrutura do item de fila (campos utilizados neste arquivo):
- token: identificador do item para consumo.
- acao: ProtheusClientePadrao.
- chave: A1_LOJA-A1_COD.
- conteudo: registro completo docapturado cliente, conforme viewQuery(campos do monitor.cliente).
- data_adicionado: referênciadata/hora temporalde captura gravada no enfileiramento.


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do item de fila
Momento: Início do run(token)
- Lê item via get(token).

3.2 Reset ao iniciar execução
Momento: Antes do envio
- Atualiza o item para status Enviando e situacao = 1.

3.3 Normalização do payload
Momento: Pré-envio
- Aplica mapeamento de campos via $field durante getConteudo().

3.4 Atualização do estado para EXECUTANDO
Momento: Pré-requisição
- Mantém o item como situacao = 1 até concluir o envio e classificar o retorno.

3.5 Paginação dos registros
Momento: ExecuçãNão aplicável (processa 1 item por item (consumo unitário)execução).

3.6 Sanitização dos dados
Momento: Pré-envio ao Protheus
- Remove acentos e caracterecaracteres | em campos textuais.
- Normaliza A1_CODPAIS para 5 dígitos com zero-pad.

3.7 Atualização do filtro de posição
Momento: Pós-processamentoNão aplicável (controle de posição é do item
- O item permanece rastreável pela chave e pelo token, com retorno e situação persistidos na fila.Monitor).

3.8 Envio / Integração
Momento: Envio ao Protheus
- ExecutaDispara setProtheus('cliente', payload, 'POST', headers).

3.9 Atualização incremental da posição
Momento: AtualizaçãNão doaplicável item
- A posiçã(não dohá processamentooffset énesta refletida na própria fila por status e situação (1 durante envio; 2 ou 4 ao concluir)classe).

3.10 Finalização
Momento: Pós-resposta do Protheus
- Define situacao final (2 ou 4) e atualiza o item na fila com retorno, mensagem, dump e tempo.

3.11 Tratamento de erro
Momento: catch(Exception) interno do processamento do item
- Registra erro no retorno,erro, define situacao = 4 e persiste a mensagem no item de fila.


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

4.1 Controle do monitor
Momento: PersistênciaNão doaplicável estadopara doesta monitorclasse (quandonão utilizado pela integração)
- Tabela:grava {$this->bancoIntegrador}.wosk_monitor).

4.2 Fila de integração
Momento: Durante todo o ciclo do item (get/set).
- Tabela:Tabela persistida: {$this->bancoIntegrador}.wosk_queue.
- LogAtualização de log (em falhas internas deda persistência (biblioteca wosk_queue)infraestrutura): {$this->bancoIntegrador}.wosk_queue_log (biblioteca wosk_queue).


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item finalizadoatualizado compara situacao = 2, com retorno persistido e marcaçãocliente do clientemarcado como integrado.

Execução com erro:
- Item finalizadoatualizado compara situacao = 4, mensagem/retornocom retorno/mensagem persistidos para auditoria e notificação.


6. OPERAÇÃO MANUAL – capturar()

OperaçNão aplicável para esta classe (a operação manual está definidana noclasse Monitor deste arquivo, com enfileiramento do item para consumo pela Queue).

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada