ProtheusClientePadrao (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	TO-DOOSKLEN
Nome do projeto	TO-DOIntegração LINX → Protheus
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/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_protheus_padrao/wosk_protheus_padrao.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: capturar (de forma pontual/manual) registroscadastro de clientes da(padrão) do LINX ao Protheus, preparando os dados e registrando o resultado do envio para acompanhamento.

Capturador

Descrição Conceitual

O capturador recebe uma chave (ou lista de chaves) no formato A1_LOJA-A1_COD, consulta a fonte SQLde WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAOdados e enfileirarlocaliza os registros correspondentes na view de integração.

Para cada registro para integração assí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.

No fluxo manual, para cada chave informada, o processo:
- Reaproveita token existente na fila (quando houver item já criado) consultando Queue::get('', chave).
- Consulta a fonte SQL filtrando por A1_LOJA e A1_COD.
- Sanitiza o registro com trim() recursivo em todos os campos.
- Reestrutura o controle de posicionamento (novoFiltro) com A1_LOJA, A1_COD e DATA_PARA_TRANSFERENCIA (normalizada).
- Monta a chave da fila no formato A1_LOJA-A1_COD e enfileira via Queue::set() com status Aguardando Integração e situacao = 0.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para o Monitor, os dados necessários são:

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

Fonte de 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: Não aplicado no fluxo atual (run() vazio).
- O controle de estado existe via Monitor::get()/Monitor::set(), persistindo em wosk_monitor quando utilizado por integrações que exigem retomada/continuidade.

3.2 Reset ao iniciar execução
Momento: Não aplicado no fluxo atual (run() vazio).

3.3 Normalização dos filtros
Momento: Pré-consulta no fluxo manual (capturar()).
- Deriva filtros diretamente da chave: A1_LOJA e A1_COD.

3.4 Atualização do estado para EXECUTANDO
Momento: Não aplicado no fluxo atual (não persiste situacao no capturar()).

3.5 Paginação dos registros
Momento: Não aplicável.
- A consulta manual filtra por chave e processa o resultado 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'] e novoFiltro['A1_COD'] com valores do registro.
- Normaliza novoFiltro['DATA_PARA_TRANSFERENCIA'] para Y-m-d H:i:s.

3.8 Enfileiramento
Momento: Dentro do loop do capturar().
- Monta key no padrão A1_LOJA-A1_COD.
- Enfileira via Queue::set(key, registro, [], 'Aguardando Integração', ...).
- Reaproveita token se o item já existir na fila (obtido via Queue::get).

3.9 Atualização incremental da posição
Momento: Não aplicável.
- O fluxo manual não atualiza offset/chave_posicao em wosk_monitor.

3.10 Finalização
Momento: Final do capturar().
- Não há persistência de encerramento do monitor (situação) neste fluxo manual; a finalização é implícita após enfileirar.

3.11 Tratamento de erro
Momento: catch(Exception) do capturar().
- Registra erro via errorByexception e encerra o processamento do lote atual.


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

4.1 Controle do monitor
Momento: Quando Monitor::set() é utilizado (não ocorre no capturar()).
- Tabela persistida (implementação da trait wosk_monitor): {$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): {$this->bancoIntegrador}.wosk_queue.


5. RESULTADO DO PROCESSAMENTO

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

Execução com erro:
- O erro é registrado e o item pode deixar de ser enfileirado (dependendo do ponto de falha).


6. OPERAÇÃO MANUAL – capturar()

Objetivo: enfileirar manualmente um ou mais clientes para integração, usando chave conhecida.

Fluxo:
- Entrada: chave string ou array, no padrão A1_LOJA-A1_COD.
- Para cada chave:
    - Consulta a fila para reaproveitar token (quando existir).
    - Consulta a fonte SQL filtrando por A1_LOJA e A1_COD.
    - Sanitiza o registro com trim() recursivo.
    - 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 o payload para o padrão Protheus e executar o envio, persistindo retorno, tempo e status na própria fila.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, o processo busca um item via get(token). Se houver registro:
- Atualiza o mesmo para status Enviando e situacao = 1 antes do envio (marcando consumo em andamento).
- Converteencontrado, o conteúdo persistidoé emencaminhado para a fila de processamento, onde será transformado e enviado ao Protheus.

Fonte

A entrada é obtida por consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO. O filtro (WHERE) é montado dinamicamente a partir da chave informada (A1_LOJA e A1_COD).

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

- Leitura: consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO para obter os dados do cliente a partir da chave informada.
- Persistência: os 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 pendente e utiliza o conteúdo do cliente como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização viae getConteudo()realiza (internamentea _getConteudo),chamada aplicandoao Protheus.

Ao final, o mapeamentoresultado definidoé empersistido $field.

Transformaçõesna própria tabela wosk_queue, registrando situação, mensagem e normalizaçõesresposta pré-enviopara (aplicadasauditoria e reprocessamento quando aplicável.

Estruturação de Dados

Mapa de campos do payload

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 removeaplica 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:
  - Se não houverde resposta: →registra erro:erro com a mensagem JSON: NÃO HOUVE RESPOSTA.
-
Se
• Resposta respostainválida/inesperada: quando não foré array ou não contiverpossui Mensagem, →registra erro:erro com a mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
-
Situação
• Indicadores finalde do item:
      - 2erro: quando sucessoMensagem é ERRO (sem code e Mensagem diferente de ERRO).
      - 4 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 viae setProtheusClienteIntegrado(chave,conclui true)o item como sucesso na fila.

Rotinas Inteligentes

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

Persistência e sinalizalimpeza remoçapós sucesso

• Persistência: o resultado da integração (sucesso/erro), mensagem e resposta são registrados na tabela wosk_queue.
• Limpeza: em caso de sucesso, a rotina remove registros auxiliares relacionados ao processo em tabelas/estruturas de controle do integrador (ex.: entidades ProtheusCliente e ProtheusClienteFull), evitando acúmulo de referências.

 

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.
- Auditoria: o tempo de processamento e os detalhes da requisição/resposta são persistidos na tabela wosk_queue para rastreabilidade.

Encaminhamento em cenário de erro

Quando há erro no envio ou na validação da resposta, o item é mantido na tabela wosk_queue com situação de erro e mensagem correspondente, permitindo reprocessamento conforme as rotinas padrões de fila do integrador.

Notificação

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

mensagem

Destinatários: os e-mails de destino estão definidos no código da biblioteca e acionarecebem o mecanismo internorelatório de notificação (_getNotificarErros).


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para a Queue, os dados necessários são os itens persistidos na fila.

Estruturaerros do item de fila (campos utilizados neste arquivo):
- token: identificador do item para consumo.
- acao: ProtheusClientePadrao.
- chave: A1_LOJA-A1_COD.
- conteudo: registro completo capturado (campos do cliente).
- data_adicionado: data/hora de 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é classificar o retorno.

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

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

3.7 Atualização do filtro de posição
Momento: 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).

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 item na fila com retorno, mensagem, dump e tempo.

3.11 Tratamento de erro
Momento: catch(Exception) interno do processamento do item
- Registra 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: Não aplicável para esta classe (não grava wosk_monitor).

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


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item atualizado para situacao = 2, com retorno persistido e cliente marcado como integrado.

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


6. OPERAÇÃO MANUAL – capturar()

Não aplicável para esta classe (a operação manual está na classe Monitor).

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.