ProtheusCancelamentoCupomFiscalRelampago (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca encaminha o cancelamento de cupom fiscal do LINX para o Protheus, garantindo validações antes do envio e registro do resultado.

Capturador

Descrição Conceitual

Captura cancelamentos de cupom fiscal a partir de uma fonte dedicada e encaminha cada documento para processamento em fila, anexando itens e parcelas de pagamento para formar o conteúdo completo.

O fluxo suporta captura automática por agendador de tarefas, com processamento cronológico (ordenação/paginação por data), e captura manual por chave no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO.

Operações com Dados

Processamento cronológico (ordenação/paginação por data): a captura consulta registros com filtro por DATA_PARA_TRANSFERENCIA, ordena por DATA_PARA_TRANSFERENCIA ASC e pagina com OFFSET/FETCH NEXT.
link: Cronológico

Consulta base da fonte (projeção completa):

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)

Consulta cronológica por lote (string dinâmica):

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '{DATA_PARA_TRANSFERENCIA}'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    {OFFSET} ROWS
FETCH NEXT
    {TOP} ROWS ONLY

Consulta de itens do documento:

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,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO_ITEM (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 de parcelas/pagamentos do documento:

SELECT
    L4_FILIAL,
    L4_DOC,
    L4_SERIE,
    L4_CLIENTE,
    L4_LOJA,
    L4_FORMA,
    L4_DATA,
    L4_VALOR,
    L4_MOEDA,
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_XINUTI,
    LQ_DOCCANC,
    LQ_DATCANC,
    LQ_HORCANC,
    L4_DOCCANC,
    L4_DATCANC,
    L4_HORCANC
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO_PGTO (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}'

Captura manual: o filtro WHERE é construído dinamicamente conforme a chave informada, restringindo por LQ_FILIAL, LQ_DOC, LQ_SERIE e, quando informado, por LQ_CLIENTE e LQ_LOJA.

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)
WHERE
    LQ_FILIAL = '{LQ_FILIAL}'
    AND LQ_DOC = '{LQ_DOC}'
    AND LQ_SERIE = '{LQ_SERIE}'
    [AND LQ_CLIENTE = '{LQ_CLIENTE}']
    [AND LQ_LOJA = '{LQ_LOJA}']

Fila de Processamento

Descrição Conceitual

A fila recupera um cancelamento pendente e utiliza o conteúdo completo (cabeçalho, itens e parcelas) como payload de integração. Antes do envio, valida dependências e aplica padronizações numéricas obrigatórias para consistência.

Ao final, registra o retorno e a situação do processamento na tabela de fila (wosk_queue), permitindo auditoria, notificação de erros e reprocessamento.

Estruturação de Dados

O payload enviado ao Protheus segue o schema definido no array $field da fila. O registro atual capturado é enriquecido com:

- ITENS: lista retornada por consulta na fonte de itens (associada por filial, documento, série, cliente e loja).
- PARCELAS: lista retornada por consulta na fonte de pagamentos (associada pelos mesmos campos).

Cabeçalho

Campo no payload	Campo de origem
`LQ_FILIAL`	`LQ_FILIAL`
`LQ_CLIENTE`	`LQ_CLIENTE`
`LQ_LOJA`	`LQ_LOJA`
`LQ_VEND`	`LQ_VEND`
`LQ_EMISSAO`	`LQ_EMISSAO`
`LQ_DOC`	`LQ_DOC`
`LQ_SERIE`	`LQ_SERIE`
`LQ_ESPECIE`	`LQ_ESPECIE`
`LQ_XNATOPE`	`LQ_XNATOPE`
`LQ_XCANAL`	`LQ_XCANAL`
`LQ_HORA`	`LQ_HORA`
`LQ_KEYNFCE`	`LQ_KEYNFCE`
`LQ_FORMA`	`LQ_FORMA`
`LQ_DINHEIR`	`LQ_DINHEIR`
`LQ_FORMPG`	`LQ_FORMPG`
`LQ_CONDPG`	`LQ_CONDPG`
`LQ_OPERADO`	`LQ_OPERADO`
`LQ_PDV`	`LQ_PDV`
`LQ_SITUA`	`LQ_SITUA`
`LQ_VALMERC`	`LQ_VALMERC`
`LQ_VLRTOT`	`LQ_VLRTOT`
`LQ_VLRLIQ`	`LQ_VLRLIQ`
`LQ_VALBRUT`	`LQ_VALBRUT`

