ProtheusCancelamentoCupomFiscal (STATUS: AJUSTANDO)

Documentação Técnica

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

Descrição

Este serviço organiza o envio de cancelamentos de cupom fiscal do LINX para o Protheus, garantindo validações prévias e rastreabilidade do processamento.

Também mantém controle de captura e status para facilitar auditoria e reprocessamento quando necessário.

Capturador

Descrição Conceitual

O capturador busca cancelamentos de cupom fiscal disponíveis na origem, respeitando um limite configurável por ciclo e registrando a posição de continuidade para evitar duplicidades e permitir retomada segura.
Quando executa a busca por data de transferência, aplica ordenação/paginação por data, caracterizando processamento cronológico, a partir do campo DATA_PARA_TRANSFERENCIA, e seguindo o conceito: Conceito Cronológico.

Também permite captura manual por uma ou mais chaves no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA; para cada chave, consulta a mesma origem com filtros dinâmicos e registra o registro correspondente na fila de processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO.

Operações com Dados

Leitura (captura por data): consulta a origem com filtro por DATA_PARA_TRANSFERENCIA, ordenação ascendente e paginação por offset.

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET <OFFSET> ROWS FETCH NEXT <TOP> ROWS ONLY

Leitura (captura manual por chave): consulta a mesma origem aplicando WHERE construído dinamicamente a partir dos componentes da chave. Os filtros de LQ_CLIENTE e LQ_LOJA só são incluídos quando presentes na chave.

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO (NOLOCK)
WHERE
    LQ_FILIAL = '<LQ_FILIAL>'
    AND LQ_DOC = '<LQ_DOC>'
    AND LQ_SERIE = '<LQ_SERIE>'
    AND LQ_CLIENTE = '<LQ_CLIENTE (opcional)>'
    AND LQ_LOJA = '<LQ_LOJA (opcional)>'

Persistência (controle de continuidade): grava/atualiza a posição de execução na tabela wosk_monitor, incluindo os campos evento, offset, filtro, chave_posicao, situacao, data_posicao e data_iniciado.
Persistência (registros pendentes): registra os registros para processamento na fila de processamento, utilizando chave composta no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA.

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.

Neste processo, a fila valida pré-requisitos de integração (cliente e, quando aplicável, documento de cancelamento de cupom fiscal) antes de efetivar o envio do cancelamento ao Protheus e persistir o status final do registro.

Rotinas Inteligentes

Cliente Integrado: Antes de enviar o cancelamento ao Protheus, ao validar o vínculo do cliente (LQ_LOJA-LQ_CLIENTE). Garante que o cancelamento seja encaminhado apenas para clientes reconhecidos no Protheus. Após confirmação de sucesso da integração, reinicia os processos que estão suspensos marcados com "ProtheusCliente" vinculados com o registro atual.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

Documento de Cancelamento de Cupom Fiscal: Quando F3_CODRSEF for diferente de 102, antes de enviar o cancelamento ao Protheus. Garante consistência do documento de referência no Protheus para o cancelamento.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/documento-de-cancelamento-de-cupom-fiscal

Estruturação de Dados

Campo no payload (Protheus)	Campo de origem
`LQ_FILIAL`	`LQ_FILIAL`
`LQ_DOC`	`LQ_DOC`
`LQ_SERIE`	`LQ_SERIE`
`LQ_CLIENTE`	`LQ_CLIENTE`
`LQ_LOJA`	`LQ_LOJA`
`LQ_EMISSAO`	`LQ_EMISSAO`
`F3_DTCANC`	`F3_DTCANC`
`F3_CODRSEF`	`F3_CODRSEF`

Exemplo de payload enviado:

{
  "LQ_FILIAL": "0101",
  "LQ_DOC": "123456",
  "LQ_SERIE": "1",
  "LQ_CLIENTE": "000001",
  "LQ_LOJA": "01",
  "LQ_EMISSAO": "2026-03-02",
  "F3_DTCANC": "2026-03-02",
  "F3_CODRSEF": "101"
}

Tratamento de Dados

F3_CODRSEF: avaliado como numérico para decidir se a validação do documento de cancelamento de cupom fiscal será exigida (quando diferente de 102).
tenantId (cabeçalho): formado a partir de LQ_FILIAL no padrão <primeiros 2 caracteres>,<LQ_FILIAL>.
chave (notificação): decomposta em LQ_FILIAL, LQ_DOC, LQ_SERIE, LQ_CLIENTE, LQ_LOJA para apresentar os componentes do registro com falha.
ERRO (notificação): se a mensagem contiver marcador de SQL Server, é extraído o trecho relevante a partir de [SQL Server] até antes de Error :; se existir :, é mantido apenas o conteúdo após o primeiro :; sequências de quebra de linha (escapadas ou reais) são convertidas para quebra de linha padrão.
data_adicionado, data (notificação): formatados para d/m/Y H:i:s.

Integração com o Protheus

Chamada de integração com o Protheus

Chamada: Requisição HTTP
Recurso: /rest/cupom
Método HTTP: PUT
Cabeçalhos:
- tenantId: <UF>,<LQ_FILIAL>

Notificação de erros

Consulta registros com falha na fila de processamento (serviço ProtheusCancelamentoCupomFiscal e situação de erro), ordenando pelo horário de processamento para priorizar ocorrências mais antigas.

Tratamento de retorno

Sucesso: quando o retorno estiver decodificado e não houver indicador de erro, o registro é finalizado como integrado.
Erro: quando houver exceção no fluxo, retorno ausente, retorno inválido ou indicador de erro, o registro é finalizado como erro com o retorno armazenado no campo de auditoria.
Persistência de status: o registro é atualizado na fila de processamento, incluindo mensagem, retorno decodificado, tempo de processamento e situação final.

Encaminhamento em cenário de erro

Quando a validação prévia do cliente (LQ_LOJA-LQ_CLIENTE) ou do documento (LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA) não estiver atendida, o registro não segue para integração. Ele é marcado como suspenso e armazenado com identificação do motivo (tipo) e chave de suspensão, permitindo retomada após a correção do pré-requisito.

Notificação

A notificação de erros seleciona registros com falha do serviço ProtheusCancelamentoCupomFiscal na fila de processamento, priorizando os mais antigos pela ordenação por data de processamento. Em seguida, encaminha o resultado para os destinatários configurados, incluindo a chave do registro e a mensagem de erro higienizada.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por data e continuidade	Ao executar a captura por `DATA_PARA_TRANSFERENCIA`, deve consultar a origem ordenando/paginando por data e persistir a posição atual em `wosk_monitor` (offset, chave e datas), evitando duplicidades.	Posição atualizada em `wosk_monitor` e registros novos registradosna fila de processamento com chave consistente.
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 com `WHERE` dinâmico e registrar os registros correspondentes para processamento.	registros pendentes registrados na fila de processamento para o serviço `ProtheusCancelamentoCupomFiscal`.
Fila de Processamento	Validações e integração	Ao processar um registro pendente do serviço `ProtheusCancelamentoCupomFiscal`, deve validar pré-requisitos (cliente e documento quando aplicável), enviar o cancelamento ao Protheus (recurso `cupom`, `PUT`) e persistir retorno/mensagem.	fila de processamento atualizado com situação final coerente: sucesso, suspenso ou erro, com mensagem e retorno armazenados.
Fila de Processamento	Resalva de sucesso	Se o Protheus responder erro com mensagem contendo `documento de saida nao cadastrado`, deve tratar o registro como sucesso e registrar a mensagem de resalva definida no processo.	Registro finalizado como sucesso na fila de processamento, com mensagem de resalva persistida.