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

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 (itens pendentes): registra os itens para processamento na tabela wosk_queue (banco integrador), 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 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:

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 item 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: cupom
Método HTTP: PUT
Cabeçalhos:

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

Ausência de resposta: considera erro e finaliza o item com mensagem JSON: NÃO HOUVE RESPOSTA.
Resposta inválida: se não for array ou não contiver Mensagem, considera erro e finaliza com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
Indicadores de erro: considera erro quando existir campo code no retorno, ou quando Mensagem for ERRO.
Mensagem detalhada: quando presente, utiliza Mensagem Detalhada como base da mensagem final.
Resalva de sucesso: se houver erro e a mensagem contiver documento de saida nao cadastrado, o item é tratado como sucesso com a mensagem Cancelado com Sucesso, com resalva (autorizado pelo Juan - 08/04/2025).

Encaminhamento em cenário de erro:

Se a validação de cliente ou do documento não retornar sucesso, o item é marcado como suspenso e registra o tipo e a chave de suspensão para retomar posteriormente.

Notificação de erros:

Consulta itens com falha na tabela wosk_queue (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 item é finalizado como integrado.
Erro: quando houver exceção no fluxo, retorno ausente, retorno inválido ou indicador de erro, o item é finalizado como erro com o retorno armazenado no campo de auditoria.
Persistência de status: o item é atualizado na tabela wosk_queue, 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 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.

Documento de Cancelamento de Entrada

Documento de Cancelamento de Saida

Documento de Cancelamento de Cupom Fiscal

Documento de Saida Integrado

Nota Fiscal Omni Integrado

Ordem de Produção Cadastro Pi Integrado

Ordem de Produção Integrado

Cupom Ecommerce Integrado

Cupom Fiscal Integrado

Pedido Omni

Cliente Integrado