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 é acionado por cron e captura periodicamente registros da view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES que possuem DATA_PARA_TRANSFERENCIA a partir do filtro configurado. Recupera o estado anterior (offset, chave_posicao, data_posicao, filtro, situação). Se a situação estiver concluída (2), redefine para parado (0) para permitir novo ciclo. Se parado (0) ou em execução (1), normaliza os filtros (A1_LOJA, A1_COD, CGC_CPF, DATA_PARA_TRANSFERENCIA), monta a query com paginação (OFFSET/FETCH NEXT) usando o limite woskLimiteCaptura::ProtheusCliente, executa a consulta e para cada registro sanitiza os campos (trim), monta a chave A1_LOJA-A1_COD-CGC_CPF, enfileira na Queue com status "Aguardando Integração" e atualiza incrementalmente a posição do monitor. Ao final marca situação como concluída (2). Em erro, registra em filtro[ERRORS] e marca situação como problema (4).

~~2. DADOS NECESSÁRIOS PARA O MONITOR~~
Configuração: woskLimiteCaptura::ProtheusCliente (inteiro) – quantidade máxima de registros por lote (top). Estado persistido: data_posicao, data_iniciado, offset, chave_posicao, filtro, situação, token. Filtros utilizados: 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~~
~~O método get("ProtheusCliente") recupera do controle do monitor: data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situação (0=parado, 1=executando, 2=concluído, 4=problema).~~
~~3.2 Reset ao iniciar execução~~
Se situação for 2 (concluído), é redefinida para 0 (parado) via set(..., 0, ...). Se situação for 0 (parado), antes de processar são resetados: dataPosicao e dataIniciado para new DateTime(), offset para 0, chavePosicao para string vazia. Se situação for 1 (executando), nenhum reset é feito.
~~3.3 Normalização dos filtros~~
A1_LOJA, A1_COD e CGC_CPF: se vazios, ficam como string vazia. DATA_PARA_TRANSFERENCIA: se vazio, é definido como 2023-05-01 00:00:00; caso contrário é convertido de string para DateTime e formatado em "Y-m-d H:i:s".
~~3.4 Atualização do estado para EXECUTANDO~~
~~Antes de cada consulta à view, é chamado set(offset, chavePosicao, dataPosicao, filtro, 1, dataIniciado, token), marcando situação como 1 (executando).~~
~~3.5 Paginação dos registros~~
A query é montada com WHERE DATA_PARA_TRANSFERENCIA >= '{filtro[DATA_PARA_TRANSFERENCIA]}', ORDER BY DATA_PARA_TRANSFERENCIA ASC, OFFSET {offset} ROWS FETCH NEXT {top} ROWS ONLY. A view consultada é WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES (campos: 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).
~~3.6 Sanitização dos dados~~
~~Para cada linha retornada (fetch ASSOC), é aplicado array_walk_recursive com trim em todos os valores do array.~~
~~3.7 Atualização do filtro de posição~~
~~O array novoFiltro recebe A1_LOJA, A1_COD, CGC_CPF e DATA_PARA_TRANSFERENCIA do registro atual; DATA_PARA_TRANSFERENCIA é formatada via setDateTime()->format("Y-m-d H:i:s").~~
~~3.8 Enfileiramento~~
A chave de enfileiramento é key = A1_LOJA . '-' . A1_COD . '-' . CGC_CPF. É chamado queueClass->set(key, r, [], 'Aguardando Integração', '', 0, 0, setDateTime(novoFiltro[DATA_PARA_TRANSFERENCIA])). Se set retornar false, é lançada exceção.
~~3.9 Atualização incremental da posição~~
Após cada enfileiramento: offset é incrementado; chavePosicao = key; dataPosicao = setDateTime(novoFiltro[DATA_PARA_TRANSFERENCIA]); set(offset, chavePosicao, dataPosicao, filtro, 1, dataIniciado, token).
~~3.10 Finalização~~
~~Ao sair do loop (stop=true ou offset < top), é chamado set(offset, chavePosicao, dataPosicao, novoFiltro, 2, dataIniciado, token), definindo situação como 2 (concluído).~~
~~3.11 Tratamento de erro~~
No catch: errorByexception(e); se filtro[ERRORS] não existir, é inicializado como array; é adicionado em filtro[ERRORS] um objeto com DATE (DateTime atual formatado) e MESSAGE (e->getMessage()); em seguida set(offset, chavePosicao, dataPosicao, filtro, 4, dataIniciado, token), marcando situação como 4 (problema).

~~4. PERSISTÊNCIA DOS DADOS (BANCO DE DADOS)~~
~~4.1 Controle do monitor~~
O estado do monitor (offset, chave_posicao, data_posicao, filtro, situação, data_iniciado, token) é persistido através do método _set("ProtheusCliente", ...), que grava no armazenamento de controle do monitor (tabela/estrutura definida pelo trait WOSK\Commons\Monitor).
~~4.2 Fila de integração~~
Cada registro capturado é inserido na fila via Queue::set(), com chave A1_LOJA-A1_COD-CGC_CPF, payload do registro, status "Aguardando Integração", e data de referência DATA_PARA_TRANSFERENCIA. A persistência da fila é feita pela classe Queue (tabela/estrutura própria da fila).

~~5. RESULTADO DO PROCESSAMENTO~~
Ao concluir sem erro: situação 2 (concluído); estado atualizado com último offset, chave_posicao e data_posicao; todos os registros do lote enfileirados para processamento assíncrono pela Queue. Em caso de exceção: situação 4 (problema); filtro[ERRORS] com data e mensagem do erro; estado do monitor mantém offset/chave/data até o último registro processado com sucesso.

~~6. OPERAÇÃO MANUAL – capturar()~~
O método capturar($chave) permite incluir manualmente um ou vários itens na fila. O parâmetro chave pode ser uma string (uma chave) ou um array de chaves. Cada chave deve ter o formato A1_LOJA-A1_COD ou A1_LOJA-A1_COD-CGC_CPF (2 ou 3 partes separadas por '-'). Para cada chave: é obtido o registro atual da Queue (get) para preservar o token; a chave é quebrada em partes (explode '-', 3); é montada a query na view WOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES com WHERE A1_LOJA, A1_COD e opcionalmente CGC_CPF; os registros retornados são sanitizados (trim), monta-se novoFiltro e key, e são inseridos na fila via Queue::set com o mesmo token. Chave inválida (menos de 2 ou mais de 3 partes) gera exceção. Exceções são tratadas com 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