ProtheusCliente

Documentação Técnica

Nome do cliente	TO-DO
Nome do projeto	TO-DO
Biblioteca	wosk_loja_cliente
Token da Biblioteca	1be199d8-98e8-4de7-a92c-e59c2f08edd6
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/1be199d8-98e8-4de7-a92c-e59c2f08edd6/wosk_loja_cliente
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/1be199d8-98e8-4de7-a92c-e59c2f08edd6/wosk_loja_cliente
Data	?

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
?	1.0	Maykon/Gustavo	Documentação inicial

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

Processo:
~~1. DESCRIÇÃO DO FLUXO~~
O Monitor (classe WOSK\\ProtheusCliente\\Monitor) é acionado por cron e captura periodicamente registros da origem WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES, controlando continuidade por estado persistido (evento, offset, chave_posicao, data_posicao, filtro, situação e token).
Se a situação estiver CONCLUÍDO (2), o Monitor redefine para PARADO (0) e inicia um novo ciclo. Se estiver PARADO (0) ou EXECUTANDO (1), normaliza os filtros e executa leituras paginadas ordenadas por DATA_PARA_TRANSFERENCIA. Para cada registro, sanitiza os valores (trim), monta uma chave de integração e grava um item na fila para processamento assíncrono. A cada item enfileirado, atualiza incrementalmente o estado do Monitor. Ao final, marca o estado como CONCLUÍDO (2). Em qualquer exceção, registra o erro em filtro[ERRORS] e marca o estado como PROBLEMA (4).

~~2. DADOS NECESSÁRIOS PARA O ENDPOINT~~
~~NÃO APLICÁVEL: esta classe Monitor não expõe endpoint e não recebe parâmetros de requisição HTTP. Ela é executada por cron e depende de configuração/estado interno.~~
~~Configuração obrigatória: woskLimiteCaptura::ProtheusCliente (inteiro) – define o tamanho do lote (top) no FETCH NEXT.~~
~~Estado obrigatório (persistido): token, evento (ProtheusCliente), offset, filtro (JSON), chave_posicao, situacao, data_posicao, data_iniciado, data.~~
~~Filtros utilizados (persistidos em filtro): A1_LOJA (opcional), A1_COD (opcional), CGC_CPF (opcional), DATA_PARA_TRANSFERENCIA (opcional; padrão 2023-05-01 00:00:00).~~

~~3. REESTRUTURAÇÃO DOS DADOS~~
~~3.1 Recuperação do estado do monitor~~
~~Recupera o estado anterior via get("ProtheusCliente"), obtendo data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situacao (0=PARADO, 1=EXECUTANDO, 2=CONCLUÍDO, 4=PROBLEMA).~~
~~3.2 Reset ao iniciar execução~~
Regra aplicada antes da captura: se situacao === 2, redefine para 0 via set(..., situacao=0, ...). Se situacao != 1 (não está em execução), reinicia data_posicao e data_iniciado (DateTime atual), offset=0 e chave_posicao="".
~~3.3 Normalização dos filtros~~
Regra aplicada antes da consulta: A1_LOJA/A1_COD/CGC_CPF viram string vazia quando não informados. DATA_PARA_TRANSFERENCIA vira DateTime e é formatada em "Y-m-d H:i:s"; se ausente, assume 2023-05-01 00:00:00.
~~3.4 Atualização do estado para EXECUTANDO~~
~~Regra aplicada antes de cada busca: persiste situacao=1 via set(offset, chave_posicao, data_posicao, filtro, 1, data_iniciado, token).~~
~~3.5 Paginação dos registros~~
Consulta executada na origem WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES: WHERE DATA_PARA_TRANSFERENCIA >= '{filtro[DATA_PARA_TRANSFERENCIA]}' ORDER BY DATA_PARA_TRANSFERENCIA ASC OFFSET {offset} ROWS FETCH NEXT {top} ROWS ONLY.
~~3.6 Sanitização dos dados~~
~~Regra aplicada por registro: array_walk_recursive com trim em todos os valores do array retornado pelo fetch.~~
~~3.7 Atualização do filtro de posição~~
Regra aplicada por registro: novoFiltro recebe A1_LOJA, A1_COD, CGC_CPF e DATA_PARA_TRANSFERENCIA do registro atual; DATA_PARA_TRANSFERENCIA é convertida por setDateTime() e formatada em "Y-m-d H:i:s".
~~3.8 Enfileiramento~~
Regra aplicada por registro: monta key = A1_LOJA . '-' . A1_COD . '-' . CGC_CPF e chama Queue::set(key, conteudo=r, retorno=[], mensagem="Aguardando Integração", requisicao="", tempo=0, situacao=0, data_adicionado=DATA_PARA_TRANSFERENCIA). Se o retorno for falso, lança exceção.
~~3.9 Atualização incremental da posição~~
~~Regra aplicada após enfileirar: incrementa offset, atualiza chave_posicao=key e data_posicao=DATA_PARA_TRANSFERENCIA e persiste novamente situacao=1.~~
~~3.10 Finalização~~
~~Ao finalizar o loop do lote, persiste situacao=2 (CONCLUÍDO) e grava o novoFiltro como filtro do estado final.~~
~~3.11 Tratamento de erro~~
~~Se ocorrer exceção: registra em filtro[ERRORS][] um item {DATE, MESSAGE} e persiste situacao=4 (PROBLEMA) com o filtro atualizado.~~

~~4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)~~
~~4.1 Controle do monitor~~
~~Tabela: {$this->bancoIntegrador}.wosk_monitor.~~
Persistência feita via trait WOSK\\Commons\\Monitor (dbSet("wosk_monitor", ...)) com o evento "ProtheusCliente" e campos: token, evento, offset, filtro (JSON), chave_posicao, situacao, data_posicao, data_iniciado (e data).
~~4.2 Fila de integração~~
~~Tabela: {$this->bancoIntegrador}.wosk_queue.~~
Persistência feita via trait WOSK\\Commons\\Queue (dbSet("wosk_queue", ...)) com acao "ProtheusCliente" e chave "A1_LOJA-A1_COD-CGC_CPF". O conteudo do item é o registro sanitizado capturado da origem, e o status inicial é gravado com mensagem "Aguardando Integração".

~~5. RESULTADO DO PROCESSAMENTO~~
Quando bem-sucedido: itens inseridos em wosk_queue para processamento assíncrono e estado atualizado em wosk_monitor finalizando com situacao=2 (CONCLUÍDO) e filtro apontando para o último DATA_PARA_TRANSFERENCIA processado.
Quando falha: estado persistido em wosk_monitor com situacao=4 (PROBLEMA) e filtro contendo ERRORS com data e mensagem da exceção; o offset/chave/data refletem o último item efetivamente enfileirado antes do erro.

~~6. OPERAÇÃO MANUAL – capturar()~~
~~Uso: capturar($chave) aceita uma chave (string) ou uma lista de chaves (array).~~
~~Formato da chave: A1_LOJA-A1_COD (2 partes) ou A1_LOJA-A1_COD-CGC_CPF (3 partes; split limitado a 3).~~
Fluxo: para cada chave, consulta o item atual na fila para recuperar token; executa SELECT na origem WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES filtrando por A1_LOJA, A1_COD e opcionalmente CGC_CPF; sanitiza os valores (trim); monta key e insere/atualiza na tabela wosk_queue via Queue::set, preservando o token quando existente. Chaves com menos de 2 ou mais de 3 partes geram exceção e são registradas via errorByexception.PROCESSO_MONITOR

Queue

Processo:
PROCESSO_QUEUE

WebService

Processo:
PROCESSO_WEBSERVICE

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