ITENS

Campo no payload	Campo de origem
`LR_FILIAL`	`LR_FILIAL`
`LR_PRODUTO`	`LR_PRODUTO`
`LR_DESCRI`	`LR_DESCRI`
`LR_POSIPI`	`LR_POSIPI`
`LR_ORIGEM`	`LR_ORIGEM`
`LR_QUANT`	`LR_QUANT`
`LR_UM`	`LR_UM`
`LR_TABELA`	`LR_TABELA`
`LR_VRUNIT`	`LR_VRUNIT`
`LR_VLRITEM`	`LR_VLRITEM`
`LR_ENTREGA`	`LR_ENTREGA`
`LR_VEND`	`LR_VEND`
`LR_TES`	`LR_TES`
`LR_CF`	`LR_CF`
`LR_CLASFIS`	`LR_CLASFIS`
`LR_VALDESC`	`LR_VALDESC`
`LR_LOCAL`	`LR_LOCAL`
`LR_DOC`	`LR_DOC`
`LR_SERIE`	`LR_SERIE`
`LR_CLIENTE`	`LR_CLIENTE`
`LR_LOJA`	`LR_LOJA`

PARCELAS

Campo no payload	Campo de origem
`L4_FILIAL`	`L4_FILIAL`
`L4_DOC`	`L4_DOC`
`L4_SERIE`	`L4_SERIE`
`L4_CLIENTE`	`L4_CLIENTE`
`L4_LOJA`	`L4_LOJA`
`L4_FORMA`	`L4_FORMA`
`L4_DATA`	`L4_DATA`
`L4_VALOR`	`L4_VALOR`
`L4_MOEDA`	`L4_MOEDA`
`LQ_FILIAL`	`LQ_FILIAL`
`LQ_DOC`	`LQ_DOC`
`LQ_SERIE`	`LQ_SERIE`
`F3_DTCANC`	`F3_DTCANC`
`F3_CODRSEF`	`F3_CODRSEF`
`LQ_XINUTI`	`LQ_XINUTI`
`LQ_DOCCANC`	`LQ_DOCCANC`
`LQ_DATCANC`	`LQ_DATCANC`
`LQ_HORCANC`	`LQ_HORCANC`
`L4_DOCCANC`	`L4_DOCCANC`
`L4_DATCANC`	`L4_DATCANC`
`L4_HORCANC`	`L4_HORCANC`

Exemplo de payload enviado

{
  "LQ_FILIAL": "",
  "LQ_CLIENTE": "",
  "LQ_LOJA": "",
  "LQ_VEND": "",
  "LQ_EMISSAO": "",
  "LQ_DOC": "",
  "LQ_SERIE": "",
  "LQ_ESPECIE": "",
  "LQ_XNATOPE": "",
  "LQ_XCANAL": "",
  "LQ_HORA": "",
  "LQ_KEYNFCE": "",
  "LQ_FORMA": "",
  "LQ_DINHEIR": 0,
  "LQ_FORMPG": "",
  "LQ_CONDPG": "",
  "LQ_OPERADO": "",
  "LQ_PDV": "",
  "LQ_SITUA": "",
  "LQ_VALMERC": 0,
  "LQ_VLRTOT": 0,
  "LQ_VLRLIQ": 0,
  "LQ_VALBRUT": 0,
  "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_VEND": "",
      "LR_TES": "",
      "LR_CF": "",
      "LR_CLASFIS": "",
      "LR_VALDESC": 0,
      "LR_LOCAL": "",
      "LR_DOC": "",
      "LR_SERIE": "",
      "LR_CLIENTE": "",
      "LR_LOJA": ""
    }
  ],
  "PARCELAS": [
    {
      "L4_FILIAL": "",
      "L4_DOC": "",
      "L4_SERIE": "",
      "L4_CLIENTE": "",
      "L4_LOJA": "",
      "L4_FORMA": 0,
      "L4_DATA": "",
      "L4_VALOR": 0,
      "L4_MOEDA": 0,
      "LQ_FILIAL": "",
      "LQ_DOC": "",
      "LQ_SERIE": "",
      "F3_DTCANC": "",
      "F3_CODRSEF": "",
      "LQ_XINUTI": "",
      "LQ_DOCCANC": "",
      "LQ_DATCANC": "",
      "LQ_HORCANC": "",
      "L4_DOCCANC": "",
      "L4_DATCANC": "",
      "L4_HORCANC": ""
    }
  ]
}

