ProtheusCupomFiscalPontual (STATUS: PARCIAL)
Documentação Técnica
| Nome do cliente | OSKLEN |
| Nome do projeto | Integração LINX → Protheus |
| Biblioteca | wosk_protheus_cupom_fiscal_pontual |
| Data | 02/03/2026 |
Histórico de Versões
| Data | Versão | Modificado por | Descrição da Mudança |
| 02/03/2026 | 1.0 | Maykon/Gustavo | Criação da documentação técnica do processo ProtheusCupomFiscalPontual. |
Descrição
Esta biblioteca organiza o envio de cupons fiscais do LINX para o Protheus em modo pontual, garantindo que cada documento seja coletado, preparado e encaminhado com controle de situação.
O processo inclui a composição de itens, pagamentos e informações de troca (quando aplicável), mantendo rastreabilidade do que foi processado e do resultado obtido.
Capturador
Descrição Conceitual
O capturador recupera documentos na origem WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PONTUAL e, para cada registro encontrado, monta uma chave de rastreio a partir de LQ_FILIAL, LQ_DOC, LQ_SERIE, LQ_CLIENTE e LQ_LOJA, no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA, para encaminhamento à fila de processamento. A captura pode ocorrer automaticamente (via agendador de tarefas) com paginação por data, caracterizando processamento por ordem temporal (ordenação/paginação por data).
Também permite captura manual informando a chave completa; nesse caso, o filtro é construído dinamicamente pelos cinco componentes da chave e, se a quantidade de partes for menor que 5, o processo é interrompido com erro de chave inválida, evitando enfileiramento incorreto.
Fonte
Origem consultada: WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PONTUAL.
Operações com Dados
Leitura: consulta o conjunto base de cupons na origem e aplica filtro por DATA_PARA_TRANSFERENCIA no intervalo do dia (início e fim), ordenando por data para garantir continuidade.
Reestruturação do registro atual: para cada cupom retornado, adiciona os grupos ITENS e PARCELAS com consultas complementares por chave (filial, documento, série, cliente, loja).
Condição de troca: se NUMERO_FISCAL_TROCA estiver preenchido, adiciona CAB_DEV com os dados do cabeçalho e inclui ITENS_DEV vinculados à troca.
Persistência: cada registro preparado é armazenado para processamento na tabela wosk_queue (integrador), identificado pela chave LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA.
Query base (origem):
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,
LQ_XCBSIBS,
NUMERO_FISCAL_TROCA,
SERIE_NF_ENTRADA,
LQ_SERSAT,
DATA_PARA_TRANSFERENCIA
FROM
WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PONTUAL (NOLOCK)Query de itens (grupo ITENS):
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_PONTUAL (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}'Query de pagamentos (grupo PARCELAS):
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_PONTUAL (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}'Query de troca (grupo CAB_DEV):
SELECT
F1_FILIAL,
F1_DOC,
LQ_SERIE,
F1_FORNECE,
F1_LOJA,
F1_COND,
F1_XNATOPE,
F1_XCANAL,
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_DESCONTO,
F1_BASEICM,
F1_VALICM,
F1_BASEIPI,
F1_VALIPI,
F1_BRICMS,
F1_ICMSRET,
F1_BASIMP5,
F1_VALIMP5,
F1_BASIMP6,
F1_VALIMP6,
BASEPS3,
VALPS3,
BASECF3,
VALCF3,
F1_MUORITR,
F1_UFORITR,
F1_MUDESTR,
F1_UFDESTR,
F1_II,
F1CIF,
F1_TIPO_NF,
F1_CHVNFE,
F1_DAUTNFE,
F1_HAUTNFE,
F1_PROTOC,
F1_NFELETR,
F1_EMINFE,
F1_HORNFE,
F1_TPFRETE,
F1_TPCTE,
P1_PLIQUI,
P1_PBRUTO,
P1_ESPECI1,
P1_VOLUME1,
F1_ORIGLAN,
F1_NFORIG,
F1_SERORIG,
F1_NUMTRIB,
F1_MOEDA,
F1_PREFIXO,
F1_STATUS,
F1_ESTPRES_2,
F1_SDOC,
F1_TRANSP,
F3_DTCANC,
F3_CODRSEF,
F1_XCBSIBS,
DATA_PARA_TRANSFERENCIA
FROM
WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_TROCA_CABECALHO_PONTUAL (NOLOCK)
WHERE
F1_DOC = '{$NUMERO_FISCAL_TROCA}'
AND LQ_SERIE = '{$SERIE_NF_ENTRADA}'
AND F1_FILIAL = '{$LQ_FILIAL}'Query de itens da troca (grupo ITENS_DEV):
SELECT
D1_FILIAL,
D1_ITEM,
D1_COD,
B1_TP,
B1_UM,
B1_LOCAL,
B1_GRUPO,
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,
F1_SDOC,
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,
DATA_PARA_TRANSFERENCIA
FROM
WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_TROCA_ITEM_PONTUAL (NOLOCK)
WHERE
D1_FILIAL = '{$D1_FILIAL}'
AND D1_DOC = '{$D1_DOC}'
AND D1_SERIE = '{$D1_SERIE}'
AND D1_FORNECE = '{$D1_FORNECE}'
AND D1_LOJA = '{$D1_LOJA}'
Fila de Processamento
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 processamento valida previamente a situação de integração do cliente no Protheus e, em seguida, envia o cupom. Ao final, persiste na tabela wosk_queue (integrador) a situação do item, mensagem e retorno de integração para auditoria e notificação.
Estruturação de Dados
$field), incluindo grupos aninhados ITENS, PARCELAS e CAB_DEV (quando houver), onde CAB_DEV pode conter ITENS_DEV. Quando houver mapeamento (ex.: F1_SERIE → LQ_SERIE), o campo do payload assume o nome do lado esquerdo, com valor derivado do campo indicado no lado direito.Exemplo de payload enviado (campos completos conforme
$field):{
"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": "",
"LQ_XCBSIBS": "",
"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,
"LR_XCBSBS": 0,
"LR_XCBSAL": 0,
"LR_XCBSVL": 0,
"LR_XIBSBS": 0,
"LR_XIBSAL": 0,
"LR_XIBSVL": 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": ""
}
],
"CAB_DEV": [
{
"F1_FILIAL": "",
"F1_DOC": "",
"F1_SERIE": "",
"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": 0,
"F1_VALBRUT": 0,
"F1_FRETE": 0,
"F1_DESPESA": 0,
"F1_SEGURO": 0,
"F1_DESCONT": 0,
"F1_BASEICM": 0,
"F1_VALICM": 0,
"F1_BASEIPI": 0,
"F1_VALIPI": 0,
"F1_BRICMS": 0,
"F1_ICMSRET": 0,
"F1_BASIMP5": 0,
"F1_VALIMP5": 0,
"F1_BASIMP6": 0,
"F1_VALIMP6": 0,
"F1_BASEPS3": 0,
"F1_VALPS3": 0,
"F1_BASECF3": 0,
"F1_VALCF3": 0,
"F1_MUORITR": "",
"F1_UFORITR": "",
"F1_MUDESTR": "",
"F1_UFDESTR": "",
"F1_II": 0,
"F1_CIF": 0,
"F1_TIPO_NF": "",
"F1_CHVNFE": "",
"F1_DAUTNFE": "",
"F1_HAUTNFE": "",
"F3_PROTOC": "",
"F1_NFELETR": "",
"F1_EMINFE": "",
"F1_HORNFE": "",
"F1_TPFRETE": "",
"F1_TPCTE": "",
"F1_PLIQUI": 0,
"F1_PBRUTO": 0,
"F1_ESPECI1": "",
"F1_VOLUME1": 0,
"F1_ORIGLAN": "",
"F1_NFORIG": "",
"F1_SERORIG": "",
"F1_NUMTRIB": "",
"F1_MOEDA": 0,
"F1_PREFIXO": "",
"F1_STATUS": "",
"F1_SDOC": "",
"F1_TRANSP": "",
"F1_XNATOPE": "",
"F1_XCANAL": "",
"F3_DTCANC": "",
"F3_CODRSEF": "",
"F1_XCBSIBS": "",
"ITENS_DEV": [
{
"D1_FILIAL": "",
"D1_ITEM": "",
"D1_COD": "",
"D1_TP": "",
"D1_UM": "",
"D1_LOCAL": "",
"D1_GRUPO": "",
"D1_TEC": "",
"D1_QUANT": 0,
"D1_VUNIT": 0,
"D1_TOTAL": 0,
"D1_DESC": 0,
"D1_VALDESC": 0,
"D1_SEGURO": 0,
"D1_VALFRE": 0,
"D1_DESPESA": 0,
"D1_EMISSAO": "",
"D1_DTDIGIT": "",
"D1_DOC": "",
"D1_SERIE": "",
"D1_SDOC": "",
"D1_TIPO": "",
"D1_FORNECE": "",
"D1_LOJA": "",
"D1_CLASFIS": "",
"D1_OPER": "",
"D1_CF": "",
"D1_BASEIPI": 0,
"D1_IPI": 0,
"D1_VALIPI": 0,
"D1_BASEICM": 0,
"D1_PICM": 0,
"D1_VALICM": 0,
"D1_VRDICMS": 0,
"D1_VALANTI": 0,
"D1_ICMSDIF": 0,
"D1_BASFECP": 0,
"D1_ALQFECP": 0,
"D1_VALFECP": 0,
"D1_ALIQCMP": 0,
"D1_DIFAL": 0,
"D1_BSFCCMP": 0,
"D1_ALFCCMP": 0,
"D1_VFCPDIF": 0,
"D1_AFCPANT": 0,
"D1_VFCPANT": 0,
"D1_BRICMS": 0,
"D1_ALIQSOL": 0,
"D1_MARGEM": 0,
"D1_ICMSRET": 0,
"D1_BSFCPST": 0,
"D1_ALFCPST": 0,
"D1_VFECPST": 0,
"D1_BASIMP5": 0,
"D1_ALQIMP5": 0,
"D1_VALIMP5": 0,
"D1_BASIMP6": 0,
"D1_ALQIMP6": 0,
"D1_VALIMP6": 0,
"D1_ALIQII": 0,
"D1_II": 0,
"D1_CIF": 0,
"D1_TIPO_NF": "",
"D1_OP": "",
"D1_CC": "",
"D1_CONTA": "",
"D1_PESO": 0,
"D1_DATORI": "",
"D1_NFORI": "",
"D1_SERIORI": "",
"D1_ITEMORI": "",
"D1_ORIGLAN": "",
"DKD_XCBSBS": 0,
"DKD_XCBSAL": 0,
"DKD_XCBSVL": 0,
"DKD_XIBSBS": 0,
"DKD_XIBSAL": 0,
"DKD_XIBSVL": 0
}
]
}
]
}Tratamento de Dados
Antes do envio ao Protheus, a fila aplica padronização numérica com setNumeric (sem alterar a semântica dos campos, apenas formato/precisão).
Cabeçalho do cupom
- 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 como numéricos (setNumeric padrão).
Itens do cupom
- 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: normalizados como numéricos (setNumeric padrão).
Parcelas/pagamentos
- L4_VALOR, L4_XTOTPAR, L4_MOEDA: normalizados como numéricos (setNumeric padrão).
Troca (cabeçalho)
- 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: normalizados como numéricos (setNumeric padrão).
Troca (itens)
- D1_QUANT: normalizado com 3 casas decimais (setNumeric(..., 3, false)).
- D1_VUNIT: normalizado com 5 casas decimais (setNumeric(..., 5, false)).
- 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: normalizados como numéricos (setNumeric padrão).
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: composto por substr(LQ_FILIAL, 0, 2) . "," . LQ_FILIAL.
Pré-validação (cliente)
Antes do envio do cupom, o processo exige que o cliente esteja integrado no Protheus usando a chave LQ_LOJA-LQ_CLIENTE. Se não estiver integrado, o item é suspenso para evitar envio de cupom sem dependência atendida.
Tratamento de retorno
- Ausência de resposta: o item é finalizado como erro com mensagem JSON: NÃO HOUVE RESPOSTA..
- Resposta inválida/inesperada: se não for um array ou não contiver Mensagem, o item é finalizado como erro com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..
- Definição de situação: por padrão, sucesso quando não houver code e Mensagem não for ERRO; erro quando houver code ou Mensagem for ERRO.
- Espera por processamento: em sucesso, se vierem ZB_FILIAL e ZB_ID e ZB_DATRET estiver vazio, o item passa para estado de espera por callback e a mensagem vira Aguardando Processamento no Protheus.
- Exceção de mensagem: se a mensagem detalhada contiver ja cadastrado, o retorno é tratado como sucesso.
Rotinas Inteligentes
- Cliente Integrado: chamada antes do envio do cupom, após estruturar o conteúdo. Garante que o cliente esteja pronto para receber o documento no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado
- Cupom Ecommerce Integrado: chamada após sucesso da integração do cupom. Registra que a chave do documento foi integrada, evitando reprocessamento indevido.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cupom-ecommerce-integrado
- Cupom Fiscal Integrado: chamada após sucesso da integração do cupom. Registra a integração do cupom fiscal para rastreabilidade do processo.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cupom-fiscal-integrado
- Documento de Cancelamento de Cupom Fiscal: chamada após sucesso da integração do cupom. Mantém consistência do status do cancelamento associado à mesma chave do documento, quando aplicável.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/documento-de-cancelamento-de-cupom-fiscal
Tratamento de retorno
Sucesso: quando o retorno do Protheus não indicar erro (Mensagem diferente de ERRO e sem campo code), a fila registra a situação de sucesso e dispara o registro de integração das rotinas associadas à chave do documento.
Espera por callback: quando o Protheus retorna identificadores ZB_FILIAL e ZB_ID sem data de retorno (ZB_DATRET vazio), a fila salva o controle de acompanhamento e registra a situação de aguardo.
Erro: quando houver ausência de resposta, resposta não decodificável, ou indicador de erro (code presente ou Mensagem = ERRO), a fila grava o retorno de erro e mensagem para auditoria.
Encaminhamento em cenário de erro
Dependência de cliente: se o cliente não estiver integrado, o item é marcado como suspenso, registrando o tipo de suspensão ProtheusCliente e a chave LQ_LOJA-LQ_CLIENTE, permitindo reprocessamento após a correção da dependência.
Demais erros: o item permanece registrado como erro na tabela wosk_queue, com detalhes do retorno e mensagem, habilitando acompanhamento e reprocessamento conforme necessidade operacional.
Notificação
wosk_queue (serviço ProtheusCupomFiscalPontual e situação de erro), ordenando pelo horário de processamento para priorizar ocorrências mais antigas. Em seguida, higieniza a mensagem de erro removendo prefixos padrão e normalizando quebras de linha, e formata as datas para leitura, enviando o aviso aos destinatários configurados.Fluxo do Processo
Critérios de Aceitação
| Processo | Subprocesso | Descrição | Situação esperada |
| Capturador | Captura e enfileiramento | Ao encontrar documentos na origem WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_PONTUAL dentro do filtro por DATA_PARA_TRANSFERENCIA, deve compor a chave LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA e registrar o item na tabela wosk_queue para processamento. |
Item pendente registrado em wosk_queue com conteúdo completo (incluindo ITENS e PARCELAS e, quando aplicável, CAB_DEV e ITENS_DEV). |
| Capturador | Captura manual | Ao informar uma chave, o processo deve exigir o padrão com cinco partes e filtrar dinamicamente por LQ_FILIAL, LQ_DOC, LQ_SERIE, LQ_CLIENTE e LQ_LOJA, evitando enfileirar itens fora do escopo. |
Chave inválida não gera enfileiramento; chave válida gera registro correspondente em wosk_queue. |
| Fila de Processamento | Integração com Protheus | Ao processar um item pendente, deve validar previamente o cliente no Protheus (chave LQ_LOJA-LQ_CLIENTE), padronizar campos numéricos conforme regras, e enviar o cupom ao recurso cupom via POST com cabeçalho tenantId. |
Em sucesso, item atualizado em wosk_queue com retorno e mensagem; em erro, item atualizado com situação de erro e mensagem higienizada para notificação. |