ProtheusCupomFiscal (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza a captura e o envio de cupons fiscais do LINX para o Protheus, garantindo que cada registro seja identificado, enriquecido com seus detalhes e encaminhado para integração.

Capturador

Descrição Conceitual

O capturador consulta a view de origem de cupons fiscais pendentes, respeitando limite configurado de lote, e prepara a chave lógica do registro no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA para rastreio.

Para cada registro encontrado, o capturador enriquece o conteúdo com itens, parcelas e dados de troca (quando aplicável) e registra o item para processamento assíncrono, mantendo controle de posição e situação de execução.

Fonte

Destaque: a instrução SELECT {{TOP}} é usada para controlar a captura em lotes (semáforo). link: Conceito de Semáforo

Query base (origem):

SELECT {{TOP}}
  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,
  LQ_XCBSIBS,
  NUMERO_FISCAL_TROCA,
  SERIE_NF_ENTRADA,
  LQ_SERSAT,
  CREPROCESSA,
  DATA_PARA_TRANSFERENCIA
FROM
  WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM (NOLOCK)

Filtro aplicado no fluxo:

... WHERE CAPTURADO_ISNAPP = 0

Queries auxiliares (enriquecimento do registro):

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,
  LR_XCBSBS,
  LR_XCBSAL,
  LR_XCBSVL,
  LR_XIBSBS,
  LR_XIBSAL,
  LR_XIBSVL,
  DATA_PARA_TRANSFERENCIA
FROM
  WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM (NOLOCK)
WHERE
  LR_FILIAL = '<LR_FILIAL>'
  AND LR_DOC = '<LR_DOC>'
  AND LR_SERIE = '<LR_SERIE>'
  AND LR_CLIENTE = '<LR_CLIENTE>'
  AND LR_LOJA = '<LR_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 (NOLOCK)
WHERE
  L4_FILIAL = '<L4_FILIAL>'
  AND L4_DOC = '<L4_DOC>'
  AND L4_SERIE = '<L4_SERIE>'
  AND L4_CLIENTE = '<L4_CLIENTE>'
  AND L4_LOJA = '<L4_LOJA>'

Operações com Dados

Leitura: consulta registros pendentes na view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM e complementa o registro com dados de WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_ITEM e WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PGTO (além de fontes de troca quando houver).

Persistência do controle de posição: o estado do capturador (offset, chave de posição, filtros, situação e datas) é persistido na tabela wosk_monitor do banco integrador, permitindo retomada e rastreabilidade do processamento.

Captura manual: quando uma chave é informada (string ou lista), o capturador monta dinamicamente o WHERE com LQ_FILIAL, LQ_DOC e LQ_SERIE obrigatórios, e LQ_CLIENTE/LQ_LOJA opcionais, para recuperar o(s) registro(s) exato(s) e encaminhar para processamento.

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.

No processamento, o registro da fila passa por validações e rotinas de dependência (por exemplo, garantir que o cliente e cupons relacionados estejam integrados). O resultado (sucesso, erro, suspensão por dependência ou aguardo de callback) é persistido de volta na própria fila para auditoria.

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": "",
  "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_SERSAT": "",
  "LQ_TPFRET": "",
  "LQ_XCBSIBS": "",
  "CREPROCESSA": "",
  "ITENS": [
    {
      "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": "",
      "LR_XCBSBS": "",
      "LR_XCBSAL": "",
      "LR_XCBSVL": "",
      "LR_XIBSBS": "",
      "LR_XIBSAL": "",
      "LR_XIBSVL": ""
    }
  ],
  "PARCELAS": [
    {
      "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": ""
    }
  ],
  "CAB_DEV": [
    {
      "F1_FILIAL": "",
      "F1_DOC": "",
      "F1_FORNECE": "",
      "F1_LOJA": "",
      "F1_COND": "",
      "F1_XNATUR": "",
      "F1_DUPL": "",
      "F1_EMISSAO": "",
      "F1_DTDIGIT": "",
      "F1_RECBMTO": "",
      "F1_EST": "",
      "F1_ESTPRES": "",
      "F1_TIPO": "",
      "F1_FORMUL": "",
      "F1_ESPECIE": "",
      "F1_VALMERC": "",
      "F1_VALBRUT": "",
      "F1_FRETE": "",
      "F1_DESPESA": "",
      "F1_SEGURO": "",
      "F1_BASEICM": "",
      "F1_VALICM": "",
      "F1_BASEIPI": "",
      "F1_VALIPI": "",
      "F1_BRICMS": "",
      "F1_ICMSRET": "",
      "F1_BASIMP5": "",
      "F1_VALIMP5": "",
      "F1_BASIMP6": "",
      "F1_VALIMP6": "",
      "F1_MUORITR": "",
      "F1_UFORITR": "",
      "F1_MUDESTR": "",
      "F1_UFDESTR": "",
      "F1_II": "",
      "F1_TIPO_NF": "",
      "F1_CHVNFE": "",
      "F1_DAUTNFE": "",
      "F1_HAUTNFE": "",
      "F1_NFELETR": "",
      "F1_EMINFE": "",
      "F1_HORNFE": "",
      "F1_TPFRETE": "",
      "F1_TPCTE": "",
      "F1_ORIGLAN": "",
      "F1_NFORIG": "",
      "F1_SERORIG": "",
      "F1_NUMTRIB": "",
      "F1_MOEDA": "",
      "F1_PREFIXO": "",
      "F1_STATUS": "",
      "F1_SDOC": "",
      "F1_TRANSP": "",
      "F1_XNATOPE": "",
      "F1_XCANAL": "",
      "F3_DTCANC": "",
      "F3_CODRSEF": "",
      "F1_XCBSIBS": "",
      "F1_SERIE": "",
      "F1_DESCONT": "",
      "F1_BASEPS3": "",
      "F1_VALPS3": "",
      "F1_BASECF3": "",
      "F1_VALCF3": "",
      "F1_CIF": "",
      "F3_PROTOC": "",
      "F1_PLIQUI": "",
      "F1_PBRUTO": "",
      "F1_ESPECI1": "",
      "F1_VOLUME1": "",
      "ITENS_DEV": [
        {
          "D1_FILIAL": "",
          "D1_ITEM": "",
          "D1_COD": "",
          "D1_TEC": "",
          "D1_QUANT": "",
          "D1_VUNIT": "",
          "D1_TOTAL": "",
          "D1_DESC": "",
          "D1_VALDESC": "",
          "D1_SEGURO": "",
          "D1_VALFRE": "",
          "D1_DESPESA": "",
          "D1_EMISSAO": "",
          "D1_DTDIGIT": "",
          "D1_DOC": "",
          "D1_SERIE": "",
          "D1_TIPO": "",
          "D1_FORNECE": "",
          "D1_LOJA": "",
          "D1_CLASFIS": "",
          "D1_OPER": "",
          "D1_CF": "",
          "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_TIPO_NF": "",
          "D1_OP": "",
          "D1_CC": "",
          "D1_CONTA": "",
          "D1_PESO": "",
          "D1_DATORI": "",
          "D1_NFORI": "",
          "D1_SERIORI": "",
          "D1_ITEMORI": "",
          "D1_ORIGLAN": "",
          "DKD_XCBSBS": "",
          "DKD_XCBSAL": "",
          "DKD_XCBSVL": "",
          "DKD_XIBSBS": "",
          "DKD_XIBSAL": "",
          "DKD_XIBSVL": "",
          "D1_TP": "",
          "D1_UM": "",
          "D1_LOCAL": "",
          "D1_GRUPO": "",
          "D1_SDOC": ""
        }
      ]
    }
  ]
}

