ProtheusCancelamentoDocumentoSaida (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_cancelamento_documento_saida
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 ProtheusCancelamentoDocumentoSaida.

Descrição

Esta biblioteca organiza o envio do cancelamento de documentos de saída do LINX para o Protheus, garantindo validações prévias e rastreabilidade do resultado.

Capturador

Descrição Conceitual

Permite capturar registros de cancelamento de documento de saída a partir da origem no LINX e encaminhá-los para processamento assíncrono, controlando continuidade por posição (offset/chave/data) para evitar reprocessamentos indevidos.

Também suporta captura direcionada por chave, validando o formato e consultando a origem para registrar apenas o(s) registro(s) correspondente(s) na fila de processamento.

Fonte

Origem consultada: WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_CANCELAMENTO.

Operações com Dados

Leitura: consulta a origem com limitação dinâmica por SELECT {{TOP}}, que funciona como controle de volume por execução.
Conceito: semáforo (SELECT {{TOP}})

Consulta usada na captura por lote (limite substitui {{TOP}}):

SELECT {{TOP}}
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_EMISSAO,
    F2_FORNECE,
    F2_LOJA,
    F2_TIPO,
    F2_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    F2_CHVNFE,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_CANCELAMENTO (NOLOCK)
WHERE
    CAPTURADO_ISNAPP = 0

Consulta usada na captura por chave (WHERE montado dinamicamente conforme a chave informada):

SELECT
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_EMISSAO,
    F2_FORNECE,
    F2_LOJA,
    F2_TIPO,
    F2_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    F2_CHVNFE,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_CANCELAMENTO (NOLOCK)
WHERE
    F2_FILIAL = <F2_FILIAL>
    AND F2_DOC = <F2_DOC>
    AND F2_SERIE = <F2_SERIE>
    AND F2_FORNECE = <F2_FORNECE>
    AND F2_LOJA = <F2_LOJA>

Persistência: o registro capturado é armazenado na tabela wosk_queue para processamento posterior, e a posição de captura (offset/chave/data) é persistida na tabela wosk_monitor.

 

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.

No fluxo, é feita uma validação prévia do cliente (integração obrigatória antes do cancelamento) e, quando aplicável, uma conferência do estado de integração do documento para ajustar o motivo/código de cancelamento antes do envio.

Estruturação de Dados

{
  "F2_FILIAL": "",
  "F2_DOC": "",
  "F2_SERIE": "",
  "F2_EMISSAO": "",
  "F2_CLIENTE": "",
  "F2_LOJA": "",
  "F2_TIPO": "",
  "F2_ESPECIE": "",
  "F3_DTCANC": "",
  "F3_CODRSEF": "",
  "F3_PROTOC": "",
  "F2_CHVNFE": ""
}

Tratamento de Dados

Validação prévia do cliente (obrigatória): antes do envio do cancelamento, a chave do cliente é montada no padrão F2_LOJA-F2_CLIENTE e utilizada para validar se o cliente já está integrado. Se não estiver, o item não segue para integração e fica marcado como suspenso, com rastreio do tipo/chave de suspensão.

Tratamento condicional do motivo de cancelamento (F3_CODRSEF): quando F3_CODRSEF for diferente de 102, é feita uma conferência do estado de integração do documento; se o resultado indicar que o documento está em estado de aguardo, o campo F3_CODRSEF é ajustado para SAI antes do envio ao Protheus, e o item fica marcado para remoção de registros correlatos após sucesso.

Integração com o Protheus

Chamada de integração com o Protheus

Chamada: Requisição HTTP
Recurso: documento_saida
Método HTTP: PUT
Cabeçalhos:
- tenantId: composto por substr(F2_FILIAL, 0, 2) e F2_FILIAL, no formato <UF>,<FILIAL> (ex.: 01,0101).

Exemplo de payload enviado: ver seção “Estruturação de Dados” (campos do esquema oficial).

Tratamento de retorno:
- Sem resposta: retorna erro JSON: NÃO HOUVE RESPOSTA.
- Resposta inválida: quando não é possível interpretar a resposta em formato esperado, retorna erro JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Erro indicado: se houver Mensagem = "ERRO" ou presença de code, o item é finalizado como erro.
- Exceção tratada: quando a mensagem detalhada contém documento de saida nao cadastrado, o item é considerado concluído com ressalva, registrando a mensagem: Cancelado com Sucesso, com resalva (autorizado pelo Juan - 08/04/2025).

Rotinas Inteligentes:
- Documento de Cancelamento de Saida: durante a conferência do estado de integração do documento, antes do envio ao Protheus. Objetiva validar/definir a condição de envio e o ajuste do motivo de cancelamento quando aplicável.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/documento-de-cancelamento-de-saida
- Cliente Integrado: na pré-validação do item da fila, antes de enviar o cancelamento. Objetiva garantir que o cliente associado ao documento já esteja integrado para evitar rejeição no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

Tratamento de retorno

Sucesso: quando a resposta do Protheus possui estrutura esperada e não indica erro (ausência de code e Mensagem diferente de ERRO), o item é concluído e o retorno é persistido no próprio registro da fila (wosk_queue).

Erro: quando houver ausência de resposta, resposta inválida, exceção no fluxo ou indicação explícita de erro no retorno, o item é finalizado como erro e o detalhe é persistido na fila. Quando o erro ocorrer por falta de pré-requisito (cliente não integrado), o item é mantido como suspenso, com identificação do tipo/chave para retomada controlada.

Encaminhamento em cenário de erro

Quando o fluxo identifica pré-requisito não atendido (ex.: cliente não integrado), o item é marcado como suspenso para permitir retomada posterior sem perda de rastreabilidade. Nos demais erros, o item é mantido como erro na fila, preservando mensagem, requisição e retorno para auditoria e reprocessamento controlado.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por lote	Ao consultar WOSK_SERVICO_ENVIA_PROTHEUS_SAIDAS_CANCELAMENTO com filtro CAPTURADO_ISNAPP = 0 e limite via SELECT {{TOP}}, deve registrar na wosk_queue um item para cada registro retornado.	Itens pendentes registrados na fila, prontos para processamento e com rastreio de posição de captura.
Capturador	Captura por chave	Ao informar uma chave no padrão esperado (6 partes separadas por -), deve consultar a origem aplicando WHERE dinâmico por F2_FILIAL, F2_DOC, F2_SERIE, F2_FORNECE e F2_LOJA.	Somente os registros correspondentes são registrados na wosk_queue; em formato inválido, nenhum item é registrado.
Fila de Processamento	Validação prévia	Antes de enviar o cancelamento, deve validar a integração do cliente pela chave F2_LOJA-F2_CLIENTE; se a validação falhar, o item deve ser mantido como suspenso com motivo identificável.	Item não segue para integração e permanece suspenso, com mensagem e identificação do tipo/chave de suspensão persistidas na wosk_queue.
Fila de Processamento	Integração com Protheus	Ao enviar o payload ao recurso documento_saida via PUT com cabeçalho tenantId, deve interpretar o retorno e registrar sucesso/erro com detalhes.	Em sucesso, item concluído; em erro (sem resposta, resposta inválida ou Mensagem = "ERRO"/code), item finalizado como erro com retorno persistido na wosk_queue.
Fila de Processamento	Remoção pós-sucesso (caso aplicável)	Quando houver marcação de remoção e o cancelamento for concluído, deve excluir registros correlatos nas tabelas ProtheusDocumentoSaida, ProtheusDocumentoSaidaPontual, ProtheusDocumentoSaidaLoja, ProtheusDocumentoSaidaLog, ProtheusDocumentoSaidaFull, ProtheusDocumentoSaidaLojaFull e ProtheusDocumentoSaidaLojaLog.	Registros correlatos removidos conforme a chave do documento e logs de integração, mantendo consistência após o cancelamento.