ProtheusNotaFiscalOmniCancelamento (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_nota_fiscal_omni_cancelamento
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	Criação da documentação técnica do processo ProtheusNotaFiscalOmniCancelamento.

Descrição

Esta biblioteca organiza o cancelamento de Notas Fiscais Omni do LINX no Protheus, garantindo captura por chave ou por data e registro do resultado do cancelamento.

Capturador

Descrição Conceitual

Permite a captura manual de uma ou mais Notas Fiscais Omni por chave no padrão cpedsite-cchvnfe, com validação obrigatória do formato; quando a chave estiver fora do padrão, o processo é interrompido com erro de chave inválida para evitar registros inconsistentes.

A captura por data consulta a origem filtrando e ordenando por DATA_PARA_TRANSFERENCIA, com paginação por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_EXCLUSAO.

Consulta utilizada na captura por data (WHERE e paginação construídos dinamicamente conforme posição e limite configurado):

SELECT
    cfilial,
    cchvnfe,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_EXCLUSAO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Consulta utilizada na captura manual (chave informada e WHERE construído dinamicamente):

SELECT
    cfilial,
    cchvnfe,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_EXCLUSAO (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'
    AND cchvnfe = '<CCHVNFE>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_EXCLUSAO para obter o registro atual da Nota Fiscal Omni (cfilial, cpedsite, cchvnfe, DATA_PARA_TRANSFERENCIA) e construir o identificador de processamento no padrão cpedsite-cchvnfe.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusNotaFiscalOmniCancelamento, aplicado na paginação da consulta (FETCH NEXT <LIMITE>).

- Registro para processamento: cada Nota Fiscal Omni capturada é persistida como pendência na tabela wosk_queue sob o serviço ProtheusNotaFiscalOmniCancelamento, com o conteúdo vindo da origem para processamento assíncrono.

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.

O item de fila é persistido e atualizado na tabela wosk_queue ao longo do processamento, registrando retorno, mensagem, tempo e situação para auditoria.

Estruturação de Dados

Tratamento de Dados

- Campos utilizados na integração: o cancelamento utiliza cpedsite e cchvnfe para compor o recurso de integração (parâmetros em URL). O corpo da requisição é enviado vazio ([]).

- Mapeamento de retorno: quando o Protheus retornar COD e MSG, esses campos são reinterpretados como code e message para padronizar o tratamento do resultado.

- Consolidação de mensagem: quando existir detailedMessage, ele é concatenado à mensagem final para detalhar a causa do sucesso/erro.

- Classificação de resultado: considera sucesso quando code for NX200; demais valores finalizam como erro.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtbomni/notas com parâmetros na URL
- Método HTTP: DELETE
- Exemplo de envio:
  - Não há corpo de requisição (payload vazio). Os parâmetros obrigatórios são enviados na URL: cpedsite e cchvnfe.
  - Exemplo de recurso com parâmetros:
    rtbomni/notas?cpedsite=<CPEDSITE>&cchvnfe=<CCHVNFE>

Tratamento de retorno

Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como erro.

Resposta inválida/inesperada: quando não for possível obter code (direto ou via COD), registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera sucesso quando code for NX200; demais valores finalizam como erro.

Consolidação de mensagem: a mensagem final é composta por message (direto ou via MSG) e, quando existir, complementada por detailedMessage.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada e a situação final (situacao = 2 em sucesso, situacao = 4 em erro). O tempo de processamento é registrado para acompanhamento operacional.

Encaminhamento em cenário de erro

Em cenários de falha (ausência de resposta, retorno inválido ou code diferente de NX200), o item permanece registrado em wosk_queue com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_EXCLUSAO com filtro por DATA_PARA_TRANSFERENCIA, ordenação ascendente e paginação por OFFSET/FETCH, deve manter a continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao, filtro).	Posição atualizada em wosk_monitor e itens pendentes registrados para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma chave no padrão cpedsite-cchvnfe, deve consultar a origem filtrando por cpedsite e cchvnfe e registrar o item correspondente para processamento; quando a chave estiver fora do padrão, deve finalizar com erro de chave inválida.	Item pendente registrado para processamento quando a chave for válida; erro quando a chave estiver fora do padrão.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusNotaFiscalOmniCancelamento), deve compor o recurso rtbomni/notas com os parâmetros cpedsite e cchvnfe, enviar requisição DELETE e registrar retorno, mensagem e situação final.	Item atualizado em wosk_queue com retorno/mensagem e situação final coerente (sucesso apenas quando code = NX200; erro quando não houver resposta, não houver code ou code for diferente).
Fila de Processamento	Padronização do retorno	Quando o retorno vier nos campos COD e MSG, deve mapear para code e message antes de avaliar sucesso/erro e consolidar a mensagem.	Avaliação de sucesso/erro e mensagem final consistentes, independentemente do formato do retorno.