Tratamento de Dados

Padronização numérica (cupom): os campos 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 são normalizados para formato numérico antes do envio.

Padronização numérica (itens): em cada item de ITENS, os campos 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, LR_XCBSBS, LR_XCBSAL, LR_XCBSVL, LR_XIBSBS, LR_XIBSAL, LR_XIBSVL são normalizados para formato numérico antes do envio.

Padronização numérica (parcelas): em PARCELAS, os campos L4_VALOR, L4_XTOTPAR, L4_MOEDA são normalizados para formato numérico.

Padronização numérica (troca/devolução - CAB_DEV): quando houver troca/devolução, no bloco CAB_DEV os campos 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 para formato numérico.

Padronização numérica (troca/devolução - ITENS_DEV): no bloco CAB_DEV.ITENS_DEV, os campos D1_QUANT, D1_VUNIT, 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, DKD_XCBSBS, DKD_XCBSAL, DKD_XCBSVL, DKD_XIBSBS, DKD_XIBSAL, DKD_XIBSVL são normalizados para formato numérico (com precisãconfiguração diferenciadade paracasas decimais específica: D1_QUANT é arredondado/normalizado com 3 casas decimais e D1_VUNIT) é arredondado/normalizado com 5 casas decimais; em ambos os campos, a rotina aplica a normalização com removerInteiro = false.

