ProtheusClienteFull

Documentação Técnica

Nome do cliente	EXEMPLO: TERRAS DE AVENTURA INDUSTRIA DE ARTIGOS ESPORTIVOS SA
Nome do projeto	EXEMPLO: IMPLANTAÇÃO PROTHEUS
Biblioteca	EXEMPLO: wosk_loja_cliente
Token da Biblioteca	EXEMPLO: 1be199d8-98e8-4de7-a92c-e59c2f08edd6
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/ba4e7bb5-4770-4780-beaa-b28980153cc7/wosk/webservice/callback_protheus
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/ba4e7bb5-4770-4780-beaa-b28980153cc7/wosk/webservice/callback_protheus
Data	EXEMPLO: 01/11/2024

Sumário

Documentação Técnica
Sumário
Histórico de Versões
Descrição Geral dos Processos
- Monitor
- Queue
- WebService
Fluxo do Processo
Critérios de Aceitação

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
01/01/9999	1.0	Maykon

Descrição Geral dos Processos

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum

Monitor

1. DESCRIÇÃO DO FLUXO

O Monitor ProtheusClienteFull é responsável exclusivamente pela captura incremental de registros da view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL e pelo encaminhamento estruturado desses registros para a fila de integração (Queue).

O processo é acionado por agendamento (cron) através do método run(). Sua responsabilidade é:

- Recuperar o estado anterior de execução.
- Controlar continuidade incremental (offset e chave de posição).
- Evitar reprocessamento indevido.
- Garantir ordenação cronológica por DATA_PARA_TRANSFERENCIA.
- Persistir o controle transacional do processamento.
- Encaminhar registros válidos para a Queue.

Fluxo de execução:

1. Recupera o estado atual do monitor na base de controle.
2. Avalia a situação armazenada:
  - Se CONCLUÍDO (2) → redefine para PARADO (0).
  - Se PARADO (0) → reinicia execução.
  - Se EXECUTANDO (1) → continua do ponto persistido.
3. Caso iniciado do zero:
  - Offset é redefinido.
  - Chave de posição é limpa.
  - Data de posição é reiniciada.
4. Normaliza filtros internos.
5. Atualiza situação para EXECUTANDO (1).
6. Executa consulta paginada na view.
7. Para cada registro retornado:
  - Sanitiza dados.
  - Atualiza filtro incremental.
  - Enfileira o registro na Queue.
  - Atualiza offset e posição no controle.
8. Quando não houver mais registros:
  - Atualiza situação para CONCLUÍDO (2).
9. Em caso de erro:
  - Atualiza situação para PROBLEMA (4).
  - Registra erro no filtro persistido.

O Monitor não realiza integrações externas nem transformações finais de payload. Sua responsabilidade termina no momento do enfileiramento.

1. DADOS NECESSÁRIOS PARA O ENDPOINT

O Monitor não expõe endpoint externo. Ele opera sobre a view:

WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL

Campos capturados:

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

Campos obrigatórios para captura incremental:

A1_LOJA
A1_COD
DATA_PARA_TRANSFERENCIA

Esses campos compõem a chave lógica e o controle cronológico da captura.

1. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Início do run()

Dados recuperados da tabela de controle:

offset
chavePosicao
dataPosicao
filtro
situacao
dataIniciado
token

Regra:
Se situacao = 2 (CONCLUÍDO) → redefinir para 0 (PARADO).

3.2 Reset ao iniciar execução
Momento: Quando situacao ≠ 1

Ações executadas:

offset ← 0
chavePosicao ← ''
dataPosicao ← Data/hora atual
dataIniciado ← Data/hora atual

3.3 Normalização dos filtros
Momento: Pré-consulta

Regra:

Se DATA_PARA_TRANSFERENCIA não estiver definida no filtro:
DATA_PARA_TRANSFERENCIA ← data mínima configurada no sistema.

Conversão obrigatória:
DATA_PARA_TRANSFERENCIA → formato DateTime padrão do sistema.

3.4 Atualização do estado para EXECUTANDO
Momento: Pré-query

situacao ← 1
Persistência imediata no controle do monitor.

3.5 Paginação dos registros
Momento: Execução da consulta

Critérios:

ORDER BY DATA_PARA_TRANSFERENCIA ASC

Controle:

OFFSET = offset persistido
Limite = configuração interna do monitor

3.6 Sanitização dos dados
Momento: Pós-fetch (antes do enfileiramento)

Transformações aplicadas:

trim() em todos os campos string.
Remoção de espaços laterais.
Padronização de datas via setDateTime() quando aplicável.

