ProtheusCliente (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	TO-DOOSKLEN
Nome do projeto	TO-DOIntegração LINX → Protheus
Biblioteca	wosk_protheus_cliente
Token da Biblioteca	04c0adf0-ee2a-4f36-aa5a-358420676cb6
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/04c0adf0-ee2a-4f36-aa5a-358420676cb6/wosk_protheus_cliente
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/04c0adf0-ee2a-4f36-aa5a-358420676cb6/wosk_protheus_clientewosk_protheus_cliente_padrao
Data	23/26/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/26/02/2026	1.0	Maykon/Gustavo	DocumentaçCriação inicialda documentação técnica do processo ProtheusClientePadrao.

Descrição Geral dos Processos

EscopoEsta destebiblioteca arquivo:

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

Monitor

Processo: 
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: executar captura incrementalcadastro de clientes a(padrão) partirdo deLINX umaao fonteProtheus, SQLpreparando os dados e enfileirarregistrando cadao registroresultado do envio para processamentoacompanhamento.

assíncrono.
-

Disparo:

Capturador

execuç

Descrição agendada (cron) chamando Monitor::run().

Ao iniciar, o processo carrega o estado persistido do monitor via get("ProtheusCliente"), obtendo:
- data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situacao.

Regras de continuidade:
- Se situacao = 2 (Concluído) → redefine para 0 (Parado) e permite nova execução.
- Se situacao estiver em [0, 1] → inicia/continua o processamento.

Quando inicia a partir de estado não-executando (situacao ≠ 1):
- dataPosicao ← agora
- dataIniciado ← agora
- offset ← 0
- chavePosicao ← vazio

Em seguida, normaliza o filtro (garantindo defaults) e define a data mínima de captura:
- A1_LOJA, A1_COD, CGC_CPF → string vazia quando ausente
- DATA_PARA_TRANSFERENCIA → se ausente, define 2023-05-01 00:00:00Conceitual

O monitorcapturador executarecebe paginaçãouma comchave OFFSET/FETCH(ou NEXTlista usandode limitechaves) configuradono emformato woskLimiteCaptura::ProtheusClienteA1_LOJA-A1_COD, consultandoconsulta a fonte WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTESde com:
-dados WHEREe DATA_PARA_TRANSFERENCIAlocaliza >=os filtro.DATA_PARA_TRANSFERENCIA
-registros ORDERcorrespondentes BYna DATA_PARA_TRANSFERENCIAview ASCde integração.

Para cada registro retornado:
- Sanitiza os valores com trim() (recursivo em todos os campos).
- Atualizaencontrado, o filtroconteúdo é encaminhado para a fila de posiçãoprocessamento, (A1_LOJA,onde A1_COD,será CGC_CPF, DATA_PARA_TRANSFERENCIA).
- Monta a chave da fila no formato: A1_LOJA-A1_COD-CGC_CPF.
- Enfileira via Queue::set() com status Aguardando Integraçãotransformado e situacaoenviado =ao 0Protheus.

Fonte

A entrada é obtida por consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO.
- Persiste incrementalmente offset, chavePosicao e dataPosicao após enfileirar.

Encerramento:
- Quando não há mais registros, marca o monitor como situacao = 2 (Concluído) e persiste o últimoO filtro efetivo.

Em caso de erro (catch):
- Marca o monitor como situacao = 4 (Problema).
- Armazena a mensagem em filtro.ERRORS[] com data e descrição do erro.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para o Monitor, os dados de entrada são originados da fonte SQL consultada em viewQuery.

Fonte de dados:
- View/Tabela lógica: WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES

Campos capturados (conjunto completo):
- Identificação: A1_COD, A1_LOJA, CGC_CPF
- Cadastro: 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

Observação: no fluxo automático (run(WHERE)), apenas DATA_PARA_TRANSFERENCIA é aplicadamontado na cláusula WHERE da consulta (os demais filtros são normalizados e persistidos como estado).


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Início do run()
- Lê estado via get("ProtheusCliente") (offset, chave, datas, filtro, token, situação).
- Regra: se situacao = 2, redefine para 0 antes de prosseguir.

3.2 Reset ao iniciar execução
Momento: Quando situacao ≠ 1
- Reseta dataPosicao, dataIniciado, offset e chavePosicao para reinício controlado.

3.3 Normalização dos filtros
Momento: Antes da query
- Preenche A1_LOJA, A1_COD, CGC_CPF com string vazia quando ausente.
- Define DATA_PARA_TRANSFERENCIA:
    - informado → convertido para datetime e formatado
    - ausente → 2023-05-01 00:00:00

3.4 Atualização do estado para EXECUTANDO
Momento: Antes da consulta
- Persiste situacao = 1 com o estado atual (offset, chave, datas, filtro, token).

3.5 Paginação dos registros
Momento: Execução da query
- Ordena por DATA_PARA_TRANSFERENCIA ASC.
- Aplica paginação com OFFSET baseado no estado e FETCH NEXT no limite configurado.

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 cada registro
- Atualiza novoFiltro com os campos-chave do registro e a DATA_PARA_TRANSFERENCIA normalizada.

3.8 Enfileiramento
Momento: Dentro do loop de registros
- Monta chave no padrão A1_LOJA-A1_COD-CGC_CPF.
- Enfileira com Queue::set(chave, registro, ...).
- Status gravado: Aguardando Integração.
- Situação gravada: 0.

3.9 Atualização incremental da posição
Momento: Após inserir na fila
- offset ← offset + 1
- chavePosicao ← chave
- dataPosicao ← DATA_PARA_TRANSFERENCIA
- Persiste o estado imediatamente para garantir retomada em caso de interrupção.

3.10 Finalização
Momento: Encerramento do loop
- Persiste situacao = 2 com o último novoFiltro (estado efetivo de posição).

3.11 Tratamento de erro
Momento: catch(Exception)
- Adiciona registro em filtro.ERRORS[] contendo DATE e MESSAGE.
- Persiste situacao = 4 (Problema).


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

4.1 Controle do monitor
Momento: Durante a execução e finalização do run()
- Persistência ocorre via Monitor::set() (método _set da biblioteca wosk_monitor).
- Campos persistidos (visíveis neste arquivo): offset, chave_posicao, data_posicao, filtro, situacao, data_iniciado, token.
- Tabela/estrutura física do armazenamento: não há SQL explícito neste arquivo, portanto o nome da tabela não está identificado aqui.

4.2 Fila de integração
Momento: Enfileiramento (3.8)
- Operação executada por Queue::set() (persistência interna via biblioteca wosk_queue).
- Tabela explicitamente referenciada neste arquivo: wosk_queue (consultas e notificação de erros).


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Monitor marcado como Concluído (2) ao final.
- Registros enfileirados com status Aguardando Integração para processamento posterior.

Execução com erro:
- Monitor marcado como Problema (4).
- Erro registrado em filtro.ERRORS[].


6. OPERAÇÃO MANUAL – capturar()

Objetivo: capturar (re-enfileirar) manualmente um ou mais clientesdinamicamente a partir da chave.

Fluxo:
-chave Entrada:informada chave string ou array, no padrão A1_LOJA-A1_COD[-CGC_CPF].
- Para cada chave:
    - Consulta a fila via Queue::get('', chave) para reaproveitar token quando existir.
    - Consulta a fonte por (A1_LOJA, A1_COD e opcionalmente CGC_CPFA1_COD).
    - Sanitiza com trim() e enfileira via Queue::set() com o token reaproveitado.

Queue

SELECT
    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
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO
WHERE
    A1_LOJA = '<A1_LOJA>'
    AND A1_COD = '<A1_COD>'

 

Operações com Dados

- Processo:Leitura:
consulta 1.na DESCRIÇÃOview DOWOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO FLUXO
para obter os dados do cliente a partir da chave informada.
- Responsabilidade:Persistência: consumiros registros capturados são registrados para processamento assíncrono na tabela wosk_queue (base de integração), permitindo rastreabilidade do processamento e do resultado (sucesso/erro).

Fila de Processamento

Descrição Conceitual

A fila recebe um item dapendente fila,e transformar/normalizarutiliza o conteúdo do cliente como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e enviarrealiza paraa chamada ao Protheus.

Ao final, o Protheus,resultado registrandoé retorno e statuspersistido na própria fila.
-tabela Disparo:wosk_queue, execuçregistrando situação, mensagem e resposta para auditoria e reprocessamento quando aplicável.

Estruturação agendada (cron) chamando Queue::run(token).

Ao iniciar, a fila busca um registro via get(token). Se houver registro, atualiza o mesmo para status Enviando e situacao = 1 antes do envio.

Montagem e transformação do payload:
- O conteúdo armazenado na fila é convertido em estrutura de envioDados

por getConteudo() (internamente _getConteudo), usando o mapeamento

Mapa de campos definidodo empayload

$field.
-

Exemplo -de payload enviado

{
  "A1_COD": "000001",
  "A1_LOJA": "01",
  "A1_CGC": "00000000000000",
  "A1_NOME": "NOME DO CLIENTE",
  "A1_PESSOA": "F",
  "A1_NREDUZ": "NOME REDUZIDO",
  "A1_END": "RUA EXEMPLO 123",
  "A1_BAIRRO": "CENTRO",
  "A1_COMPLEM": "APTO 101",
  "A1_TIPO": "N",
  "A1_EST": "SP",
  "A1_COD_MUN": "3550308",
  "A1_CEP": "01000000",
  "A1_DDI": "55",
  "A1_DDD": "11",
  "A1_TEL": "999999999",
  "A1_CONTATO": "CONTATO",
  "A1_PFISICA": "1",
  "A1_INSCR": "",
  "A1_INSCRM": "",
  "A1_DTNASC": "1980-01-01",
  "A1_EMAIL": "cliente@exemplo.com",
  "A1_PAIS": "1058",
  "A1_CODPAIS": "01058",
  "A1_CONTA": "",
  "A1_CONTRIB": "",
  "A1_TPESSOA": "",
  "A1_SUFRAMA": "",
  "A1_CALCSUF": "",
  "A1_CODMUN": "",
  "A1_MSBLQL": "N"
}

Tratamento de Dados

Antes do envio ao Protheus, o conteúdo do cliente passa pelas seguintes alterações:

• A1_NOME e A1_NREDUZ: remove o caractere | e aplica remoção de acentos.
  
- A1_END, A1_BAIRRO, A1_CONTATO
• A1_NREDUZ: remove o caractere | e aplica remoção de acentos.
  
-
• A1_END: aplica remoção de acentos.
• A1_BAIRRO: aplica remoção de acentos.
• A1_CONTATO: aplica remoção de acentos.
• A1_CODPAIS: converte para inteiro e aplicapadroniza zero-padcom 5 dígitos, preenchendo com zeros à esquerda até(ex.: 51058 dígitos.
  
  Envio→ ao01058).
Protheus:
-

Executa

Integração com o Protheus

Chamada de integração viacom setProtheus("cliente",o payload,Protheus

"POST",

headers).
-
• Recurso: Headercliente
aplicado:
• Método HTTP: POST
• Cabeçalhos:
  • tenantId: no01,01SD0001
  formato
  "01,01SD0001"
(derivado

Tratamento de 01SD0001).

Validaçãoretorno e(obrigatório)

classificação

do
• Ausência retorno:
  -de Seresposta: registra erro com a mensagem JSON: NÃO HOUVE RESPOSTA.
• Resposta inválida/inesperada: quando não houver resposta → erro.
  - Se resposta não foré array ou não contiverpossui Mensagem, →registra erro.
  -erro situacaocom finala domensagem item:
  JSON: -NÃO 2FOI POSSÍVEL DECODIFICAR A RESPOSTA.
• Indicadores de erro: quando sucesso.
  Mensagem -é 4ERRO quando houver code no retorno (ou quando Mensagemhá =presença "ERRO".
  -de mensagemcode), gravadao priorizaitem Mensagemé Detalhadamarcado (como erro na fila e a resposta é armazenada para auditoria.
• Condição de sucesso: quando presente).
  
  Açõesnão adicionaishá porindicador resultado:
  -de Sucessoerro, (situacaoa = 2):rotina marca o cliente como integrado via setProtheusClienteIntegrado("A1_LOJA-A1_COD", true).
  - Erro (situacao = 4): tenta reprocesso alternativo acionando WOSK\\ProtheusClientePadrao\\Monitor::capturar() para a mesma chave (estratégia de fallback). Se existir item correspondente na fila com acao = 'ProtheusClientePadrao' e token, o registro atual pode ser removido do fluxo original.
  
  Persistência do status do item (fila):
  - Em fluxo padrão, ao final atualiza o mesmo registro com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação final.
  - Em caso de remoção condicional (erro + fallback capturado), executa exclusão via setProtheusExcluir(['ProtheusCliente'], 'chave', chave).
  
  
  2. DADOS NECESSÁRIOS PARA O ENDPOINT
  
  Não há endpoint (WebService) implementado neste arquivo. Para a Queue, os dados de entrada são os registros persistidos na fila.
  
  Estrutura do item de fila (visível pelo uso neste arquivo):
  - token: identificador do item para consumo.
  - chave: A1_LOJA-A1_COD-CGC_CPF.
  - conteudo: registro completo capturado pelo monitor (campos do cliente).
  - data_adicionado: referência temporal 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 para indicar consumo em andamento.
  
  3.3 Normalização do payload
  Momento: Pré-envio
  - Aplica mapeamento de campos via $field durante a preparação do conteúdo.
  
  3.4 Atualização do estado para EXECUTANDO
  Momento: Pré-requisição
  - Mantémconclui o item como situacaosucesso =na 1fila.
até

concluir

Rotinas Inteligentes

Foi identificada a chamada da rotina inteligente setProtheusClienteIntegrado, utilizada para registrar o enviocliente como integrado após o retorno de sucesso do Protheus.

Persistência e classificarlimpeza após sucesso

• Persistência: o retorno.
  
  3.5resultado Paginaçda integração dos(sucesso/erro), mensagem e resposta são registrados na tabela wosk_queue.
• Limpeza: em caso de sucesso, a rotina remove registros
  Momento: Nãoauxiliares aplicável (a Queue processa um item por execução).
  
  3.6 Sanitização dos dados
  Momento: Pré-enviorelacionados ao Protheus
  -processo Removeem acentostabelas/estruturas de controle do integrador (ex.: entidades ProtheusCliente e caracteresProtheusClienteFull), |evitando em campos textuais.
  - Normaliza A1_CODPAIS para 5 dígitos com zero-pad.
  
  3.7 Atualização do filtroacúmulo de posição
  Momento:referências.
Não

aplicável

 (controle

de

posição é do Monitor).

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

3.9 Atualização incremental da posição
Momento: Não aplicável (não há offset nesta classe).

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

3.11

Tratamento de retorno

- Sucesso: quando a resposta não indica erro, o item é concluído como sucesso na fila e o cliente é marcado como integrado.
- Erro: quando ocorre exceção, retorno ausente/invalidado ou resposta com erro, o item permanece registrado com erro e a mensagem detalhada é armazenada para consulta.
Momento:- catch(Exception)Auditoria: internoo dotempo de processamento doe item
-os Registradetalhes da requisição/resposta são persistidos na tabela wosk_queue para rastreabilidade.

Encaminhamento em cenário de erro

Quando há erro no retorno,envio defineou situacaona =validação 4da resposta, o item é mantido na tabela wosk_queue com situação de erro e persiste a mensagem nocorrespondente, itempermitindo dereprocessamento fila.


4.conforme PERSISTÊNCIAas DOSrotinas DADOS (BANCO DE DADOS)

4.1 Controle do monitor
Não aplicável (esta classe não persiste estado de monitor).

4.2 Fila de integração
- Tabela explicitamente referenciada neste arquivo: wosk_queue.
- Atualizaçõpadrões ocorrem via Queue::set() em fases distintas:
    - Pré-envio: status Enviando, situacao = 1
    - Pós-envio: persistência de retorno, mensagem, dump de requisição, tempo e situacao final


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item de fila finaliza com situacao = 2 e registra retorno do Protheus.

Execuçintegrador.

Notificação

com

SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem` AS 'ERRO'
FROM
    `<bancoIntegrador>`.`wosk_queue`
WHERE
    `acao` = 'ProtheusClientePadrao' AND `situacao` = 4
ORDER BY
    `data` ASC

Tratamento do relatório

Destinatários: os e-mails de destino estão definidos no código da biblioteca e recebem o relatório de erros do processo.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por chave	Ao informar uma chave válida no padrão A1_LOJA-A1_COD, deve consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO e registrar o item correspondente na fila de processamento.	Item pendente registrado na wosk_queue, pronto para processamento.
Fila de Processamento	Transformação e envio	Ao processar um item pendente, deve montar o payload com os campos A1_* e aplicar as alterações documentadas (remoção de |, remoção de acentos e padronização de A1_CODPAIS), realizando a chamada de integração ao Protheus.	Fila atualizada com resultado: sucesso (cliente marcado como integrado) ou erro (mensagem e resposta registradas).
Fila de Processamento	Notificação de erros	Quando existirem itens com erro, deve gerar relatório a partir da wosk_queue filtrando pela ação ProtheusClientePadrao e ordenando por data de processamento, enviando aos destinatários configurados.	Relatório enviado e erros apresentados com mensagem legível e datas formatadas.