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. 1. Processo:DESCRIÇÃO
      simplyDO dummyFLUXO

      text
   of
   the
printing

and

O typesettingMonitor industry.ProtheusClienteFull Loremé Ipsumresponsável hasexclusivamente beenpela thecaptura industry'sincremental standardde dummyregistros textda everview sinceWOSK_SERVICO_ENVIA_PROTHEUS_CLIENTES_FULL thee 1500s,pelo whenencaminhamento anestruturado unknowndesses printerregistros tookpara a galleyfila ofde typeintegração and(Queue).

scrambled

O itprocesso toé makeacionado 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 typeQueue.

    specimen
  book.
  It
has

survived

Fluxo notde onlyexecução:

five

centuries,
1. but
   also
   1. the

      Recupera leapo intoestado electronicatual typesetting,do remainingmonitor essentiallyna unchanged.base Itde wascontrole.

      popularised
   in
   2. the

      Avalia 1960sa withsituação thearmazenada:

      release
      of
      • Letraset

        Se sheetsCONCLUÍDO containing(2) Lorem→ Ipsumredefine passages,para andPARADO more(0).

        recently
      with
      • desktop

        Se publishingPARADO software(0) like→ Aldusreinicia PageMakerexecução.

        including
      versions
      • of

        Se LoremEXECUTANDO Ipsum(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. 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. 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. 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. 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. 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. 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

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

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

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