ProtheusPedidoOmniCancelamento (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_pedido_omni_cancelamento
Data	02/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
27/02/2026	1.0	Maykon	Criação da documentação técnica do processo ProtheusPedidoOmniCancelamento.

Descrição

Esta biblioteca integra o cancelamento de pedidos 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 um ou mais pedidos pelo identificador cpedsite e a captura por agendador de tarefas com base em janela temporal, consultando a origem e registrando cada item para processamento assíncrono.

A captura por data segue processamento cronológico (ordenação/paginação por data) para priorizar registros mais antigos e manter continuidade por posição; link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO.

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

SELECT
    cfilial,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_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,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO para obter o registro atual do pedido (cfilial, cpedsite, DATA_PARA_TRANSFERENCIA) e definir a chave do item como cpedsite.

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

- Registro para processamento: cada pedido capturado é persistido como pendência na tabela wosk_queue sob o serviço ProtheusPedidoOmniCancelamento, com chave cpedsite e conteúdo 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.

Estruturação de Dados

{
  "cfilial": "",
  "cpedsite": ""
}

Tratamento de Dados

- Campos utilizados na integração: o cancelamento utiliza cpedsite para compor o recurso de integração (parâmetro 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.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtbomni/excvendas com parâmetro na URL
- Método HTTP: DELETE
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada
- Exemplo de recurso com parâmetro: rtbomni/excvendas?cpedsite=<CPEDSITE>
 

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 X200; 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 X200), 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_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 pedido	Ao informar um cpedsite, deve consultar a origem filtrando por cpedsite e registrar o item correspondente na fila.	Item pendente registrado para processamento, associado à chave cpedsite.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusPedidoOmniCancelamento), deve compor o recurso rtbomni/excvendas com o parâmetro cpedsite, 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 = X200; 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.