ProtheusCancelamentoCupomFiscal (STATUS: AJUSTANDO)

Documentação Técnica

Histórico de Versões

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

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

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

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

• Consulta itensregistros 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.

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