Não há alteração estrutural de nomes de campos.
Não há transformação de layout.

3.7 Atualização do filtro de posição
Momento: Após leitura do registro

novoFiltro:

A1_LOJA ← registro atual
A1_COD ← registro atual
DATA_PARA_TRANSFERENCIA ← registro atual formatado para Y-m-d H:i:s

3.8 Enfileiramento
Momento: Dentro do loop de paginação

Chave composta:

chave = A1_LOJA + '-' + A1_COD

Operação:

Queue::set(
chave,
payload completo,
[],
'Aguardando Integração',
'',
0,
0,
dataReferencia,
token
)

Se falhar:
Lança exceção.

3.9 Atualização incremental da posição
Momento: Pós-insert na fila

offset ← offset + 1
chavePosicao ← chave composta
dataPosicao ← DATA_PARA_TRANSFERENCIA

Persistência imediata no controle.

3.10 Finalização
Momento: Quando não houver mais registros

situacao ← 2 (CONCLUÍDO)
Persistência do estado final.

3.11 Tratamento de erro
Momento: catch(Exception)

situacao ← 4 (PROBLEMA)
Registro da mensagem de erro no filtro.
Persistência do estado com erro.

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

4.1 Controle do monitor

Identificação lógica do processo:
ProtheusClienteFull

Tabela de persistência de controle:
wosk_monitor

Campos persistidos:

processo
offset
chave_posicao
data_posicao
filtro (JSON)
situacao
data_iniciado
token

Situações:

0 → Parado
1 → Executando
2 → Concluído
4 → Problema

4.2 Fila de integração

Tabela:
wosk_queue

Operações realizadas:

INSERT ou UPDATE

Campos persistidos:

chave
payload (JSON completo do registro)
status = 'Aguardando Integração'
situacao = 0
data_referencia = DATA_PARA_TRANSFERENCIA
token (quando reaproveitado)

Não há transformação estrutural no payload nesta etapa.

1. RESULTADO DO PROCESSAMENTO

Execução normal:

- Todos os registros elegíveis são enfileirados.
- Offset e posição são atualizados incrementalmente.
- Monitor finaliza como CONCLUÍDO (2).
- Rastreamento garantido via wosk_monitor.

Execução com erro:

- Monitor finaliza como PROBLEMA (4).
- Última posição permanece persistida.
- Permite retomada controlada em nova execução.

1. OPERAÇÃO MANUAL – capturar()

Método: capturar($chave)

Finalidade:

Permitir reprocessamento pontual de registros específicos.

Entrada:

chave no formato:
A1_LOJA-A1_COD

Fluxo:

1. Valida formato da chave.
2. Consulta diretamente a view com filtro:
  A1_LOJA
  A1_COD
3. Sanitiza os dados (trim).
4. Converte DATA_PARA_TRANSFERENCIA via setDateTime().
5. Monta chave composta.
6. Verifica token existente na fila.
7. Executa Queue::set().
8. Em caso de falha → gera exceção e registra erro.

Responsabilidade:

Não altera estado global do monitor.
Realiza apenas inserção pontual na fila.

Queue

1. DESCRIÇÃO DO FLUXO

A Queue ProtheusClienteFull é responsável exclusivamente pelo processamento assíncrono dos registros previamente enfileirados pelo Monitor, realizando:

- Transformação estrutural dos dados.
- Normalização final para layout Protheus.
- Envio via integração HTTP.
- Controle de status.
- Tratamento de erro.
- Registro de auditoria.
- Notificação de falhas.

A Queue é acionada por cron através do método run().

Fluxo de execução:

1. Recupera o próximo registro pendente da fila (situacao = 0).
2. Atualiza o status para "Enviando" (situacao = 1).
3. Realiza transformação e normalização do payload.
4. Executa envio via setProtheus().
5. Interpreta retorno da API.
6. Atualiza situação para:
  - 2 (Sucesso)
  - 4 (Erro)
7. Registra tempo de execução e resposta completa.
8. Em caso de erro, pode acionar nova captura via outro monitor.
9. Persiste auditoria final na tabela de fila.

A Queue não consulta view nem controla offset. Sua responsabilidade inicia exclusivamente no momento da leitura da fila.

1. DADOS NECESSÁRIOS PARA O ENDPOINT

A Queue não expõe endpoint externo.

Ela consome registros persistidos na tabela:

wosk_queue

Campos obrigatórios no payload (conteudo):

