ProtheusDocumentoSaidaPontual (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_documento_saida_pontual
Data	03/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
03/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo `ProtheusDocumentoSaidaPontual`.

Descrição

Esta biblioteca organiza o envio de documentos de saída pontuais do LINX para o Protheus, garantindo que cada documento seja capturado, preparado com seus itens e encaminhado para integração.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais documentos de saída pontuais mediante a informação das chaves no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA-F2_TIPO-F2_XNATOPE, consultando a origem e carregando os itens antes de registrar o item para processamento assíncrono. Caso a chave informada esteja fora do padrão (menos de 7 partes), o processo é interrompido com erro de chave inválida.

A captura por data consulta a origem filtrando por DATA_PARA_TRANSFERENCIA no intervalo do dia (BETWEEN dataInicio AND dataFim), ordenando por DATA_PARA_TRANSFERENCIA ASC e paginando por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico. A execução periódica pode ser acionada por agendador de tarefas.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL e view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_ITEM_PONTUAL.

Consulta utilizada na captura por data (WHERE e paginação construídos dinamicamente conforme posição e limite configurado):

SELECT
    TEMP_FILIAL,
    TEMP_NF_SAIDA,
    TEMP_SERIE_NF,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_CLIENTE,
    F2_LOJA,
    F2_TIPOCLI,
    F2_EST,
    F2_DUPL,
    F2_EMISSAO,
    F2_DTDIGIT,
    F2_ESPECIE,
    F2_TIPO,
    F2_COND,
    F2_XNATOPE,
    F2_XCANAL,
    F2_XNATUR,
    F2_TPFRETE,
    F2_VALMERC,
    F2_VALBRUT,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    F2_DESCONT,
    F2_VALFAT,
    F2_PREFIXO,
    F2_VALICM,
    F2_BASEICM,
    F2_ICMFRETE,
    F2_VALIPI,
    F2_BASEIPI,
    F2_ICMSRET,
    F2_BRICMS,
    F2_BASIMP6,
    F2_BASIMP5,
    F2_VALIMP6,
    F2_VALIMP5,
    F2_BASFECP,
    F2_BSFCCMP,
    F2_BSFCPST,
    F2_BASEPS3,
    F2_VALPS3,
    F2_BASECF3,
    F2_VALCF3,
    F2_MOEDA,
    F2_NFORI,
    F2_SERIORI,
    F2_UFDEST,
    F2_UFORIG,
    F2_ESPECI1,
    F2_VOLUME1,
    F2_PLIQUI,
    F2_PBRUTO,
    F2_TRANSP,
    F2_SDOC,
    F2_CHVNFE,
    F1_DAUTNFE,
    F1_HAUTNFE,
    F1_PROTOC,
    C5_PARC1,
    C5_PARC2,
    C5_PARC3,
    C5_PARC4,
    C5_PARC5,
    C5_PARC6,
    C5_PARC7,
    C5_PARC8,
    C5_PARC9,
    C5_PARC10,
    C5_PARC11,
    C5_PARC12,
    C5_DATA1,
    C5_DATA2,
    C5_DATA3,
    C5_DATA4,
    C5_DATA5,
    C5_DATA6,
    C5_DATA7,
    C5_DATA8,
    C5_DATA9,
    C5_DATA10,
    C5_DATA11,
    C5_DATA12,
    F3_DTCANC,
    F3_CODRSEF,
    CREPROCESSA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA BETWEEN '<dataInicio>' AND '<dataFim>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <offset> ROWS FETCH NEXT <top> ROWS ONLY

Consulta utilizada na captura manual (WHERE construído dinamicamente a partir das chaves informadas):

SELECT
    ... (colunas da view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL)
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL (NOLOCK)
WHERE
    F2_FILIAL = '<chave[0]>'
    AND F2_DOC = '<chave[1]>'
    AND F2_SERIE = '<chave[2]>'
    AND F2_CLIENTE = '<chave[3]>'
    AND F2_LOJA = '<chave[4]>'
    AND F2_XNATOPE = '<chave[6]>'

Consulta utilizada para carregar os itens do documento (WHERE construído dinamicamente a partir de F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA):

SELECT
    D2_FILIAL,
    D2_ITEM,
    D2_COD,
    D2_TP,
    D2_UM,
    D2_LOCAL,
    D2_QUANT,
    D2_PRCVEN,
    D2_PRUNIT,
    D2_TOTAL,
    D2_DESC,
    D2_DESCON,
    D2_SEGURO,
    D2_VALFRE,
    D2_DESPESA,
    D2_VALBRUT,
    D2_EMISSAO,
    D2_DTDIGIT,
    D2_DOC,
    D2_SERIE,
    D2_SDOC,
    D2_TIPO,
    D2_ESPECIE,
    D2_CLIENTE,
    D2_LOJA,
    D2_EST,
    D2_CLASFIS,
    D2_TES,
    D2_CF,
    D2_BASEIPI,
    D2_IPI,
    D2_VALIPI,
    D2_BASEICM,
    D2_PICM,
    D2_VALICM,
    D2_BASFECP,
    D2_ALQFECP,
    D2_VALFECP,
    D2_BRICMS,
    D2_ALIQSOL,
    D2_MARGEM,
    D2_ICMSRET,
    D2_BSFCPST,
    D2_ALFCPST,
    D2_VFECPST,
    D2_BASIMP5,
    D2_ALQIMP5,
    D2_VALIMP5,
    D2_BASIMP6,
    D2_ALQIMP6,
    D2_VALIMP6,
    D2_BASEPS3,
    D2_ALIQPS3,
    D2_VALPS3,
    D2_BASECF3,
    D2_ALIQCF3,
    D2_VALCF3,
    D2_DESCZFP,
    D2_DESCZFC,
    D2_BASEDES,
    D2_ALIQCMP,
    D2_PDORI,
    D2_PDDES,
    D2_PDIFAL,
    D2_BSFCCMP,
    D2_ALFCCMP,
    D2_VFCPDIF,
    D2_CC,
    D2_CONTA,
    D2_PESO,
    D2_ESTOQUE,
    D2_NFORI,
    D2_SERIORI,
    D2_ITEMORI,
    D2_XPRMDPR,
    D2_XALIQBA,
    D2_ORIGLAN,
    D2_OP,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_ITEM_PONTUAL (NOLOCK)
WHERE
    D2_FILIAL = '<F2_FILIAL>'
    AND D2_DOC = '<F2_DOC>'
    AND D2_SERIE = '<F2_SERIE>'
    AND D2_CLIENTE = '<F2_CLIENTE>'
    AND D2_LOJA = '<F2_LOJA>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL para obter o registro atual do documento de saída e construir o identificador de processamento com base em F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA, F2_TIPO e F2_XNATOPE.

- Carregamento de itens: para cada registro atual, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_ITEM_PONTUAL filtrando por D2_FILIAL, D2_DOC, D2_SERIE, D2_CLIENTE, D2_LOJA e agrega os itens retornados no campo ITENS, formando o conjunto completo (cabeçalho + itens) para integração.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusDocumentoSaidaPontual, aplicado na paginação da consulta (FETCH NEXT <top>).

- Persistência de posição/continuidade: registra e atualiza o controle do capturador na tabela wosk_monitor (banco {$this->bancoIntegrador}) usando evento = 'ProtheusDocumentoSaidaPontual', mantendo token, offset, filtro, chave_posicao, situacao, data_posicao, data_iniciado e data.

- Situações registradas no controle: parado/início (0), em processamento (1), concluído (2) e problema (4). Em caso de falha, o campo filtro recebe um histórico em ERRORS[] com DATE e MESSAGE para auditoria.

- Registro para processamento: cada documento de saída capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusDocumentoSaidaPontual, com o conteúdo vindo da origem (incluindo ITENS) para processamento assíncrono.

Fila de Processamento

Descrição Conceitual

A fila recupera um registro pendente e utiliza o conteúdo do registro como base do payload de integração. Em seguida, aplica transformações obrigatórias de padronização e realiza a chamada ao Protheus.

O item de fila é persistido e atualizado na tabela wosk_queue (banco {$this->bancoIntegrador}) ao longo do processamento, registrando retorno, mensagem, tempo, situação e informações para auditoria.

Estruturação de Dados

A estrutura oficial do payload de integração é definida pelo array $field da fila. Cada campo do payload é preenchido a partir do conteúdo do item de fila, conforme o mapeamento abaixo.

Campos do payload (nível raiz)

Campo no payload	Campo de origem
`F2_FILIAL`	`F2_FILIAL`
`F2_DOC`	`F2_DOC`
`F2_SERIE`	`F2_SERIE`
`F2_CLIENTE`	`F2_CLIENTE`
`F2_LOJA`	`F2_LOJA`
`F2_TIPOCLI`	`F2_TIPOCLI`
`F2_EST`	`F2_EST`
`F2_DUPL`	`F2_DUPL`
`F2_EMISSAO`	`F2_EMISSAO`
`F2_DTDIGIT`	`F2_DTDIGIT`
`F2_ESPECIE`	`F2_ESPECIE`
`F2_TIPO`	`F2_TIPO`
`F2_COND`	`F2_COND`
`F2_XNATOPE`	`F2_XNATOPE`
`F2_XCANAL`	`F2_XCANAL`
`F2_XNATUR`	`F2_XNATUR`
`F2_TPFRETE`	`F2_TPFRETE`
`F2_VALMERC`	`F2_VALMERC`
`F2_VALBRUT`	`F2_VALBRUT`
`F2_FRETE`	`F2_FRETE`
`F2_SEGURO`	`F2_SEGURO`
`F2_DESPESA`	`F2_DESPESA`
`F2_DESCONT`	`F2_DESCONT`
`F2_VALFAT`	`F2_VALFAT`
`F2_PREFIXO`	`F2_PREFIXO`
`F2_VALICM`	`F2_VALICM`
`F2_BASEICM`	`F2_BASEICM`
`F2_ICMFRET`	`F2_ICMFRETE`
`F2_VALIPI`	`F2_VALIPI`
`F2_BASEIPI`	`F2_BASEIPI`
`F2_ICMSRET`	`F2_ICMSRET`
`F2_BRICMS`	`F2_BRICMS`
`F2_BASIMP5`	`F2_BASIMP5`
`F2_VALIMP5`	`F2_VALIMP5`
`F2_BASIMP6`	`F2_BASIMP6`
`F2_VALIMP6`	`F2_VALIMP6`
`F2_BASFECP`	`F2_BASFECP`
`F2_BSFCCMP`	`F2_BSFCCMP`
`F2_BSFCPST`	`F2_BSFCPST`
`F2_BASEPS3`	`F2_BASEPS3`
`F2_VALPS3`	`F2_VALPS3`
`F2_BASECF3`	`F2_BASECF3`
`F2_VALCF3`	`F2_VALCF3`
`F2_MOEDA`	`F2_MOEDA`
`F2_NFORI`	`F2_NFORI`
`F2_SERIORI`	`F2_SERIORI`
`F2_UFDEST`	`F2_UFDEST`
`F2_UFORIG`	`F2_UFORIG`
`F2_ESPECI1`	`F2_ESPECI1`
`F2_VOLUME1`	`F2_VOLUME1`
`F2_PLIQUI`	`F2_PLIQUI`
`F2_PBRUTO`	`F2_PBRUTO`
`F2_TRANSP`	`F2_TRANSP`
`F2_SDOC`	`F2_SDOC`
`F2_CHVNFE`	`F2_CHVNFE`
`F2_DAUTNFE`	`F1_DAUTNFE`
`F2_HAUTNFE`	`F1_HAUTNFE`
`F2_XVENPRE`	`F2_XVENPRE`
`F3_PROTOC`	`F1_PROTOC`
`C5_PARC1` a `C5_PARC12`	`C5_PARC1` a `C5_PARC12`
`C5_DATA1` a `C5_DATA12`	`C5_DATA1` a `C5_DATA12`
`F3_DTCANC`	`F3_DTCANC`
`F3_CODRSEF`	`F3_CODRSEF`
`CREPROCESSA`	`CREPROCESSA`
`ITENS`	`ITENS` (array de itens)

Campos do payload (ITENS[])

Campo no payload	Campo de origem
`D2_FILIAL`	`D2_FILIAL`
`D2_ITEM`	`D2_ITEM`
`D2_COD`	`D2_COD`
`D2_TP`	`D2_TP`
`D2_UM`	`D2_UM`
`D2_LOCAL`	`D2_LOCAL`
`D2_QUANT`	`D2_QUANT`
`D2_PRCVEN`	`D2_PRCVEN`
`D2_PRUNIT`	`D2_PRUNIT`
`D2_TOTAL`	`D2_TOTAL`
`D2_DESC`	`D2_DESC`
`D2_DESCON`	`D2_DESCON`
`D2_SEGURO`	`D2_SEGURO`
`D2_VALFRE`	`D2_VALFRE`
`D2_DESPESA`	`D2_DESPESA`
`D2_VALBRUT`	`D2_VALBRUT`
`D2_EMISSAO`	`D2_EMISSAO`
`D2_DTDIGIT`	`D2_DTDIGIT`
`D2_DOC`	`D2_DOC`
`D2_SERIE`	`D2_SERIE`
`D2_SDOC`	`D2_SDOC`
`D2_TIPO`	`D2_TIPO`
`D2_ESPECIE`	`D2_ESPECIE`
`D2_CLIENTE`	`D2_CLIENTE`
`D2_LOJA`	`D2_LOJA`
`D2_EST`	`D2_EST`
`D2_CLASFIS`	`D2_CLASFIS`
`D2_TES`	`D2_TES`
`D2_CF`	`D2_CF`
`D2_BASEIPI`	`D2_BASEIPI`
`D2_IPI`	`D2_IPI`
`D2_VALIPI`	`D2_VALIPI`
`D2_BASEICM`	`D2_BASEICM`
`D2_PICM`	`D2_PICM`
`D2_VALICM`	`D2_VALICM`
`D2_BASFECP`	`D2_BASFECP`
`D2_ALQFECP`	`D2_ALQFECP`
`D2_VALFECP`	`D2_VALFECP`
`D2_BRICMS`	`D2_BRICMS`
`D2_ALIQSOL`	`D2_ALIQSOL`
`D2_MARGEM`	`D2_MARGEM`
`D2_ICMSRET`	`D2_ICMSRET`
`D2_BSFCPST`	`D2_BSFCPST`
`D2_ALFCPST`	`D2_ALFCPST`
`D2_VFECPST`	`D2_VFECPST`
`D2_BASIMP5`	`D2_BASIMP5`
`D2_ALQIMP5`	`D2_ALQIMP5`
`D2_VALIMP5`	`D2_VALIMP5`
`D2_BASIMP6`	`D2_BASIMP6`
`D2_ALQIMP6`	`D2_ALQIMP6`
`D2_VALIMP6`	`D2_VALIMP6`
`D2_BASEPS3`	`D2_BASEPS3`
`D2_ALIQPS3`	`D2_ALIQPS3`
`D2_VALPS3`	`D2_VALPS3`
`D2_BASECF3`	`D2_BASECF3`
`D2_ALIQCF3`	`D2_ALIQCF3`
`D2_VALCF3`	`D2_VALCF3`
`D2_DESCZFP`	`D2_DESCZFP`
`D2_DESCZFC`	`D2_DESCZFC`
`D2_BASEDES`	`D2_BASEDES`
`D2_ALIQCMP`	`D2_ALIQCMP`
`D2_PDORI`	`D2_PDORI`
`D2_PDDES`	`D2_PDDES`
`D2_DIFAL`	`D2_PDIFAL`
`D2_BSFCCMP`	`D2_BSFCCMP`
`D2_ALFCCMP`	`D2_ALFCCMP`
`D2_VFCPDIF`	`D2_VFCPDIF`
`D2_CCUSTO`	`D2_CC`
`D2_CONTA`	`D2_CONTA`
`D2_PESO`	`D2_PESO`
`D2_ESTOQUE`	`D2_ESTOQUE`
`D2_NFORI`	`D2_NFORI`
`D2_SERIORI`	`D2_SERIORI`
`D2_ITEMORI`	`D2_ITEMORI`
`D2_XPRMDPR`	`D2_XPRMDPR`
`D2_XALIQBA`	`D2_XALIQBA`
`D2_ORIGLAN`	`D2_ORIGLAN`
`D2_OP`	`D2_OP`

Exemplo de payload (com todos os campos previstos em $field):

{
  "F2_FILIAL": "",
  "F2_DOC": "",
  "F2_SERIE": "",
  "F2_CLIENTE": "",
  "F2_LOJA": "",
  "F2_TIPOCLI": "",
  "F2_EST": "",
  "F2_DUPL": "",
  "F2_EMISSAO": "",
  "F2_DTDIGIT": "",
  "F2_ESPECIE": "",
  "F2_TIPO": "",
  "F2_COND": "",
  "F2_XNATOPE": "",
  "F2_XCANAL": "",
  "F2_XNATUR": "",
  "F2_TPFRETE": "",
  "F2_VALMERC": 0,
  "F2_VALBRUT": 0,
  "F2_FRETE": 0,
  "F2_SEGURO": 0,
  "F2_DESPESA": 0,
  "F2_DESCONT": 0,
  "F2_VALFAT": 0,
  "F2_PREFIXO": "",
  "F2_VALICM": 0,
  "F2_BASEICM": 0,
  "F2_ICMFRET": 0,
  "F2_VALIPI": 0,
  "F2_BASEIPI": 0,
  "F2_ICMSRET": 0,
  "F2_BRICMS": 0,
  "F2_BASIMP5": 0,
  "F2_VALIMP5": 0,
  "F2_BASIMP6": 0,
  "F2_VALIMP6": 0,
  "F2_BASFECP": 0,
  "F2_BSFCCMP": 0,
  "F2_BSFCPST": 0,
  "F2_BASEPS3": 0,
  "F2_VALPS3": 0,
  "F2_BASECF3": 0,
  "F2_VALCF3": 0,
  "F2_MOEDA": 0,
  "F2_NFORI": "",
  "F2_SERIORI": "",
  "F2_UFDEST": "",
  "F2_UFORIG": "",
  "F2_ESPECI1": "",
  "F2_VOLUME1": 0,
  "F2_PLIQUI": 0,
  "F2_PBRUTO": 0,
  "F2_TRANSP": "",
  "F2_SDOC": "",
  "F2_CHVNFE": "",
  "F2_DAUTNFE": "",
  "F2_HAUTNFE": "",
  "F2_XVENPRE": "",
  "F3_PROTOC": "",
  "C5_PARC1": 0,
  "C5_PARC2": 0,
  "C5_PARC3": 0,
  "C5_PARC4": 0,
  "C5_PARC5": 0,
  "C5_PARC6": 0,
  "C5_PARC7": 0,
  "C5_PARC8": 0,
  "C5_PARC9": 0,
  "C5_PARC10": 0,
  "C5_PARC11": 0,
  "C5_PARC12": 0,
  "C5_DATA1": "",
  "C5_DATA2": "",
  "C5_DATA3": "",
  "C5_DATA4": "",
  "C5_DATA5": "",
  "C5_DATA6": "",
  "C5_DATA7": "",
  "C5_DATA8": "",
  "C5_DATA9": "",
  "C5_DATA10": "",
  "C5_DATA11": "",
  "C5_DATA12": "",
  "F3_DTCANC": "",
  "F3_CODRSEF": "",
  "CREPROCESSA": "",
  "ITENS": [
    {
      "D2_FILIAL": "",
      "D2_ITEM": "",
      "D2_COD": "",
      "D2_TP": "",
      "D2_UM": "",
      "D2_LOCAL": "",
      "D2_QUANT": 0,
      "D2_PRCVEN": 0,
      "D2_PRUNIT": 0,
      "D2_TOTAL": 0,
      "D2_DESC": 0,
      "D2_DESCON": 0,
      "D2_SEGURO": 0,
      "D2_VALFRE": 0,
      "D2_DESPESA": 0,
      "D2_VALBRUT": 0,
      "D2_EMISSAO": "",
      "D2_DTDIGIT": "",
      "D2_DOC": "",
      "D2_SERIE": "",
      "D2_SDOC": "",
      "D2_TIPO": "",
      "D2_ESPECIE": "",
      "D2_CLIENTE": "",
      "D2_LOJA": "",
      "D2_EST": "",
      "D2_CLASFIS": "",
      "D2_TES": "",
      "D2_CF": "",
      "D2_BASEIPI": 0,
      "D2_IPI": 0,
      "D2_VALIPI": 0,
      "D2_BASEICM": 0,
      "D2_PICM": 0,
      "D2_VALICM": 0,
      "D2_BASFECP": 0,
      "D2_ALQFECP": 0,
      "D2_VALFECP": 0,
      "D2_BRICMS": 0,
      "D2_ALIQSOL": 0,
      "D2_MARGEM": 0,
      "D2_ICMSRET": 0,
      "D2_BSFCPST": 0,
      "D2_ALFCPST": 0,
      "D2_VFECPST": 0,
      "D2_BASIMP5": 0,
      "D2_ALQIMP5": 0,
      "D2_VALIMP5": 0,
      "D2_BASIMP6": 0,
      "D2_ALQIMP6": 0,
      "D2_VALIMP6": 0,
      "D2_BASEPS3": 0,
      "D2_ALIQPS3": 0,
      "D2_VALPS3": 0,
      "D2_BASECF3": 0,
      "D2_ALIQCF3": 0,
      "D2_VALCF3": 0,
      "D2_DESCZFP": 0,
      "D2_DESCZFC": 0,
      "D2_BASEDES": 0,
      "D2_ALIQCMP": 0,
      "D2_PDORI": 0,
      "D2_PDDES": 0,
      "D2_DIFAL": 0,
      "D2_BSFCCMP": 0,
      "D2_ALFCCMP": 0,
      "D2_VFCPDIF": 0,
      "D2_CCUSTO": "",
      "D2_CONTA": "",
      "D2_PESO": 0,
      "D2_ESTOQUE": "",
      "D2_NFORI": "",
      "D2_SERIORI": "",
      "D2_ITEMORI": "",
      "D2_XPRMDPR": 0,
      "D2_XALIQBA": 0,
      "D2_ORIGLAN": "",
      "D2_OP": ""
    }
  ]
}

Tratamento de Dados

- Normalização numérica (cabeçalho): F2_VALMERC, F2_VALBRUT, F2_FRETE, F2_DESPESA, F2_SEGURO, F2_DESCONT, F2_VALFAT, F2_VALICM, F2_BASEICM, F2_ICMFRET, F2_VALIPI, F2_BASEIPI, F2_ICMSRET, F2_BRICMS, F2_BASIMP5, F2_VALIMP5, F2_BASIMP6, F2_VALIMP6, F2_BASFECP, F2_BSFCCMP, F2_BSFCPST, F2_BASEPS3, F2_VALPS3, F2_BASECF3, F2_VALCF3, F2_MOEDA, F2_VOLUME1, F2_PLIQUI, F2_PBRUTO, C5_PARC1 a C5_PARC12: normalizados via setNumeric().

- Normalização numérica com precisão específica (itens): D2_QUANT normalizado com 3 casas decimais (setNumeric(..., 3, false)); D2_PRCVEN, D2_PRUNIT normalizados com 5 casas decimais (setNumeric(..., 5, false)).

- Normalização numérica (itens): D2_TOTAL, D2_DESC, D2_DESCON, D2_SEGURO, D2_VALFRE, D2_DESPESA, D2_VALBRUT, D2_BASEIPI, D2_IPI, D2_VALIPI, D2_BASEICM, D2_PICM, D2_VALICM, D2_BASFECP, D2_ALQFECP, D2_VALFECP, D2_BRICMS, D2_ALIQSOL, D2_MARGEM, D2_ICMSRET, D2_BSFCPST, D2_ALFCPST, D2_VFECPST, D2_BASIMP5, D2_ALQIMP5, D2_VALIMP5, D2_BASIMP6, D2_ALQIMP6, D2_VALIMP6, D2_BASEPS3, D2_ALIQPS3, D2_VALPS3, D2_BASECF3, D2_ALIQCF3, D2_VALCF3, D2_DESCZFP, D2_DESCZFC, D2_BASEDES, D2_ALIQCMP, D2_XPRMDPR, D2_XALIQBA, D2_PDORI, D2_PDDES, D2_DIFAL, D2_BSFCCMP, D2_ALFCCMP, D2_VFCPDIF, D2_PESO: normalizados via setNumeric().

- Reestruturação de itens duplicados: quando houver D2_ITEM repetido em ITENS, os itens são renumerados sequencialmente (1, 2, 3, ...) para evitar conflito com o Protheus.

- Validação pré-integração (documento tipo devolução): quando F2_TIPO for igual a D, é construída a lista de chaves de documento de entrada (D2_FILIAL-D2_NFORI-D2_SERIORI-D2_CLIENTE-D2_LOJA) a partir dos itens e validada a integração de cada documento de entrada antes de prosseguir; em caso de falha, o item é suspenso com suspensaoTipo = ProtheusDocumentoEntrada e situacao = 3.

- Cabeçalho de integração: o header tenantId é gerado como <UF>,<F2_FILIAL>, em que <UF> é o prefixo de 2 caracteres de F2_FILIAL.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: documento_saida
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF>,<F2_FILIAL>, em que <UF> é o prefixo de 2 caracteres de F2_FILIAL
- Exemplo de payload enviado:
  - O payload é composto pelos campos do cabeçalho (F2_*, C5_*, F3_*, CREPROCESSA) e pela lista ITENS, conforme o mapeamento em "Estruturação de Dados".
  - Exemplo de payload: ver o JSON completo apresentado em "Estruturação de Dados".
- Tratamento de retorno:
  - Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como erro (situacao = 4).
  - Resposta inválida/inesperada: quando não for possível obter Mensagem ou o retorno não for array, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..
  - Indicadores de sucesso/erro: considera erro quando Mensagem for igual a ERRO ou quando code estiver presente (não vazio). Em ambos os casos, situacao = 4. Sucesso quando Mensagem for OK e code estiver vazio ou ausente, finalizando com situacao = 2.
  - Tratamento especial: quando a mensagem detalhada contiver o padrão "ja cadastrado" (case insensitive), o retorno é considerado sucesso (Mensagem ajustado para OK e code removido se existir).
  - Mensagem detalhada: prioriza Mensagem Detalhada quando disponível; se for array, extrai de erros tipo ou erros devolucao[0].mensagem conforme o caso.
- Reprocessamento em cenário de erro: quando houver falha na validação pré-integração (cliente ou documento de entrada não integrado), o item é marcado como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave para encaminhamento posterior.

Rotinas Inteligentes

- Cliente Integrado: chamada antes de enviar o documento ao Protheus, com chave F2_LOJA-F2_CLIENTE. Garante que o cliente esteja integrado antes de prosseguir com a integração do documento.
link: Cliente Integrado

- Documento de Saida Integrado: chamada em caso de sucesso da integração, com chave F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA. Registra o documento como integrado para controle de duplicidade.
link: Documento de Saida Integrado

- Documento de Cancelamento de Saida: chamada em caso de sucesso da integração, com chave F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA. Registra o documento de cancelamento para controle.
link: Documento de Cancelamento de Saida

Tratamento de retorno

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada (priorizando Mensagem Detalhada quando disponível), a situação final (situacao = 2 em sucesso, situacao = 3 em suspensão, situacao = 4 em erro) e o tempo de processamento.

Encaminhamento em cenário de erro

Quando houver falha por ausência de resposta, retorno inválido, Mensagem igual a ERRO ou presença de code, o item permanece registrado em wosk_queue com detalhes do retorno e mensagem para acompanhamento e eventual reprocessamento. Em caso de suspensão (cliente ou documento de entrada não integrado), o item é marcado com situacao = 3 e suspensaoTipo/suspensaoChave para encaminhamento posterior.

Notificação

A notificação de erros consulta itens com falha na tabela wosk_queue (serviço ProtheusDocumentoSaidaPontual e situação de erro), ordenando pela data de processamento para priorizar ocorrências mais antigas.

Para apresentação, higieniza a mensagem quando identificar padrão de erro de SQL Server (mantém apenas o trecho após [SQL Server] e antes de Error :), remove o prefixo antes do primeiro : quando existir, normaliza quebras de linha (\r, \n) e formata as datas data_adicionado e data para d/m/Y H:i:s. O relatório inclui as colunas: CAPTURADO EM, F2_FILIAL, F2_DOC, F2_SERIE, F2_CLIENTE, F2_LOJA, F2_TIPO, F2_XNATOPE, MSG ERRO, PROCESSADO EM.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e controle de posição	Ao consultar a view `WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_PONTUAL` com filtro por `DATA_PARA_TRANSFERENCIA` no intervalo do dia, ordenação ascendente e paginação por `OFFSET/FETCH`, deve manter a 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 para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma ou mais chaves no padrão `F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA-F2_TIPO-F2_XNATOPE`, deve consultar a origem filtrando por esses campos e carregar os itens da view `WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_ITEM_PONTUAL` antes de registrar o item para processamento.	Item pendente registrado com `ITENS` carregados quando a chave for válida.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em `wosk_queue` (serviço `ProtheusDocumentoSaidaPontual`), deve validar cliente integrado, aplicar transformações numéricas e de itens, enviar requisição `POST` para o recurso `documento_saida` com o payload completo (cabeçalho + `ITENS`) e registrar retorno, mensagem e situação final.	Item atualizado em `wosk_queue` com retorno/mensagem e situação final coerente (sucesso quando `Mensagem` for `OK` e `code` estiver vazio ou ausente; erro quando não houver resposta, não houver `Mensagem` ou `Mensagem` for `ERRO` ou `code` estiver presente; suspensão quando cliente ou documento de entrada não integrado).