ProtheusDocumentoSaida (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_documento_saida
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 ProtheusDocumentoSaida.

Descrição

Este processo captura documentos de saída do LINX, estrutura seu conteúdo completo (cabeçalho e itens) e realiza a integração no Protheus.
O fluxo garante validações prévias, padronizações obrigatórias e registro do resultado de processamento na fila.

Capturador

Descrição Conceitual

Captura documentos de saída pendentes na origem e registra cada documento para processamento em fila, mantendo controle de posição (offset, chave e data) para evitar recapturas e garantir continuidade.

Além da captura automática por agendador de tarefas (quando houver registros pendentes na origem), permite captura manual por chave informada, montando filtros dinâmicos para localizar um documento específico e registrar seu conteúdo completo para integração.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS.
Observação: a consulta utiliza SELECT {{TOP}} para limitar lotes de captura (conceito de semáforo).
link: Semáforo

Operações com Dados

Leitura: consulta documentos com CAPTURADO_ISNAPP = 0 na origem, com limite configurável por lote, e para cada documento recupera seus itens antes de registrá-lo para processamento em fila.

Consulta principal (lote):

SELECT TOP {{TOP}}
    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,
    F2_XCODREP,
    F2_XCNPJRE,
    F2_XMARCA,
    F2_XCBSIBS,
    F2_DESCZFR,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS (NOLOCK)
WHERE
    CAPTURADO_ISNAPP = 0

Consulta de itens do documento:

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,
    D2_XPDWISE,
    D2_XPDLINX,
    D2_XCOLEC,
    D2_XCOLDE,
    D2_XIBSBS,
    D2_XIBSAL,
    D2_XIBSVL,
    D2_XCBSBS,
    D2_XCBSAL,
    D2_XCBSVL,
    D2_DESCZFR,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_ITEM (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}'

Captura manual: a consulta é montada dinamicamente conforme as partes informadas na chave (filial, documento, série e, opcionalmente, cliente/loja e natureza de operação):

SELECT
    -- (mesmas colunas da consulta principal)
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS (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}']
    [AND F2_XNATOPE = '{F2_XNATOPE}']

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.

Antes do envio, valida dependências (ex.: integração prévia do cliente) e ajusta consistências dos itens (ex.: renumeração de item quando houver duplicidade). Ao final, registra retorno, mensagem e situação para auditoria.

Estruturação de Dados

O payload enviado ao Protheus segue o schema definido na lista de campos da fila. Abaixo está o mapeamento oficial de origem → payload.

Cabeçalho do documento

ITENS

Exemplo de payload enviado

{
  "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_BASIMP6": 0,
  "F2_VALIMP5": 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": "",
  "F2_XCODREP": "",
  "F2_XCNPJRE": "",
  "F2_XMARCA": "",
  "F2_XCBSIBS": "",
  "F2_DESCZFR": 0,
  "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": "",
      "D2_XPDWISE": "",
      "D2_XPDLINX": "",
      "D2_XCOLEC": "",
      "D2_XCOLDE": "",
      "D2_XIBSBS": 0,
      "D2_XIBSAL": 0,
      "D2_XIBSVL": 0,
      "D2_XCBSBS": 0,
      "D2_XCBSAL": 0,
      "D2_XCBSVL": 0,
      "D2_DESCZFR": 0
    }
  ]
}

Tratamento de Dados

Antes do envio ao Protheus, o payload passa por validações e padronizações obrigatórias para consistência numérica e integridade dos itens.

Validação de dependência
- F2_CLIENTE, F2_LOJA: o processamento exige confirmação de integração prévia do cliente antes de prosseguir; em caso de falha, o item é marcado como suspenso por dependência.

Padronização numérica (setNumeric)
- 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, C5_PARC2, C5_PARC3, C5_PARC4, C5_PARC5, C5_PARC6, C5_PARC7, C5_PARC8, C5_PARC9, C5_PARC10, C5_PARC11, C5_PARC12, F2_DESCZFR: normalizados com o padrão do setNumeric(...).

- D2_QUANT: normalizado com 3 casas decimais (setNumeric(..., 3, false)).
- D2_PRCVEN, D2_PRUNIT: normalizado com 5 casas decimais (setNumeric(..., 5, false)).
- 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, D2_XIBSBS, D2_XIBSAL, D2_XIBSVL, D2_XCBSBS, D2_XCBSAL, D2_XCBSVL, D2_DESCZFR: normalizados com o padrão do setNumeric(...).

Consistência e reestruturação de itens
- D2_ITEM: quando o documento possui itens com numeração duplicada, os itens são renumerados sequencialmente (1..N) para evitar colisões no envio.
- D2_ITEMORI: quando D2_TIPO é devolução, o campo é ajustado com preenchimento à esquerda por zeros para atingir o tamanho esperado do item de origem, garantindo consistência no relacionamento com o documento de entrada de origem.

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: <primeiros 2 caracteres de F2_FILIAL>,<F2_FILIAL>

Tratamento de retorno
- Ausência de resposta: gera erro com mensagem JSON: NÃO HOUVE RESPOSTA.
- Resposta inválida/inesperada: se não for array ou não contiver Mensagem, gera erro com JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Ajuste de sucesso por mensagem: quando a mensagem detalhada contém indicação de “já cadastrado”, a resposta é tratada como sucesso (Mensagem = OK) e o campo code é removido (se existir).
- Condição de erro: quando existir code na resposta ou quando Mensagem = ERRO, o processamento é marcado como falha.
- Condição de sucesso: quando o retorno é considerado OK, o item é finalizado como sucesso e aciona marcadores correlatos (integrado/cancelamento) quando aplicável.

Rotinas Inteligentes

Cliente Integrado (rotina inteligente): chamada no início do processamento, antes de normalizar dados e integrar o documento de saída. Garante que o cliente do documento esteja integrado no Protheus para permitir o envio do documento.
link: Cliente Integrado

Documento de Saida Integrado (rotina inteligente): chamada após retorno de sucesso do envio do documento de saída. Registra/valida o status de integração do documento para manter consistência do processo.
link: Documento de Saida Integrado

Documento de Cancelamento de Saida (rotina inteligente): chamada após retorno de sucesso do envio do documento de saída. Encaminha o cancelamento correlato para manter o status consistente no Protheus.
link: Documento de Cancelamento de Saida

Tratamento de retorno

Persistência do resultado: o item processado é atualizado na tabela wosk_queue (base integrador), registrando retorno, mensagem, requisicao, tempo, situacao e, quando existir, informações de suspensão por dependência.

Situações utilizadas:
- 1: Em envio.
- 2: Sucesso.
- 3: Suspenso por dependência.
- 4: Erro.

Encaminhamento em cenário de erro

Quando a falha ocorre por dependência prévia (ex.: cliente ainda não integrado), o item pode ser marcado como suspenso, mantendo tipo e chave de dependência para rastreio. Demais falhas permanecem como erro com mensagem registrada para correção e reprocessamento.

Notificação

SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem` AS 'ERRO'
FROM
    `{BASE_INTEGRADOR}`.`wosk_queue`
WHERE
    `acao` = 'ProtheusDocumentoSaida'
    AND `situacao` = 4
ORDER BY
    `data` ASC

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura e registro na fila	Ao identificar registros pendentes na origem (CAPTURADO_ISNAPP = 0) na view WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS, deve estruturar a chave no padrão F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA-F2_TIPO-F2_XNATOPE, anexar ITENS e registrar o item para processamento.	Item pendente registrado em wosk_queue, com conteúdo completo e chave consistente.
Fila de Processamento	Validação de dependência	Antes de enviar o documento de saída, deve validar que o cliente (F2_CLIENTE/F2_LOJA) está integrado no Protheus; em falha, deve suspender o item registrando tipo e chave de dependência.	Item permanece em estado suspenso (situacao = 3) com informações para rastreio, sem tentativa de envio.
Fila de Processamento	Normalização e consistência de itens	Ao processar um item pendente, deve normalizar campos numéricos do cabeçalho e itens, aplicar precisão diferenciada para D2_QUANT (3 casas, false) e D2_PRCVEN/D2_PRUNIT (5 casas, false), e renumerar D2_ITEM quando houver duplicidade.	Payload consistente e pronto para envio, com itens numerados corretamente e valores padronizados.
Fila de Processamento	Integração e persistência do retorno	Após enviar ao Protheus (POST no recurso documento_saida com header tenantId), deve validar a resposta, tratar “já cadastrado” como sucesso, e registrar em wosk_queue o retorno, mensagem e situação final. Em sucesso, deve acionar marcadores correlatos (integrado/cancelamento).	Fila atualizada com situação final e detalhes para auditoria; em sucesso, documento marcado como integrado e cancelamento encaminhado.