A1_COD
A1_LOJA
A1_CGC (CGC_CPF)
A1_NOME
A1_PESSOA
A1_NREDUZ
A1_END
A1_BAIRRO
A1_COMPLEM
A1_TIPO
A1_EST
A1_COD_MUN
A1_CEP
A1_DDI
A1_DDD
A1_TEL
A1_CONTATO
A1_PFISICA
A1_INSCR
A1_INSCRM
A1_DTNASC
A1_EMAIL
A1_PAIS
A1_CODPAIS
A1_CONTA
A1_CONTRIB
A1_TPESSOA
A1_SUFRAMA
A1_CALCSUF
A1_CODMUN
A1_MSBLQL

Campos críticos obrigatórios para envio:

A1_COD
A1_LOJA
A1_NOME
A1_CODPAIS

1. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do estado do monitor
Momento: Início do run()

Operação:

Busca na tabela wosk_queue:

acao = 'ProtheusClienteFull'
situacao = 0

Limite configurável (default 10).

3.2 Reset ao iniciar execução
Momento: Pré-envio

Atualiza registro:

status ← 'Enviando'
situacao ← 1

Persistência imediata na tabela wosk_queue.

3.3 Normalização dos filtros
Momento: Pré-transformação

Operação:

getConteudo() → reorganiza payload conforme mapeamento interno $field.

Mapeamento estrutural:

Campos de origem → Campos Protheus

Exemplo:
A1_CGC ← CGC_CPF
A1_NOME ← NOME
A1_NREDUZ ← NOME_REDUZ
A1_END ← ENDERECO

Campos não mapeados explicitamente mantêm mesmo nome.

3.4 Atualização do estado para EXECUTANDO
Momento: Já definido no item 3.2 (situacao = 1).

3.5 Paginação dos registros
Momento: Seleção via get()

Limite padrão: 10 registros por execução.

3.6 Sanitização dos dados
Momento: Pré-envio HTTP

Transformações aplicadas:

A1_NOME:

- Remoção de acentos.
- Remoção de caractere '|'.

A1_NREDUZ:

- Remoção de acentos.
- Remoção de '|'.

A1_END:

- Remoção de acentos.

A1_BAIRRO:

- Remoção de acentos.

A1_CONTATO:

- Remoção de acentos.

A1_CODPAIS:

- Conversão para inteiro.
- Preenchimento com zeros à esquerda.
- Tamanho fixo de 5 posições.

Não há alteração de estrutura JSON.

3.7 Atualização do filtro de posição
Não aplicável à Queue (controle é feito via token e situacao).

3.8 Enfileiramento
Não aplicável nesta etapa (já realizado pelo Monitor).

3.9 Atualização incremental da posição
Não aplicável.

3.10 Finalização
Momento: Pós-resposta da API

Interpretação do retorno:

Se resposta vazia:
situacao ← 4

Se não for array válido:
situacao ← 4

Se Mensagem = "ERRO":
situacao ← 4

Se code existir:
situacao ← 4

Caso contrário:
situacao ← 2

Em sucesso (situacao = 2):

Executa:
setProtheusClienteIntegrado(chave, true)

Persistência final:

wosk_queue:
retorno (JSON resposta)
mensagem
tempo_execucao
situacao
data_processado

3.11 Tratamento de erro
Momento: catch(Exception)

Ações:

situacao ← 4
mensagem ← erro capturado
retorno ← JSON com erro

Persistência:

Atualiza wosk_queue com erro completo.

Regra adicional:

Se erro (situacao = 4):

1. Aciona Monitor ProtheusClientePadrao via capturar().
2. Verifica se novo token foi gerado.
3. Se houver novo token:
  Executa setProtheusExcluir(['ProtheusClienteFull'], "chave", chave).

Objetivo:
Evitar duplicidade entre integrações Full e Padrão.

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

4.1 Controle do monitor
Não aplicável à Queue.

4.2 Fila de integração

Tabela:

wosk_queue

Campos atualizados:

acao = 'ProtheusClienteFull'
chave
conteudo (JSON original)
retorno (JSON resposta API)
mensagem
requisicao (dump HTTP)
tempo_execucao
situacao
data_adicionado
data (processado em)
token

Situações:

0 → Aguardando
1 → Enviando
2 → Integrado com sucesso
4 → Erro

1. RESULTADO DO PROCESSAMENTO

Execução com sucesso:

- Registro atualizado para situacao = 2.
- Payload enviado ao Protheus.
- Registro marcado como integrado.
- Tempo de execução registrado.
- Auditoria completa armazenada.