Reindexação de item em troca: quando há itens duplicados em CAB_DEV.ITENS_DEV, o campo D1_ITEM é reatribuído em sequência crescente para garantir unicidade no envio.

Integração com o Protheus

Chamada: Requisição HTTP
Recurso: cupom
Método HTTP: POST
Cabeçalhos:
tenantId: <prefixo_filial_2_chars>,<LQ_FILIAL> (onde <prefixo_filial_2_chars> é formado pelos 2 primeiros caracteres de LQ_FILIAL)

Exemplo de payload enviado:
O payload segue a mesma estrutura definida na seção “Estruturação de Dados” (incluindo ITENS, PARCELAS e CAB_DEV quando aplicável).

Tratamento de retorno:
- Ausência de resposta: retorna erro JSON: NÃO HOUVE RESPOSTA.
- Resposta inválida/inesperada: retorna erro JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Erro identificado: considera falha quando existir code no retorno ou quando Mensagem for ERRO.
- Sucesso: considera sucesso quando não há sinalização de erro e Mensagem não é ERRO.
- Aguardo de callback: em sucesso, se o retorno contiver ZB_FILIAL e ZB_ID, e ZB_DATRET estiver vazio, registra controle de callback e define mensagem Aguardando Processamento no Protheus.
- Reclassificação de erro para sucesso: quando a mensagem detalhada contém indicação de “já cadastrado”, o processamento é tratado como sucesso (ajuste de status e limpeza do indicador code, quando presente).

Encaminhamento em cenário de erro:
- Dependência de integração de cliente: ao identificar cliente não integrado, o item fica suspenso por dependência (registrando tipo/chave de suspensão do cliente).
- Dependência de integração de cupons relacionados à troca: ao identificar cupons de origem não integrados, o item fica suspenso por dependência (registrando tipo/chave do primeiro cupom pendente).
- Falhas gerais de envio/retorno: o item é registrado como erro, preservando mensagem e retorno de erro para auditoria.

Tratamento de retorno

Persistência do resultado: o resultado do processamento é persistido na tabela wosk_queue (banco integrador), atualizando o registro com retorno da integração, mensagem, tempo e situação final.

Estados principais do item na fila (situação):
- 1: enviando/processing iniciada
- 2: sucesso
- 3: suspenso por dependência (cliente/cupom relacionado)
- 4: erro
- 5: aguardando processamento via callback

Ações adicionais em sucesso: quando o item é concluído com sucesso, o processo registra integrações relacionadas (e-commerce e cancelamento) e marca o cupom como integrado no contexto de integração.

Encaminhamento em cenário de erro

Quando uma dependência de integração é identificada (cliente ou cupom de origem de troca), o item é suspenso para evitar envio inconsistente e permitir reprocessamento após a integração da dependência. Em falhas de comunicação/retorno, o erro é persistido com a mensagem resultante e o conteúdo do retorno para auditoria.

Notificação

SELECT
  `token`,
  `acao`,
  `chave`,
  `data_adicionado`,
  `data`,
  `mensagem` AS 'ERRO'
FROM
  `<banco_integrador>`.`wosk_queue`
WHERE
  `acao` = 'ProtheusCupomFiscal' AND `situacao` = 4
ORDER BY
  `data` ASC

Rotinas Inteligentes

Rotinas inteligentes identificadas no fluxo:

setProtheusClienteIntegrado: antes do envio do cupom, ao validar a dependência de integração do cliente. Garante que o cliente esteja apto para integração do cupom.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/setprotheusclienteintegrado

setProtheusCupomFiscalIntegrado: antes do envio do cupom, ao validar cupons relacionados a trocas/devoluções. Evita envio de cupom com dependência pendente.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/setprotheuscupomfiscalintegrado

setProtheusCupomEcommerceIntegrado: após sucesso no envio do cupom, ao registrar integrações relacionadas. Mantém consistência de integração entre processos de cupom.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/setprotheuscupomecommerceintegrado

setProtheusDocumentoCancelamentoCupomFiscal: após sucesso no envio do cupom, ao registrar o estado de cancelamento relacionado. Evita divergências de status entre documento e cupom.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/setprotheusdocumentocancelamentocupomfiscal

Fluxo do Processo

Critérios de Aceitação