ProtheusNotaFiscalMarketplacePontual (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	TO-DOOSKLEN
Nome do projeto	TO-DOIntegração LINX → Protheus
Biblioteca	wosk_protheus_nota_fiscal_marketplace_pontual
Token da Biblioteca	b35dc71f-3153-423d-9bd2-3f97cbe66573
URL de Produção	https://isnapp.illimitar.pro/bibliotecas/b35dc71f-3153-423d-9bd2-3f97cbe66573/wosk_protheus_nota_fiscal_marketplace_pontual
URL de Homologação	https://hmg-isnapp.illimitar.pro/bibliotecas/b35dc71f-3153-423d-9bd2-3f97cbe66573/wosk_protheus_nota_fiscal_marketplace_pontual
Data	23/27/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
23/27/02/2026	1.0	Maykon/GustavoMaykon	DocumentaçCriação inicialda documentação técnica do processo ProtheusNotaFiscalMarketplacePontual.

Descrição Geral dos Processos

EscopoEsta destebiblioteca arquivo:

-organiza Esteo documentoenvio foi gerado exclusivamente a partirpontual de wosk_protheusNotaFiscalMarketplacePontual/wosk_protheusNotaFiscalMarketplacePontual.php.
- Classes presentes neste arquivo: Monitor e Queue.
- Classe ausente neste arquivo: Webservice (não há endpoint implementado aqui).

Monitor

Processo: 
1. DESCRIÇÃO DO FLUXO

- Responsabilidade: capturar, de forma incremental, notas fiscais de marketplace do MarketplaceLINX para o Protheus, garantindo captura por chave ou por período.

Capturador

Descrição Conceitual

Permite a captura manual (cabeçalhopor chave composta) e itens)a captura automática (por agendador de tarefas) de notas fiscais pendentes, consultando a partir de fontes SQLorigem e enfileirarregistrando cada nota fiscalitem para processamento assíncrono.
-
A Disparo:captura execuçautomática segue processamento cronológico (ordenação/paginação agendadapor (cron)data) chamandopara Monitor::run()priorizar registros mais antigos e manter continuidade por posição; link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL.

AoOrigem iniciar, o monitor determina o limiteauxiliar de itens: view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL.

Consulta utilizada na captura automática (janela diária calculada a partir de DATA_PARA_TRANSFERENCIA e paginação pelaconforme configuração woskLimiteCaptura::ProtheusNotaFiscalMarketplacePontualOFFSET e carregalimite o estado persistido via get('ProtheusNotaFiscalMarketplacePontual'), contendo:
- data_posicao, data_iniciado, offset, chave_posicao, filtro, token e situacao.configurado):

Regras

de

SELECT
    continuidade:
-TIPO,
    SeE1_XFILORI,
    situacaoF2_FILIAL,
    =F2_DOC,
    2F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL (Concluído)NOLOCK)
→WHERE
    redefine para 0 (Parado) e permite nova execução.
- Se situacao estiver em [0, 1] → inicia/continua o processamento.

Para a data base de captura, o monitor trabalha por janelas diárias. A cada ciclo de paginação ele:
- Persiste situacao = 1 (Executando) antes da consulta.
- Calcula dataInicio e dataFim como o intervalo do dia de filtro.DATA_PARA_TRANSFERENCIA (00:00:00 até 23:59:59).
- Executa query paginada sobre WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL filtrando por DATA_PARA_TRANSFERENCIA BETWEEN dataInicio'<DATA_INICIO_DIA>' AND dataFim,'<DATA_FIM_DIA>'
com:
    - ORDER BY
    DATA_PARA_TRANSFERENCIA ASC

-OFFSET
    <OFFSET> baseadoROWS no estado do monitor
    - FETCH NEXT no<LIMITE> limiteROWS configuradoONLY

ParaConsulta cadautilizada na captura manual (chave informada e WHERE construído dinamicamente):

SELECT
    TIPO,
    E1_XFILORI,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

Consulta utilizada para recuperar itens da nota fiscal retornada:
-(itens Sanitizavinculados o cabeçalho com trim() recursivo.
- Atualiza o filtro de posição (F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA, DATA_PARA_TRANSFERENCIA).
- Monta aà chave noprincipal):

padrão:

SELECT
    F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.