Execução com erro:

- Registro atualizado para situacao = 4.
- Mensagem de erro persistida.
- Dump da requisição armazenado.
- Pode disparar integração alternativa.
- Registro permanece disponível para notificação.

1. OPERAÇÃO MANUAL – capturar()

Não aplicável à Queue.

A Queue não realiza captura manual de registros.
Sua responsabilidade limita-se ao processamento dos itens já existentes na fila.

Funcionalidade complementar:

notificar()

Objetivo:

Enviar e-mail com resumo de erros (situacao = 4).

Consulta:

SELECT em wosk_queue
acao = 'ProtheusClienteFull'
situacao = 4

Transformações na notificação:

- Extração de A1_LOJA e A1_COD da chave.
- Limpeza de mensagens SQL Server.
- Remoção de prefixos técnicos.
- Normalização de quebras de linha.
- Formatação de datas (d/m/Y H:i:s).

Destinatários fixos configurados internamente.

Assunto:

"Erros na Integração do LINX para o PROTHEUS - Cliente - Full"

Finalidade:

Garantir visibilidade operacional e rastreabilidade de falhas.

WebService

~~Processo:~~
is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum

Método: POST para Registro Recebido

Chave Primária: FILIAL, ID

Observação: O campo ID será único por FILIAL.

CAMPO	TIPO	TAMANHO	CONTEÚDO	OBRIGATÓRIO
key	C	36	Chave da API Key para autenticação	sim

Exemplos de Request:

{
    "key": "34a20688-1bb6-4fcd-9592-d58ca9876de5",
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0206",
    "ID": "00000007188082",
    "DATA_RETORNO": "2024-10-29 00:37:05",
    "SITUACAO": "1",
    "MENSAGEM": "GravaBatch Executado com Sucesso",
    "DETALHE": {
        "ZB_ID": "000000000004156",
        "LQ_DOC": "000051206",
        "LQ_PDV": "003",
        "ERGRVBT": "",
        "LQ_HORA": "20:41:19",
        "LQ_LOJA": "68",
        "LQ_VEND": "000001",
        "SITUAGB": "OK",
        "LQ_FORMA": "R$",
        "LQ_FRETE": 0,
        "LQ_SERIE": "65",
        "LQ_SITUA": "RX",
        "Mensagem": "OK",
        "LQ_CARTAO": 752.14,
        "LQ_CONDPG": "",
        "LQ_EMISNF": "27/07/2025",
        "LQ_FILIAL": "01LJ0299",
        "LQ_FORMPG": "CC",
        "LQ_NOMCLI": "XXXXXX",
        "LQ_OUTROS": 139.65,
        "LQ_SERSAT": "",
        "LQ_TPFRET": "S",
        "LQ_VALICM": 178.35,
        "LQ_VLRLIQ": 891.79,
        "LQ_VLRTOT": 891.79,
        "LQ_XCANAL": "VAREJO",
        "ZB_DATRET": "29/07/25",
        "ZB_FILIAL": "01LJ0299",
        "ZB_HORRET": "09:18:00",
        "LQ_CLIENTE": "XXXXX",
        "LQ_DINHEIR": 0,
        "LQ_EMISSAO": "27/07/2025",
        "LQ_ESPECIE": "NFCE",
        "LQ_KEYNFCE": "XXXXX",
        "LQ_NUMCFIS": "000051206",
        "LQ_OPERADO": "C24",
        "LQ_PARCELA": 0,
        "LQ_TIPOCLI": "F",
        "LQ_VALBRUT": 891.79,
        "LQ_VALMERC": 1044,
        "LQ_VENDTEF": "S",
        "LQ_VLRDEBI": 0,
        "LQ_XNATOPE": "100.80",
        "Mensagem Detalhada": "GravaBatch Executado com Sucesso"
    }
}

{
    "key": "34a20688-1bb6-4fcd-9592-d58ca9876de5",
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "MENSAGEM": "D2_TES: Tipo Operacao '', do Item '0001', Invalido."
}

Exemplos de Response:

{
    "INTEGRADOR": "cupom",
    "FILIAL": "01LJ0269",
    "ID": "00000001352422",
    "DATA_RETORNO": "2024-10-29 11:23:20",
    "SITUACAO": "0",
    "Mensagem Detalhada": "Registrado com sucesso.",
    "Mensagem": "OK"
}

{
    "success":false,
    "message":"Sess\u00e3o Expirou",
    "data":false,
    "errors":{"reason":"Sess\u00e3o Expirou"}
}

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada