ProtheusCupomFiscalOmni (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca organiza a integração de cupons fiscais omni do LINX para o Protheus, garantindo que cada cupom seja capturado com itens e parcelas, preparado e encaminhado para envio, incluindo suporte a devolução de troca quando aplicável.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais cupons fiscais omni mediante a informação das chaves no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA, consultando a origem e carregando itens e parcelas antes de registrar o item para processamento assíncrono. Caso a chave informada esteja fora do padrão (menos de 5 partes), o processo é interrompido com erro de chave inválida.

A captura por data consulta a origem filtrando por DATA_PARA_TRANSFERENCIA, 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_CUPOM_OMNI, view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM_OMNI e view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PGTO_OMNI.

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

SELECT
    LQ_FILIAL,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_NOMCLI,
    LQ_TIPOCLI,
    LQ_VEND,
    LQ_EMISSAO,
    LQ_DOC,
    LQ_EMISNF,
    LQ_NUMCFIS,
    LQ_SERIE,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_CARTAO,
    LQ_VLRDEBI,
    LQ_OUTROS,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PARCELA,
    LQ_PDV,
    LQ_VENDTEF,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    LQ_VALICM,
    LQ_FRETE,
    LQ_DESPESA,
    LQ_SEGURO,
    LQ_TPFRET,
    NUMERO_FISCAL_TROCA,
    SERIE_NF_ENTRADA,
    LQ_SERSAT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_OMNI (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<data_posicao>'
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_CUPOM_OMNI)
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_OMNI (NOLOCK)
WHERE
    LQ_FILIAL = '<chave[0]>'
    AND LQ_DOC = '<chave[1]>'
    AND LQ_SERIE = '<chave[2]>'
    AND LQ_CLIENTE = '<chave[3]>'
    AND LQ_LOJA = '<chave[4]>'

Consulta utilizada para carregar os itens do cupom (WHERE construído dinamicamente a partir de LR_FILIAL, LR_DOC, LR_SERIE, LR_CLIENTE, LR_LOJA):

SELECT
    LR_FILIAL,
    LR_PRODUTO,
    LR_DESCRI,
    LR_POSIPI,
    LR_ORIGEM,
    LR_QUANT,
    LR_UM,
    LR_TABELA,
    LR_VRUNIT,
    LR_VLRITEM,
    LR_ENTREGA,
    LR_PRCTAB,
    LR_VEND,
    LR_TES,
    LR_CF,
    LR_CLASFIS,
    LR_DESC,
    LR_VALDESC,
    LR_DESCPRO,
    LR_LOCAL,
    LR_DOC,
    LR_SERIE,
    LR_CLIENTE,
    LR_LOJA,
    LR_BASEPS2,
    LR_ALIQPS2,
    LR_VALPS2,
    LR_BASECF2,
    LR_ALIQCF2,
    LR_VALCF2,
    LR_BASEICM,
    LR_PICM,
    LR_VALICM,
    LR_PREDIC,
    LR_XBASECMP,
    LR_XALIQCMP,
    LR_XVLRCMP,
    LR_CCUSTO,
    LR_ALQFECP,
    LR_VALFECP,
    LR_VALFRE,
    LR_SEGURO,
    LR_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM_OMNI (NOLOCK)
WHERE
    LR_FILIAL = '<LQ_FILIAL>'
    AND LR_DOC = '<LQ_DOC>'
    AND LR_SERIE = '<LQ_SERIE>'
    AND LR_CLIENTE = '<LQ_CLIENTE>'
    AND LR_LOJA = '<LQ_LOJA>'

Consulta utilizada para carregar as parcelas de pagamento (WHERE construído dinamicamente a partir de L4_FILIAL, L4_DOC, L4_SERIE, L4_CLIENTE, L4_LOJA):

SELECT
    L4_FILIAL,
    L4_DOC,
    L4_SERIE,
    L4_CLIENTE,
    L4_LOJA,
    L4_DATA,
    L4_VALOR,
    L4_ADMINIS,
    L4_XTOTPAR,
    L4_VENDTEF,
    L4_DATATEF,
    L4_DOCTEF,
    L4_AUTORIZ,
    L4_NSUTEF,
    L4_NUMCART,
    L4_FORMA,
    L4_FORMAID,
    L4_MOEDA,
    L4_XBANCO,
    L4_AGENCIA,
    L4_XDIGAG,
    L4_XCONTA,
    L4_XDIGCONT,
    L4_XNSU,
    L4_XAUTORI,
    L4_XTID,
    L4_XPEDIDO,
    L4_XIDERP,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PGTO_OMNI (NOLOCK)
WHERE
    L4_FILIAL = '<LQ_FILIAL>'
    AND L4_DOC = '<LQ_DOC>'
    AND L4_SERIE = '<LQ_SERIE>'
    AND L4_CLIENTE = '<LQ_CLIENTE>'
    AND L4_LOJA = '<LQ_LOJA>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_OMNI para obter o registro atual do cupom e construir o identificador de processamento com base em LQ_FILIAL, LQ_DOC, LQ_SERIE, LQ_CLIENTE e LQ_LOJA.

- Carregamento de itens: para cada registro atual, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM_OMNI filtrando por LR_FILIAL, LR_DOC, LR_SERIE, LR_CLIENTE, LR_LOJA e agrega os itens retornados no campo ITENS.

- Carregamento de parcelas: para cada registro atual, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PGTO_OMNI filtrando por L4_FILIAL, L4_DOC, L4_SERIE, L4_CLIENTE, L4_LOJA e agrega as parcelas no campo PARCELAS.

- Inicialização de CAB_DEV: o campo CAB_DEV é inicializado como array vazio para eventual preenchimento de dados de devolução de troca.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusCupomFiscalOmni, 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 = 'ProtheusCupomFiscalOmni', 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 cupom capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusCupomFiscalOmni, com o conteúdo vindo da origem (incluindo ITENS, PARCELAS e CAB_DEV) 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.

Estruturação de Dados

{
  "LQ_FILIAL": "",
  "LQ_CLIENTE": "",
  "LQ_LOJA": "",
  "LQ_NOMCLI": "",
  "LQ_TIPOCLI": "",
  "LQ_VEND": "",
  "LQ_EMISSAO": "",
  "LQ_DOC": "",
  "LQ_EMISNF": "",
  "LQ_NUMCFIS": "",
  "LQ_SERIE": "",
  "LQ_ESPECIE": "",
  "LQ_XNATOPE": "",
  "LQ_XCANAL": "",
  "LQ_HORA": "",
  "LQ_KEYNFCE": "",
  "LQ_FORMA": "",
  "LQ_DINHEIR": 0,
  "LQ_CARTAO": 0,
  "LQ_VLRDEBI": 0,
  "LQ_OUTROS": 0,
  "LQ_FORMPG": "",
  "LQ_CONDPG": "",
  "LQ_OPERADO": "",
  "LQ_PARCELA": 0,
  "LQ_PDV": "",
  "LQ_VENDTEF": "",
  "LQ_SITUA": "",
  "LQ_VALMERC": 0,
  "LQ_VLRTOT": 0,
  "LQ_VLRLIQ": 0,
  "LQ_VALBRUT": 0,
  "LQ_VALICM": 0,
  "LQ_FRETE": 0,
  "LQ_DESPESA": 0,
  "LQ_SEGURO": 0,
  "LQ_SERSAT": "",
  "LQ_TPFRET": "",
  "ITENS": [
    {
      "LR_FILIAL": "",
      "LR_PRODUTO": "",
      "LR_DESCRI": "",
      "LR_POSIPI": "",
      "LR_ORIGEM": "",
      "LR_QUANT": 0,
      "LR_UM": "",
      "LR_TABELA": "",
      "LR_VRUNIT": 0,
      "LR_VLRITEM": 0,
      "LR_ENTREGA": "",
      "LR_PRCTAB": 0,
      "LR_VEND": "",
      "LR_TES": "",
      "LR_CF": "",
      "LR_CLASFIS": "",
      "LR_DESC": 0,
      "LR_VALDESC": 0,
      "LR_DESCPRO": 0,
      "LR_LOCAL": "",
      "LR_DOC": "",
      "LR_SERIE": "",
      "LR_CLIENTE": "",
      "LR_LOJA": "",
      "LR_BASEPS2": 0,
      "LR_ALIQPS2": 0,
      "LR_VALPS2": 0,
      "LR_BASECF2": 0,
      "LR_ALIQCF2": 0,
      "LR_VALCF2": 0,
      "LR_BASEICM": 0,
      "LR_PICM": 0,
      "LR_VALICM": 0,
      "LR_PREDIC": 0,
      "LR_XBASECMP": 0,
      "LR_XALIQCMP": 0,
      "LR_XVLRCMP": 0,
      "LR_CCUSTO": "",
      "LR_ALQFECP": 0,
      "LR_VALFECP": 0,
      "LR_VALFRE": 0,
      "LR_SEGURO": 0,
      "LR_DESPESA": 0
    }
  ],
  "PARCELAS": [
    {
      "L4_FILIAL": "",
      "L4_DOC": "",
      "L4_SERIE": "",
      "L4_CLIENTE": "",
      "L4_LOJA": "",
      "L4_DATA": "",
      "L4_VALOR": 0,
      "L4_ADMINIS": "",
      "L4_XTOTPAR": 0,
      "L4_VENDTEF": "",
      "L4_DATATEF": "",
      "L4_DOCTEF": "",
      "L4_AUTORIZ": "",
      "L4_NSUTEF": "",
      "L4_NUMCART": "",
      "L4_FORMA": "",
      "L4_FORMAID": "",
      "L4_MOEDA": 0,
      "L4_XBANCO": "",
      "L4_AGENCIA": "",
      "L4_XDIGAG": "",
      "L4_XCONTA": "",
      "L4_XDIGCONT": "",
      "L4_XNSU": "",
      "L4_XAUTORI": "",
      "L4_XTID": "",
      "L4_XPEDIDO": "",
      "L4_XIDERP": ""
    }
  ]
}

Tratamento de Dados

- Normalização numérica (cabeçalho): LQ_DINHEIR, LQ_CARTAO, LQ_VLRDEBI, LQ_OUTROS, LQ_PARCELA, LQ_VALMERC, LQ_VLRTOT, LQ_VLRLIQ, LQ_VALBRUT, LQ_VALICM, LQ_FRETE, LQ_DESPESA, LQ_SEGURO: normalizados via setNumeric().

- Normalização numérica (itens): LR_QUANT, LR_VRUNIT, LR_VLRITEM, LR_PRCTAB, LR_DESC, LR_VALDESC, LR_DESCPRO, LR_BASEPS2, LR_ALIQPS2, LR_VALPS2, LR_BASECF2, LR_ALIQCF2, LR_VALCF2, LR_BASEICM, LR_PICM, LR_VALICM, LR_PREDIC, LR_XBASECMP, LR_XALIQCMP, LR_XVLRCMP, LR_ALQFECP, LR_VALFECP, LR_VALFRE, LR_DESPESA, LR_SEGURO: normalizados via setNumeric().

- Normalização numérica (parcelas): L4_VALOR, L4_XTOTPAR, L4_MOEDA: normalizados via setNumeric().

- Normalização numérica (CAB_DEV - devolução de troca): quando CAB_DEV[0] estiver preenchido, os campos do cabeçalho de devolução F1_VALMERC, F1_VALBRUT, F1_FRETE, F1_DESPESA, F1_SEGURO, F1_DESCONT, F1_BASEICM, F1_VALICM, F1_BASEIPI, F1_VALIPI, F1_BRICMS, F1_ICMSRET, F1_BASIMP5, F1_VALIMP5, F1_BASIMP6, F1_VALIMP6, F1_BASEPS3, F1_VALPS3, F1_BASECF3, F1_VALCF3, F1_II, F1_CIF, F1_PLIQUI, F1_PBRUTO, F1_VOLUME1, F1_MOEDA são normalizados via setNumeric().

- Normalização numérica com precisão específica (ITENS_DEV em CAB_DEV): D1_QUANT normalizado com 3 casas decimais (setNumeric(..., 3, false)); D1_VUNIT normalizado com 5 casas decimais (setNumeric(..., 5, false)).

- Normalização numérica (ITENS_DEV em CAB_DEV): D1_TOTAL, D1_DESC, D1_VALDESC, D1_SEGURO, D1_VALFRE, D1_DESPESA, D1_BASEIPI, D1_IPI, D1_VALIPI, D1_BASEICM, D1_PICM, D1_VALICM, D1_VRDICMS, D1_VALANTI, D1_ICMSDIF, D1_BASFECP, D1_ALQFECP, D1_VALFECP, D1_ALIQCMP, D1_DIFAL, D1_BSFCCMP, D1_ALFCCMP, D1_VFCPDIF, D1_AFCPANT, D1_VFCPANT, D1_BRICMS, D1_ALIQSOL, D1_MARGEM, D1_ICMSRET, D1_BSFCPST, D1_ALFCPST, D1_VFECPST, D1_BASIMP5, D1_ALQIMP5, D1_VALIMP5, D1_BASIMP6, D1_ALQIMP6, D1_VALIMP6, D1_ALIQII, D1_II, D1_CIF, D1_PESO: normalizados via setNumeric().

- Validação pré-integração (cliente): chamada de setProtheusClienteIntegrado com chave LQ_LOJA-LQ_CLIENTE antes de prosseguir; em caso de falha, o item é suspenso com suspensaoTipo = ProtheusCliente e situacao = 3.

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

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: cupom
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF>,<LQ_FILIAL>, em que <UF> é o prefixo de 2 caracteres de LQ_FILIAL

Rotinas Inteligentes

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

- Cupom Ecommerce Integrado: chamada em caso de sucesso da integração, com chave do item de fila. Registra o cupom e-commerce como integrado para controle de duplicidade.
link: Cupom Ecommerce Integrado

- Cupom Fiscal Integrado: chamada em caso de sucesso da integração, com chave do item de fila. Registra o cupom fiscal como integrado para controle.
link: Cupom Fiscal Integrado

- Documento de Cancelamento de Cupom Fiscal: chamada em caso de sucesso da integração, com chave do item de fila. Registra o documento de cancelamento de cupom fiscal para controle.
link: Documento de Cancelamento de Cupom Fiscal

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 contiver o padrão "ja cadastrado" (case insensitive) e situacao for 4, o retorno é considerado sucesso (situacao ajustado para 2, Mensagem para OK e code removido se existir).

Aguardando callback: quando o retorno indicar sucesso (situacao = 2) e houver ZB_FILIAL, ZB_ID preenchidos e ZB_DATRET vazio, o item é registrado para aguardar processamento no Protheus via aguardandoRespostaCallback, com mensagem "Aguardando Processamento no Protheus" e situacao = 5.

Reprocessamento em cenário de erro: quando houver falha na validação pré-integração (cliente não integrado), o item é marcado como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave para encaminhamento posterior.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada, a situação final (situacao = 2 em sucesso, situacao = 3 em suspensão, situacao = 4 em erro, situacao = 5 aguardando processamento no Protheus) 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 não integrado), o item é marcado com situacao = 3 e suspensaoTipo/suspensaoChave para encaminhamento posterior.

Notificação

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_CUPOM_OMNI com filtro por DATA_PARA_TRANSFERENCIA, 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 com ITENS, PARCELAS e CAB_DEV para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma ou mais chaves no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA, deve consultar a origem filtrando por esses campos e carregar os itens da view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM_OMNI e parcelas da view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PGTO_OMNI antes de registrar o item para processamento.	Item pendente registrado com ITENS e PARCELAS carregados quando a chave for válida.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusCupomFiscalOmni), deve validar cliente integrado, aplicar transformações numéricas (cabeçalho, itens, parcelas e CAB_DEV quando houver devolução de troca), enviar requisição POST para o recurso cupom com o payload completo e registrar retorno, mensagem e situação final. Em sucesso, registra cupom e-commerce, cupom fiscal e documento de cancelamento de cupom fiscal como integrados.	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 não integrado; aguardando quando situacao = 5).