Tratamento de Dados

Antes do envio ao Protheus, o payload passa por validações e padronizações obrigatórias.

Validação de dependência
- LQ_CLIENTE, LQ_LOJA: exige confirmação de integração prévia do cliente; em falha, o item é marcado como suspenso por dependência.

Padronização numérica (setNumeric)
- LQ_DINHEIR, LQ_VLRTOT, LQ_VLRLIQ, LQ_VALBRUT: normalizados com o padrão do setNumeric(...).
- LR_QUANT, LR_VRUNIT, LR_VLRITEM, LR_VALDESC: normalizados com o padrão do setNumeric(...).
- L4_FORMA, L4_VALOR, L4_MOEDA: normalizados com o padrão do setNumeric(...).

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: cupom
- Método HTTP: PUT
- Cabeçalhos:
- tenantId: <primeiros 2 caracteres de LQ_FILIAL>,<LQ_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.
- Condição de erro: quando existir code na resposta ou quando Mensagem = ERRO, o processamento é marcado como falha.
- Condição de sucesso: quando a resposta não indica erro, o processamento é marcado como sucesso e aciona o registro do cancelamento integrado.

Rotinas Inteligentes

Cliente Integrado (rotina inteligente): chamada no início do processamento, antes da integração do cancelamento. Garante que o cliente esteja integrado no Protheus para permitir o envio do cupom.
link: Cliente Integrado

Documento de Cancelamento de Cupom Fiscal (rotina inteligente): chamada após retorno de sucesso da integração do cupom. Registra/valida o cancelamento integrado para manter consistência do processo.
link: Documento de Cancelamento de Cupom Fiscal

Tratamento de retorno

Persistência do resultado: o item processado é atualizado na tabela wosk_queue (base integrador), registrando retorno, mensagem, requisição, tempo e situação de processamento, incluindo informações de suspensão por dependência quando aplicável.

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 (cliente não integrado), o item pode ser marcado como suspenso e permanecer aguardando regularização. Demais falhas permanecem como erro com mensagem registrada para correção e reprocessamento.

Notificação

Em cenário de falhas, a notificação seleciona itens com erro em wosk_queue para o servição ProtheusCancelamentoCupomFiscalRelampago, ordena por data e prepara a mensagem para envio de relatório, extraindo apenas a parte relevante do erro quando houver padrão de SQL Server.

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

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e enriquecimento	Ao consultar a view `WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO`, deve capturar registros por `DATA_PARA_TRANSFERENCIA` com paginação e anexar `ITENS` e `PARCELAS` provenientes das fontes correspondentes antes de encaminhar para fila.	Conteúdo completo (cabeçalho, itens, parcelas) pronto para processamento em fila.
Fila de Processamento	Validação de dependência	Antes de enviar o cancelamento ao Protheus, deve validar a integração prévia do cliente (`LQ_CLIENTE`/`LQ_LOJA`) e, em falha, suspender o item por dependência.	Item em estado suspenso (`situacao = 3`) com informações de dependência registradas.
Fila de Processamento	Padronização de valores	Ao preparar o payload, deve normalizar campos numéricos do cabeçalho (`LQ_DINHEIR`, `LQ_VLRTOT`, `LQ_VLRLIQ`, `LQ_VALBRUT`), itens (`LR_QUANT`, `LR_VRUNIT`, `LR_VLRITEM`, `LR_VALDESC`) e parcelas (`L4_FORMA`, `L4_VALOR`, `L4_MOEDA`).	Payload consistente e pronto para integração.
Fila de Processamento	Integração e persistência	Ao integrar via `PUT` no recurso `cupom` com header `tenantId`, deve validar a resposta, registrar o resultado em `wosk_queue` e, em sucesso, acionar a rotina inteligente de registro do cancelamento integrado.	Fila atualizada com situação final e detalhes de auditoria; em sucesso, cancelamento marcado/validado como integrado.