ProtheusClienteFull (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	Osklen
Nome do projeto	Integração Linx → Protheus (WOSK)
Biblioteca	wosk_protheus_cliente_full
Token da Biblioteca	d1444b58-fc25-4211-845d-a12be3cc09b7
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/d1444b58-fc25-4211-845d-a12be3cc09b7/wosk_protheus_cliente_full
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/d1444b58-fc25-4211-845d-a12be3cc09b7/wosk_protheus_cliente_full
Data	24/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
24/02/2026	1.0	Gerado automaticamente	Documentação inicial

Descrição Geral dos Processos

Esta biblioteca documenta o fluxo de integração de Clientes (Full) para o Protheus. Ela separa o trabalho em duas etapas: uma etapa de captura (Monitor) e outra de processamento assíncrono (Queue).

Na prática, o Monitor localiza os dados do cliente em uma visão de serviço e cria (ou atualiza) um item na fila para integração. Depois, a Queue consome esse item, prepara o payload final e realiza o envio para o Protheus, registrando o resultado para auditoria e acompanhamento.

O objetivo do fluxo é garantir que o envio ocorra de forma controlada, com rastreabilidade de erros e possibilidade de reprocessamento, sem depender de uma execução única e sincrona.

Monitor

Conceito: Monitor

Processo: 
Classe: WOSK\ProtheusClienteFull\Monitor
Entrada: chave no formato A1_LOJA-A1_COD (ex.: 01SD0001-000123) ou lista de chaves.
Origem dos dados: consulta na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL com WHERE construído dinamicamente a partir da chave.

Query base (sem filtro):

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_FULL

WHERE dinâmico aplicado por chave:

WHERE
    A1_LOJA = '{A1_LOJA}'
    AND A1_COD = '{A1_COD}'

Reestruturações e transformações (pré-insert na fila):
- Todos os campos do registro retornado sofrem trim() (não tratado como alteração relevante).
- O campo DATA_PARA_TRANSFERENCIA é convertido/normalizado para Y-m-d H:i:s e usado como data de captura do item na fila.
- Destaque (conceito cronológico): ao normalizar e usar DATA_PARA_TRANSFERENCIA para ordenar/capturar, o fluxo passa a depender de data/hora como controle de processamento. Referência: Cronológico.

Persistência:
- O Monitor insere/atualiza o item na fila pela Queue (tabela wosk_queue) usando:

• acao: ProtheusClienteFull
• chave: {A1_LOJA}-{A1_COD}
• conteudo: o registro bruto retornado pela view (inclui CGC_CPF, NOME, ENDERECO, etc.)
• data_adicionado: DATA_PARA_TRANSFERENCIA normalizada
• situacao: 0 (Aguardando integração)

- A tabela wosk_monitor é a persistência padrão de posição/controle do Monitor (via Monitor::set()), quando utilizada pelo agendamento/execução do monitor.

 

Queue

Conceito: Queue

Processo:
Classe: WOSK\ProtheusClienteFull\Queue
Entrada (obrigatória): token do item na fila (Queue::run(string $token)).

0) Preparação do processamento (acionada por cron/worker):
Antes de executar run(token) para cada item, o processo pode chamar Queue::prepare(), que delega para _prepare("ProtheusClienteFull"). Essa etapa seleciona tokens pendentes (situacao = 0) e dispara a execução respeitando limites de paralelismo e atraso configurável.

Query de seleção da fila (com WHERE dinâmico por atraso):

SELECT /*+ SQL_BIG_RESULT */ /*+ SQL_NO_CACHE */ `token`
FROM `{$this->bancoIntegrador}`.`wosk_queue`
WHERE `acao` = 'ProtheusClienteFull'
  AND `situacao` = 0
  {AND `data` <= '{agora - delay em minutos}'}
ORDER BY `data_adicionado` ASC

Destaque (conceito cronológico): quando o delay está ativo, a seleção filtra por data/hora (data), controlando quando um item pode ser processado. Referência: Cronológico.

1) Seleção do item e marcação de estado (pré-envio):
- Lê o item em wosk_queue pelo token.
- Atualiza o mesmo item para “Enviando” com situacao = 1 (início do processamento).

2) Reestruturação do conteúdo (mapeamento de campos):
O conteúdo capturado pelo Monitor vem com nomes como CGC_CPF, NOME, ENDERECO, etc. Antes do envio, a Queue converte isso para o layout esperado no Protheus, produzindo chaves A1_*. Exemplos de mapeamento:

• CGC_CPF → A1_CGC
• NOME → A1_NOME
• NOME_REDUZ → A1_NREDUZ
• ENDERECO → A1_END
• COD_PAIS_BC → A1_CODPAIS
• STATUS → A1_MSBLQL

3) Transformações de dados (pré-envio ao Protheus):
- A1_NOME e A1_NREDUZ: remoção de acentos e do caractere |.
- A1_END, A1_BAIRRO, A1_CONTATO: remoção de acentos.
- A1_CODPAIS: convertido para numérico e preenchido à esquerda com zeros até 5 dígitos (str_pad).

4) Envio ao Protheus:
- Chamada de integração via setProtheus("cliente", payload, "POST", headers).
- Header utilizado no envio:

tenantId: "01,01SD0001"

- Resposta esperada: array com Mensagem e opcionalmente Mensagem Detalhada.

5) Decisão de situação (pós-envio):
- Sucesso: situacao = 2 (quando não há code e Mensagem != "ERRO").
- Erro: situacao = 4 (quando Mensagem == "ERRO" ou quando existe code na resposta, ou exceção no processamento).

6) Ações e persistências (por situação):

• Quando sucesso (situacao = 2): chama setProtheusClienteIntegrado(chave, true). Além de atualizar o status do item, o fluxo padrão registra auditoria de integração em OSK_LOG_INTEGRACAO_PROTHEUS.
• Quando erro (situacao = 4): tenta capturar o mesmo cliente no processo ProtheusClientePadrao (Monitor correspondente) e verifica se um item foi criado em wosk_queue. Se o item do ProtheusClientePadrao existir, esta fila pode marcar o item atual para remoção e chamar setProtheusExcluir(["ProtheusClienteFull"], "chave", chave).
• Atualização final do item: quando não for removido, atualiza wosk_queue com retorno, mensagem, dump de requisição e tempo total.

Regra de deduplicação (pré-insert na fila):
Ao inserir itens com situacao = 0, o mecanismo padrão da Queue compara o conteudo com o que já existe para a mesma acao e chave. Se o conteúdo for igual, a inserção pode ser ignorada. O campo DATA_PARA_TRANSFERENCIA é desconsiderado nessa comparação, evitando reprocessos apenas por variação de data/hora.

Tabelas envolvidas (persistência e auditoria):

• wosk_queue: fila principal do processo (acao = ProtheusClienteFull)
• wosk_queue_log: log de falhas de SQL durante escrita de auditoria
• OSK_LOG_INTEGRACAO_PROTHEUS: auditoria de integração para ações que casam com /Protheus/

Notificação de erros (consolidação via query):
A rotina Queue::notificar() consulta os erros deste processo diretamente na tabela wosk_queue e envia e-mail para destinatários configurados.

SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem` AS 'ERRO'
FROM `{$this->bancoIntegrador}`.`wosk_queue`
WHERE `acao` = 'ProtheusClienteFull'
  AND `situacao` = 4
ORDER BY `data` ASC

 

Fluxo do Processo

Encadeamento obrigatório: Monitor → Queue.

1. Monitor (cron/on-demand): recebe a chave A1_LOJA-A1_COD, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL e grava/atualiza o item na tabela wosk_queue com situacao = 0.
2. Queue (cron/worker): seleciona itens pendentes (situacao = 0), marca como em envio (situacao = 1), monta payload A1_*, envia para o Protheus e grava o resultado (situacao = 2 ou 4).
3. Notificação: erros (situacao = 4) podem ser consolidados e enviados por e-mail via Queue::notificar().
4. Fallback: em erro, pode acionar captura do mesmo cliente em ProtheusClientePadrao e remover o item desta fila quando aplicável.

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Monitor	Captura por chave	Ao informar A1_LOJA-A1_COD, o Monitor deve montar o WHERE dinamicamente e consultar a view de serviço.	Registro encontrado → item criado/atualizado em wosk_queue com situacao = 0.
Queue	Envio ao Protheus	O worker deve mapear dados para A1_*, aplicar normalizações e executar POST no serviço de cliente.	Resposta OK → situacao = 2 e auditoria registrada.
Queue	Tratamento de erro	Quando houver falha de integração, o item deve permanecer rastreável e elegível para notificação.	situacao = 4, mensagem registrada e opção de fallback para ProtheusClientePadrao.
Notificação	Consolidação	Listar erros pendentes do processo e enviar e-mail aos destinatários configurados.	Relatório enviado com chave, datas e mensagem de erro normalizada.