Ir para o conteúdo principal

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


    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 (sem endpoint implementado aqui).

    Monitor

    Processo: 
    1. DESCRIÇÃO DO FLUXO

    - Responsabilidade: capturar registros de cliente por chave e enfileirar para integração assíncrona no Protheus.
    - Disparo: operação manual via Monitor::capturar(chave).

    Para cada chave recebida, o processo executa:
    - Normaliza a entrada para lista de chaves (suporta chave única ou array).
    - Reaproveita token existente do item de fila, consultando Queue::get('', chaveOriginal) quando houver registro.
    - Valida formato da chave e deriva filtros (A1_LOJA e A1_COD).
    - Executa consulta na fonte de 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 posição (novoFiltro) com a chave do cliente e a DATA_PARA_TRANSFERENCIA normalizada.
    - Monta a chave da fila no formato A1_LOJA-A1_COD e grava o item para processamento assíncrono com status Aguardando Integração.


    2. DADOS NECESSÁRIOS PARA O ENDPOINT

    Este arquivo não implementa endpoint (WebService). Para o Monitor, o dado necessário para execução manual é a chave do cliente.

    Entrada do processo:
    - Parâmetro chave: string ou array.
    - Formato obrigatório: A1_LOJA-A1_COD.
    - Regra: a chave precisa conter exatamente 2 segmentos (separados por -).

    Fonte de 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: Início do capturar()
    - Constrói a lista de execução (chaves) a partir do parâmetro chave.
    - Recupera token prévio do item de fila (quando existir), garantindo rastreabilidade na regravação do item.

    3.2 Reset ao iniciar execução
    Momento: Início do loop de chaves
    - Para cada chave, prepara variáveis de contexto (chave atual, token associado e filtros derivados).

    3.3 Normalização dos filtros
    Momento: Pré-consulta (por chave)
    - Divide a 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: Antes do enfileiramento
    - O item é gravado com status textual Aguardando Integração e situação inicial 0, estabelecendo o ponto de partida do processamento assíncrono.

    3.5 Paginação dos registros
    Momento: Execução da consulta
    - A consulta é executada por chave; o processamento percorre as linhas retornadas via fetch().

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

    3.7 Atualização do filtro de posição
    Momento: Após ler o registro
    - Define novoFiltro com:
        - A1_LOJA
        - A1_COD
        - DATA_PARA_TRANSFERENCIA normalizada em Y-m-d H:i:s

    3.8 Enfileiramento
    Momento: Pós-sanitização (por registro)
    - Monta a chave: A1_LOJA-A1_COD.
    - Enfileira via Queue::set(chave, registro, [], 'Aguardando Integração', ...).
    - Quando houver token prévio, ele é reaproveitado na gravação do item.

    3.9 Atualização incremental da posição
    Momento: Após inserir na fila
    - O controle incremental deste fluxo manual fica registrado no próprio item de fila, via chave e data_adicionado do item gravado/atualizado.

    3.10 Finalização
    Momento: Conclusão do processamento de todas as chaves
    - Encerramento do lote após enfileirar todos os registros encontrados para as chaves informadas.

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


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

    4.1 Controle do monitor
    Momento: Persistência de estado do monitor (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: {$this->bancoIntegrador}.wosk_queue.


    5. RESULTADO DO PROCESSAMENTO

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

    Execução com erro:
    - Exceção registrada e o lote pode encerrar antes de enfileirar todos os registros planejados.


    6. OPERAÇÃO MANUAL – capturar()

    Objetivo: enfileirar manualmente um ou mais clientes a partir da chave.

    Fluxo:
    - Entrada: chave string ou array, no padrão A1_LOJA-A1_COD.
    - Para cada chave:
        - Reaproveita token do item quando existir na fila.
        - Consulta o registro correspondente na fonte WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_PADRAO.
        - Sanitiza o registro e enfileira para integração com status Aguardando Integração.

    Queue

    Processo:
    1. DESCRIÇÃO DO FLUXO

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

    Ao iniciar, a fila busca um item via get(token). Se houver registro:
    - Atualiza o item para status Enviando e situacao = 1 antes do envio.
    - Converte o conteudo persistido em payload de integração via getConteudo(), aplicando o mapeamento de campos definido em $field.

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

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

    Validação e classificação do retorno:
    - Se a resposta vier vazia, o processamento gera erro de integração (JSON: NÃO HOUVE RESPOSTA.).
    - Se a resposta não puder ser interpretada como array ou não contiver Mensagem, o processamento gera erro de decodificação.
    - A mensagem persistida prioriza Mensagem Detalhada quando existir.
    - A situacao final é definida por:
        - 2 quando sucesso.
        - 4 quando houver erro (por code no retorno ou Mensagem = "ERRO").

    Ações pós-sucesso:
    - Marca o cliente como integrado via setProtheusClienteIntegrado(chave, true).
    - Remove itens correlatos de fila para evitar duplicidade, executando exclusões em wosk_queue para as ações ProtheusCliente e ProtheusClienteFull (chaves derivadas da chave original).

    Persistência do resultado do item:
    - Atualiza o próprio item de fila com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação 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 de notificação interno (_getNotificarErros).


    2. DADOS NECESSÁRIOS PARA O ENDPOINT

    Este arquivo não implementa endpoint (WebService). Para a Queue, os dados de 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 do cliente, conforme viewQuery do monitor.
    - 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.

    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ção por item (consumo unitário).

    3.6 Sanitização dos dados
    Momento: Pré-envio ao Protheus
    - Remove acentos e caractere | 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-processamento do item
    - O item permanece rastreável pela chave e pelo token, com retorno e situação persistidos na fila.

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

    3.9 Atualização incremental da posição
    Momento: Atualização do item
    - A posição do processamento é refletida na própria fila por status e situação (1 durante envio; 2 ou 4 ao concluir).

    3.10 Finalização
    Momento: Pós-resposta do Protheus
    - Define situacao final e atualiza o item com retorno, mensagem, dump e tempo.

    3.11 Tratamento de erro
    Momento: catch(Exception) interno
    - Registra 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: Persistência do estado do monitor (quando utilizado pela integração)
    - Tabela: {$this->bancoIntegrador}.wosk_monitor.

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


    5. RESULTADO DO PROCESSAMENTO

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

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


    6. OPERAÇÃO MANUAL – capturar()

    Operação manual está definida no Monitor deste arquivo, com enfileiramento do item para consumo pela Queue.

    Fluxo do Processo

    Diagrama sem nome.jpg

    Critérios de Aceitação

    Processo Subprocesso Descrição Situação esperada






    Voltar ao topo