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 (não hásem endpoint implementado aqui).

Monitor

Processo: 
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: capturar (de forma pontual/manual) registros de clientescliente dapor fonte SQL WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAOchave e enfileirar cada registro para integração assíncrona.ncrona no Protheus.
- 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.

No fluxo manual, paraPara cada chave informada,recebida, o processo:processo executa:
- Normaliza a entrada para lista de chaves (suporta chave única ou array).
- Reaproveita token existente na fila (quando houverdo item jáde criado)fila, consultando Queue::get('', chave)chaveOriginal) quando houver registro.
- Valida formato da chave e deriva filtros (A1_LOJA e A1_COD).
- ConsultaExecuta aconsulta na fonte SQLde dados do monitor (viewQuery) filtrando por A1_LOJA e A1_COD.
- Sanitiza o registro retornado com trim() recursivo em todos os campos.
- Reestrutura o controle de posicionamentoposição (novoFiltro) com A1_LOJA,a A1_CODchave do cliente e a DATA_PARA_TRANSFERENCIA (normalizada).normalizada.
- Monta a chave da fila no formato A1_LOJA-A1_COD e enfileiragrava viao Queue::set()item para processamento assíncrono com status Aguardando Integração e situacao = 0.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

NãEste arquivo não háimplementa endpoint (WebService) implementado neste arquivo.. Para o Monitor, oso dadosdado necessáriosrio são:para execução manual é a chave do cliente.

Entrada do processo manual:processo:
- Parâmetro chave: string ou array.
- Formato obrigatório da chave:rio: A1_LOJA-A1_COD.
- Regra: se a chave nãoprecisa possuirconter exatamente 2 segmentos, o processo lança exceçãosegmentos (separados por Chave inválida-).

Fonte de dados:dados (captura):
- 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: NãInício do capturar()
- Constrói a lista de execução aplicado(chaves) noa fluxopartir atualdo (parâmetro run()chave vazio).
- ORecupera controletoken prévio do item de estadofila existe(quando via Monitor::get()/Monitor::set()existir), persistindogarantindo emrastreabilidade wosk_monitorna quandoregravação utilizadodo por integrações que exigem retomada/continuidade.item.

3.2 Reset ao iniciar execução
Momento: NãoInício aplicadodo noloop fluxode atualchaves
- Para cada chave, prepara variáveis de contexto (run()chave vazio)atual, token associado e filtros derivados).

3.3 Normalização dos filtros
Momento: Pré-consulta no(por fluxo manual (capturar()).chave)
- DerivaDivide filtrosa diretamentechave 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: NãAntes do enfileiramento
- O item é gravado com status textual Aguardando Integração e situação aplicadoinicial no0, fluxoestabelecendo atual (não persisteponto situacaode nopartida capturar()).do processamento assíncrono.

3.5 Paginação dos registros
Momento: NãExecução aplicável.da consulta
- A consulta manualé filtraexecutada por chave e processachave; o resultadoprocessamento percorre as linhas retornadas 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 novoFiltro['A1_LOJA']novoFiltro ecom:
    - novoFiltro['A1_COD']A1_LOJA
    - A1_COD
    - DATA_PARA_TRANSFERENCIA comnormalizada valores do registro.
- Normaliza novoFiltro['DATA_PARA_TRANSFERENCIA'] paraem Y-m-d H:i:s.

3.8 Enfileiramento
Momento: DentroPós-sanitização do(por loop do capturar().registro)
- Monta keya no padrãochave: A1_LOJA-A1_COD.
- Enfileira via Queue::set(key,chave, registro, [], 'Aguardando Integração', ...).
- ReaproveitaQuando houver token seprévio, oele itemé já existirreaproveitado na filagravação (obtidodo via Queue::get).item.

3.9 Atualização incremental da posição
Momento: NãoApós aplicável.inserir na fila
- O controle incremental deste fluxo manual nãofica atualizaregistrado no próprio item de fila, via chave e offset/chave_posicaodata_adicionado emdo wosk_monitor.item gravado/atualizado.

3.10 Finalização
Momento: FinalConclusão do capturar().processamento de todas as chaves
- Não há persistência de encerramentoEncerramento do monitor (situação) neste fluxo manual; a finalização é implícitalote após enfileirar.enfileirar todos os registros encontrados para as chaves informadas.

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


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

4.1 Controle do monitor
Momento: QuandoPersistência Monitor::set()de éestado utilizadodo monitor (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 persistida (biblioteca wosk_queue):Tabela: {$this->bancoIntegrador}.wosk_queue.


5. RESULTADO DO PROCESSAMENTO

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

Execução com erro:
- OExceção erro é registradoregistrada e o itemlote pode deixarencerrar antes de serenfileirar enfileiradotodos (dependendoos doregistros ponto de falha).planejados.


6. OPERAÇÃO MANUAL – capturar()

Objetivo: enfileirar manualmente um ou mais clientes paraa integração,partir usandoda chave conhecida.chave.

Fluxo:
- Entrada: chave string ou array, no padrão A1_LOJA-A1_COD.
- Para cada chave:
    - ConsultaReaproveita atoken filado paraitem reaproveitar token (quando existir).existir na fila.
    - Consulta ao registro correspondente na fonte SQL filtrando por A1_LOJA e A1_CODWOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO.
    - Sanitiza o registro come trim()enfileira recursivo.
para - Enfileira via Queue::set()integração com status Aguardando Integração e situacao = 0.

Queue

Processo:
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: consumir um item da fila, reestruturar/normalizar odados payloaddo cliente para o padrão Protheus e executar o envio, persistindo retorno, tempo e statussituação nado própria fila.processamento.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, oa processofila busca um item via get(token). Se houver registro:
- Atualiza o mesmoitem para status Enviando e situacao = 1 antes do envio (marcando consumo em andamento).envio.
- Converte o conteúdoconteudo 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 (aplicadas no payload Protheus):envio:
- 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.gitos (STR_PAD_LEFT).

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 não houvera resposta →vier erro:vazia, o processamento gera erro de integração (JSON: NÃO HOUVE RESPOSTA.).
- Se a resposta não forpuder ser interpretada como array ou não contiver Mensagem, →o erro:processamento JSON:gera NÃOerro FOIde POSSÍVEL DECODIFICARdecodificação.
- A RESPOSTA.mensagem persistida prioriza Mensagem Detalhada quando existir.
- SituaçãoA situacao final doé item:definida por:
    - 2 quando sucesso (sem code e Mensagem diferente de ERRO).sucesso.
    - 4 quando houver erro (por code no retorno ou quando Mensagem = "ERRO".
- Mensagem gravada prioriza Mensagem Detalhada (quando presente)).

Ações adicionais por resultado:pós-sucesso:
- SucessoMarca (situacaoo = 2): marcacliente como integrado via setProtheusClienteIntegrado(chave, true).
- e sinaliza remoção deRemove itens correlatos na fila.
- Pós-sucesso (limpeza de fila):fila tentapara removerevitar registrosduplicidade, relacionadosexecutando exclusões em wosk_queue para as ações ProtheusCliente (por SUBSTRING_INDEX(chave, '-', 2)) e ProtheusClienteFull (porchaves derivadas da chave), evitando duplicidade de processamento.original).

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

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

NãEste arquivo não háimplementa endpoint (WebService) implementado neste arquivo.. Para a Queue, os dados necessáriosde entrada 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 capturadodo (camposcliente, conforme viewQuery do cliente).monitor.
- data_adicionado: data/horareferência de capturatemporal 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: NãExecução aplicável (processa 1por item por(consumo execução)unitário).

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

3.7 Atualização do filtro de posição
Momento: NãoPós-processamento aplicádo item
- O item permanece rastreável (controlepela dechave posiçe pelo token, com retorno e situação épersistidos dona Monitor).fila.

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

3.9 Atualização incremental da posição
Momento: NãAtualização aplicáveldo item
- A posição do processamento é refletida na própria fila por status e situação (não1 hádurante offsetenvio; nesta2 classe)ou 4 ao concluir).

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,erro no retorno, 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: NãoPersistência aplicáveldo paraestado estado classemonitor (nãoquando gravautilizado pela integração)
- Tabela: {$this->bancoIntegrador}.wosk_monitor).

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


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item atualizadofinalizado paracom situacao = 2, com retorno persistido e marcação do cliente marcado como integrado.

Execução com erro:
- Item atualizadofinalizado paracom situacao = 4, com retorno/mensagemmensagem/retorno persistidos para auditoria e notificação.


6. OPERAÇÃO MANUAL – capturar()

Não aplicável para esta classe (a operaçOperação manual está nadefinida classeno 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