- Consulta os itens via getItens(F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_CLIENTE,
    F2_LOJA),F2_LOJA,
    lendoD2_CCUSTO,
    deD2_LOCAL,
    D2_ITEM,
    D2_COD,
    D2_QUANT,
    D2_PRCVEN,
    D2_TOTAL,
    D2_TES,
    D2_BASEICM,
    D2_PICM,
    D2_VALICM,
    D2_DESCON,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL.
 (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

 

Operações com Dados

- EnfileiraLeitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL para obter o registro (cabeçalhoatual +da itens)nota fiscal e montar a chave composta F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.

- Leitura auxiliar de itens: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL para obter os itens relacionados à chave, que serão anexados ao conteúdo do item da fila.

- Controle de limite de captura: obtém o limite de itens por ciclo via Queue::set() com status Aguardando Integração e situacao = 0.
- Atualiza incrementalmente o estado do monitor (offset, chave e data) após cada enfileiramento, garantindo retomada.

Encerramento e agendamento da próxima janela (data):
- Quando a página atual retorna menos registros que o limite, considera o dia processado e marca situacao = 2 (Concluído).
- Se a data de posiçconfiguração for menor/igual ao momento atual, avança o filtro para o próximo dia (+1 dia) e redefine DATA_PARA_TRANSFERENCIA para 00:00:00 (reiniciando com offset = 0).

Em caso de erro (catch)woskLimiteCaptura::
- Marca o monitor como situacao = 4 (Problema).
- Registra a falha em filtro.ERRORS[] com DATE e MESSAGE.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para o MonitorProtheusNotaFiscalMarketplacePontual, osaplicado dadosna de entrada são originados das fontes SQL consultadas em viewQuery e getItens().

Fonte (cabeçalho da nota):
- View/Tabela lógica: WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL
Campos capturados:
- Identificação/Chave: F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA
- Controle: TIPO, E1_XFILORI, F2_PEDIDO, F2_TIPO, F2_FORMUL, F2_EMISSAO, F2_ESPECIE, F2_COND, F2_XNATOPE
- NF-e: F2_CHVNFE, F2_HAUTNFE, F2_DAUTNFE, F2_PROTOCOLO
- Valores: F2_FRETE, F2_SEGURO, F2_DESPESA, F2_XCBSIBS
- Incremental: DATA_PARA_TRANSFERENCIA

Fonte (itens da nota):
- View/Tabela lógica: WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL
Campos capturados:
- Identificação: D2_ITEM, D2_COD, D2_TES
- Quantidades/Valores: D2_QUANT, D2_PRCVEN, D2_TOTAL, D2_BASEICM, D2_PICM, D2_VALICM, D2_DESCON
- Tributos adicionais: D2_XIBSBS, D2_XIBSAL, D2_XIBSVL, D2_XCBSBS, D2_XCBSAL, D2_XCBSVL
- Incremental: DATA_PARA_TRANSFERENCIA


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperaçpaginação do estado do monitor
Momento: Início do run()
- Lê estado via get('ProtheusNotaFiscalMarketplacePontual').
- Se estado estiver incompleto (sem data_posicao), inicializa: datas atuais, offset = 0, chave_posicao = '', filtro = [] e token = ''.

3.2 Reset ao iniciar execução
Momento: Quando situacao = 2 (pré-execução)
- Persiste situacao = 0 com o estado atual para permitir novo ciclo.

3.3 Normalização dos filtros
Momento: Antes da query
- Garante que F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA existam (string vazia quando ausentes).
- Define DATA_PARA_TRANSFERENCIA:
    - informado → convertido/formatado para Y-m-d H:i:s
    - ausente → 2023-05-01 00:00:00

3.4 Atualização do estado para EXECUTANDO
Momento: Antes da consulta de(FETCH cadaNEXT página<LIMITE>).

- PersisteRegistro situacaopara = 1 com o estado do monitor (offset, chave, datas, filtro).

3.5 Paginação dos registros
Momento: Execução da query
- Query diária por intervalo (BETWEEN dataInicio AND dataFim).
- Ordena por DATA_PARA_TRANSFERENCIA ASC.
- Pagina com OFFSET/FETCH NEXT no limite configurado.

3.6 Sanitização dos dados
Momento: Ao ler cada registro (cabeçalho) e cada item (em getItens())
- Aplica trim() recursivamente em todos os campos.

3.7 Atualização do filtro de posição
Momento: Após lerprocessamento: cada nota fiscal
- Atualizacapturada novoFiltroé persistida como pendência na tabela wosk_queue sob o serviço ProtheusNotaFiscalMarketplacePontual, com a chave completacomposta e a DATA_PARA_TRANSFERENCIA conteúdo registro(incluindo (normalizada).

3.8 Enfileiramento
Momento: Dentro do loop de notas fiscais
- Enfileira (cabeçalho + itens) via Queue::set(itens) com:
    - chave: F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA
    - status: Aguardando Integração
    - situacao: 0

3.9 Atualização incremental da posição
Momento: Após inserir na fila
- offset ← offset + 1
- chavePosicao ← chave da nota fiscal
- dataPosicao ← DATA_PARA_TRANSFERENCIA
- Persiste imediatamente para suportarprocessamento retomada.

3.10assíncrono.

Finalização
Momento: Após

encerrar o ciclo do dia
- Se o dia foi concluído, agenda a próxima data (dia seguinte quando necessário) e persiste situacao = 2 com o novoFiltro efetivo.

3.11 Tratamento de erro
Momento: catch(Exception) do run()
- Adiciona erro em filtro.ERRORS[] e persiste situacao = 4.


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

4.1 Controle do monitor
Momento: Durante execução, continuidade e finalização do run()
- Persistência ocorre via Monitor::set() (trait wosk_monitor).
- Tabela persistida: {$this->bancoIntegrador}.wosk_monitor.
- Campos persistidos: token, evento, offset, filtro, chave_posicao, situacao, data_posicao, data_iniciado.

4.2

Fila de integração
Momento:Processamento

Enfileiramento (3.8)
- Tabela persistida: {$this->bancoIntegrador}.wosk_queue (via biblioteca wosk_queue).


5. RESULTADO DO PROCESSAMENTO

Execuç

Descrição normal:
-Conceitual

Monitor

A marcadofila comorecupera Concluídoum (2)registro ao final do ciclo do dia.
- Notas fiscais enfileiradas para envio ao Protheus pela Queue.

Execução com erro:
- Monitor marcado como Problema (4).
- Erro persistido em filtro.ERRORS[] para auditoriapendente e retomada controlada.


6. OPERAÇÃO MANUAL – capturar()

Objetivo: enfileirar manualmente uma ou mais notas fiscais a partir da chave completa.

Fluxo:
- Entrada: chave string ou array no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.
- Para cada chave:
    - Consulta Queue::get('', chave) para reaproveitar token quando existir.
    - Consulta a fonte por chave completa (WHERE com os 5 campos).
    - Sanitiza com trim() recursivo, carrega itens via getItens() e enfileira via Queue::set() usando o token reaproveitado.

Queue

Processo:
 1. DESCRIÇÃO DO FLUXO

- Responsabilidade: consumir um item da fila, reestruturar/normalizar os dados (cabeçalho e itens), validar pré-condições e enviar a nota fiscal ao Protheus, persistindo retorno, tempo e status do processamento.
- Disparo: execução agendada (cron) chamando Queue::run(token).

Ao iniciar, a fila busca o item via get(token). Se houver registro:
- Atualiza o item para status Enviando e situacao = 1 antes do envio.
- Converteutiliza o conteúdo persistidodo emregistro como base do payload viade getConteudo()integração. aplicandoEm seguida, aplica transformações obrigatórias de padronização mapeamentoe definido em $field (incluirealiza a estruturachamada itens).ao Protheus.

Pré-validaç

Estruturação (dependênciade Dados

{
  "TIPO": "",
  "e1_xfilori": "",
  "f2_filial": "",
  "f2_doc": "",
  "f2_serie": "",
  "f2_pedido": "",
  "f2_tipo": "",
  "f2_formul": "",
  "f2_emissao": "",
  "f2_cliente": "",
  "f2_loja": "",
  "f2_especie": "",
  "f2_chvnfe": "",
  "f2_hautnfe": "",
  "f2_dautnfe": "",
  "f2_protocolo": "",
  "f2_cond": "",
  "f2_frete": "",
  "f2_seguro": "",
  "f2_despesa": "",
  "f2_xnatope": "",
  "itens": [
    {
      "d2_item": "",
      "d2_cod": "",
      "d2_quant": "",
      "d2_prcven": "",
      "d2_total": "",
      "d2_tes": "",
      "d2_baseicm": "",
      "d2_picm": "",
      "d2_valicm": "",
      "D2_DESCON": ""
    }
  ]
}

Tratamento de Dados

- AntesValidação prévia obrigatória: antes do envio,envio da nota fiscal, valida se o cliente da nota está integrado chamandoconsultando setProtheusClienteIntegrado(f2_loja-f2_cliente)a rotina inteligente setProtheusClienteIntegrado com a chave F2_LOJA-F2_CLIENTE.
- Se o retorno não for true, o processamento do item é suspenso com:
    - suspensaoTipo = 'ProtheusCliente'
    - suspensaoChave = f2_loja-f2_cliente
    - situacao = 3 (suspenso por dependência)

Normalizações e transformações numéricas pré-envio:
- Cabeçalho:
    - f2_frete, f2_seguro, f2_despesa → normalizados por setNumeric().
- Itens (para cada item):
    - d2_quant, d2_prcven, d2_total, d2_baseicm, d2_picm, d2_valicm, D2_DESCON → setNumeric().
    - D2_XIBSBS, D2_XIBSAL, D2_XIBSVL, D2_XCBSBS, D2_XCBSAL, D2_XCBSVL → setNumeric().

Envio ao Protheus:
- Endpoint lógico: linx/nota_fiscal via setProtheus('linx/nota_fiscal', payload, 'POST', headers).
- Header aplicado: tenantId no formato UF,filial (ex.: substr(f2_filial, 0, 2) + "," + f2_filial).

Validação e classificação do retorno:
- Se não houverestiver respostaintegrado, →o erro:item é finalizado como suspenso (situacao = 3) com suspensao_tipo e suspensao_chave preenchidos para tratamento posterior.

- Padronização numérica (precisão padrão):
  - f2_frete, f2_seguro, f2_despesa: normalizados com setNumeric(...).
  - itens[].d2_quant, itens[].d2_prcven, itens[].d2_total, itens[].d2_baseicm, itens[].d2_picm, itens[].d2_valicm, itens[].D2_DESCON: normalizados com setNumeric(...).

Rotinas Inteligentes

- Cliente Integrado: validada antes de iniciar o envio da nota fiscal (condição obrigatória por cliente). Garante que a integração da nota fiscal só prossiga quando o cliente estiver pronto para o Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

- Nota Fiscal Omni Integrado: executada após retorno de sucesso do Protheus para a nota fiscal. Marca a nota fiscal como integrada usando a chave F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA para evitar reprocessamento.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/nota-fiscal-omni-integrado

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: linx/nota_fiscal
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <prefixo_2_caracteres_de_F2_FILIAL>,<F2_FILIAL>
 

Tratamento de retorno

Ausência de resposta: registra erro com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como falha.
-

Se

Resposta codeinválida/inesperada: quando não existirhouver code no retornoretorno, →registra erro:erro com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
-.

Montagem

Indicadores dade mensagemsucesso/erro: final:
considera -erro base em message
    - complemento em detailedMessage (quando existir).code for maior que 299; caso contrário, considera sucesso.
-

Regra de idempotência: sequando a mensagem contiver "numero de nota fiscal ja gravado"gravado, tratao retorno é reinterpretado como sucesso ajustando(força code = 0 e Mensagem = "OK"OK).
-

Situaç

Sucesso: quando a situação finalfor dosucesso, item:
marca - 2 se code <= 299
    - 4 se code > 299

Ações pós-sucesso:
- Em sucesso (situacao = 2): registra integração daa nota viafiscal setProtheusNotaFiscalOmniIntegradocomo eintegrada disparapela atualizaçãorotina deinteligente cancelamentoNota viaFiscal setProtheusDocumentoCancelamentoSaida,Omni utilizandoIntegrado usando a chave:
chave - F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.

Persistência

do item de fila:
- Ao final, atualiza o item com retorno, mensagem, dump de requisição (_CURL_DUMP), tempo e situação (2, 3 ou 4).

Notificação de erros:
- notificar() consulta em wosk_queue os itens com acao = 'ProtheusNotaFiscalMarketplacePontual' e situacao = 4, formata e envia

Quando a notificação via _getNotificarErros.


2. DADOS NECESSÁRIOS PARA O ENDPOINT

Não há endpoint (WebService) implementado neste arquivo. Para a Queue, os dados necessários são os itens persistidos na fila.

Estrutura do item de fila (campos utilizados neste arquivo):
- token: identificador do item para consumo.
- acao: ProtheusNotaFiscalMarketplacePontual.
- chave: F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.
- conteudo: registro completo (cabeçalho + itens) capturado pelo monitor.
- data_adicionado: data/hora de captura gravada no enfileiramento.


3. REESTRUTURAÇÃO DOS DADOS

3.1 Recuperação do item de fila
Momento: Início do run(token)
- Lê item via get(token).

3.2 Reset ao iniciar execução
Momento: Antes do envio
- Atualiza o item para status Enviando e situacao = 1.

3.3 Normalização do payload
Momento: Pré-envio
- Aplica mapeamento de campos via $field, incluindo a estrutura de itens.

3.4 Atualização do estado para EXECUTANDO
Momento: Pré-requisição
- Mantém situacao = 1 enquanto processa e envia; troca para 2, 3 ou 4 ao concluir.

3.5 Paginação dos registros
Momento: Não aplicável (processa 1 item por execução).

3.6 Sanitização dos dados
Momento: Pré-envio
- Normaliza campos numéricos com setNumeric() (cabeçalho e itens).

3.7 Atualização do filtro de posição
Momento: Não aplicável (controle de posição é do Monitor).

3.8 Envio / Integração
Momento: Envio ao Protheus
- Executa setProtheus('linx/nota_fiscal', payload, 'POST', headers) com tenantId derivado de f2_filial.

3.9 Atualização incremental da posição
Momento: Não aplicável (não há offset na Queue).

3.10 Finalização
Momento: Pós-resposta do Protheus / pós-prévalidação de dependência
- Persiste situação final (2, 3 ou 4) e retorno/mensagem no item da fila.

3.11 Tratamento de erro
Momento: catch(Exception) interno do processamento do item
- Define situacao = 4 e persiste retorno com erro e mensagem correspondente (ou situacao = 3 quando a falha for dependência de cliente).


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

4.1 Controle do monitor
Momento: Não aplicável para esta classe (não grava wosk_monitor).

4.2 Fila de integração
Momento: Durante todo o ciclo do item (get/set).
- Tabela persistida: {$this->bancoIntegrador}.wosk_queue.
- Suspensões (dependências) são persistidas no próprio item via _set (campos de suspensão repassados pela chamada).
- Logs internos de falha de persistência podem ser gravados em {$this->bancoIntegrador}.wosk_queue_log (biblioteca wosk_queue).


5. RESULTADO DO PROCESSAMENTO

Execução normal:
- Item finalizado com situacao = 2, retorno do Protheus persistido e integração registrada.

Execução suspensa (dependência):
- Item finalizado com situacao = 3, indicando dependência de cliente não atendidafor (ProtheusCliente).

Execuçãatendida, o comitem erro:
- Itemé finalizado comcomo suspenso (situacao = 43) e mensagema persistidafila registra suspensao_tipo = 'ProtheusCliente' e suspensao_chave = 'F2_LOJA-F2_CLIENTE' para auditoriadirecionar o tratamento.

Encaminhamento em cenário de erro

Em cenários de falha (ausência de resposta, retorno inválido ou code > 299), o item permanece registrado em wosk_queue com detalhes do retorno e notificação.


6.mensagem, OPERAÇÃOpermitindo MANUALacompanhamento –e capturar()

Nãreprocessamento conforme necessidade operacional. Em cenários de dependência (cliente não aplicávelintegrado), o item é marcado como suspenso (situacao = 3) para estaimpedir classeprocessamento (indevido até que a operaçcondição manualseja estáresolvida.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura automática com ordem por data	Ao consultar WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL com filtro por DATA_PARA_TRANSFERENCIA, ordenação ascendente e paginação por OFFSET/FETCH, deve manter continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao, filtro).	Posição atualizada em wosk_monitor e itens pendentes registrados na fila com chave composta.
Capturador	Captura manual por chave composta	Ao informar uma chave no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA, deve consultar a origem filtrando pelos cinco campos e registrar o item correspondente na fila, anexando itens obtidos de WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL.	Item pendente registrado na fila com conteúdo completo (cabeçalho + itens) para integração.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusNotaFiscalMarketplacePontual), deve normalizar campos numéricos com setNumeric(...), incluir cabeçalho tenantId e integrar via POST no recurso linx/nota_fiscal.	Item atualizado em wosk_queue com retorno/mensagem e situacao coerente (sucesso quando code não indicar erro; erro quando houver ausência de resposta, retorno inválido ou code > 299).
Fila de Processamento	Tratamento de retorno e marcação de integrado	Quando a integração retornar sucesso (incluindo o caso de idempotência por mensagem numero de nota fiscal ja gravado), deve marcar a nota como integrada pela rotina inteligente setProtheusNotaFiscalOmniIntegrado e registrar a situação final.	Nota fiscal marcada como integrada e item de fila finalizado com situação de sucesso.