ProtheusCancelamentoCupomFiscal (STATUS: PARCIAL)

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

Esta biblioteca 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 (ordenação/paginação por data) e seguindo o conceito: CONCEITO_CRONOLOGICO.

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 item correspondente na fila de processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO.

Operações com Dados

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

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)>'

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 item.

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.
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

O payload de integração é montado a partir do conteúdo do item pendente, seguindo a lista oficial de campos abaixo:

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

Integração com o Protheus

Chamada de integração com o Protheus

{
  "tenantId": "<UF>,<LQ_FILIAL>"
}

Exemplo de payload enviado:

{
  "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>"
}

Tratamento de retorno:

Encaminhamento em cenário de erro:

Notificação de erros:

Tratamento de retorno

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 item 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 itens com falha do serviço ProtheusCancelamentoCupomFiscal na tabela wosk_queue, 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 item e a mensagem de erro higienizada.

Origem dos erros: wosk_queue (banco integrador). Destinatários configurados: juan.oliveira@osklen.com.br, kelyton.anderson@osklen.com.br.

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 itens novos registrados em wosk_queue 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 itens correspondentes para processamento.	Itens pendentes registrados em wosk_queue para o serviço ProtheusCancelamentoCupomFiscal.
Fila de Processamento	Validações e integração	Ao processar um item 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.	wosk_queue atualizado com situação final coerente: 2 (sucesso), 3 (suspenso) ou 4 (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 item como sucesso e registrar a mensagem de resalva definida no processo.	Item finalizado como sucesso (2) em wosk_queue, com mensagem de resalva persistida.