ProtheusCancelamentoDocumentoEntrada (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca organiza o envio de cancelamentos de documento de entrada do LINX para o Protheus, garantindo validações prévias e rastreabilidade do processamento.
Também controla a captura e o status para facilitar auditoria e correção em cenários de falha.

Capturador

Descrição Conceitual

O capturador consulta a origem de cancelamentos de entradas e registra itens pendentes para processamento assíncrono, mantendo controle de continuidade para evitar duplicidades e permitir retomada segura.
Na consulta principal, o uso de SELECT {{TOP}} limita a quantidade de registros por ciclo, conforme o conceito: CONCEITO_SEMAFARO.

Também permite captura manual por uma ou mais chaves no padrão F1_FILIAL-F1_DOC-F1_SERIE-F1_FORNECE-F1_LOJA-F1_TIPO; para cada chave, consulta a mesma origem com filtros dinâmicos e registra o item correspondente para processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_ENTRADAS_CANCELAMENTO.

Operações com Dados

SELECT {{TOP}}
    F1_FILIAL,
    F1_DOC,
    F1_SERIE,
    F1_EMISSAO,
    F1_FORNECE,
    F1_LOJA,
    F1_TIPO,
    F1_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    F1_CHVNFE,
    EXCLUSAO,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_ENTRADAS_CANCELAMENTO (NOLOCK)
WHERE
    CAPTURADO_ISNAPP = 0

SELECT
    F1_FILIAL,
    F1_DOC,
    F1_SERIE,
    F1_EMISSAO,
    F1_FORNECE,
    F1_LOJA,
    F1_TIPO,
    F1_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    F1_CHVNFE,
    EXCLUSAO,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_ENTRADAS_CANCELAMENTO (NOLOCK)
WHERE
    F1_FILIAL = '<F1_FILIAL>'
    AND F1_DOC = '<F1_DOC>'
    AND F1_SERIE = '<F1_SERIE>'
    AND F1_FORNECE = '<F1_FORNECE (opcional)>'
    AND F1_LOJA = '<F1_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 documento de cancelamento) antes de efetivar o envio do cancelamento, podendo redirecionar o recurso para documento de saída quando necessário e persistindo o status final do item.

Rotinas Inteligentes

Cliente Integrado: Antes de enviar o cancelamento ao Protheus, ao validar o vínculo do fornecedor (F1_LOJA-F1_FORNECE). Garante que o cancelamento seja encaminhado apenas para fornecedores reconhecidos no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

Documento de Cancelamento de Entrada: 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-entrada

Estruturação de Dados

O payload de integração é montado a partir do conteúdo do item pendente. Para o envio de cancelamento de documento de entrada, a lista oficial de campos do payload é:

Exemplo de payload enviado:

{
  "F1_FILIAL": "<F1_FILIAL>",
  "F1_DOC": "<F1_DOC>",
  "F1_SERIE": "<F1_SERIE>",
  "F1_EMISSAO": "<F1_EMISSAO>",
  "F1_FORNECE": "<F1_FORNECE>",
  "F1_LOJA": "<F1_LOJA>",
  "F1_TIPO": "<F1_TIPO>",
  "F1_ESPECIE": "<F1_ESPECIE>",
  "F3_DTCANC": "<F3_DTCANC>",
  "F3_CODRSEF": "<F3_CODRSEF>",
  "F3_PROTOC": "<F3_PROTOC>",
  "F1_CHVNFE": "<F1_CHVNFE>"
}

Quando o documento de entrada ainda não estiver integrado e o fluxo exigir envio alternativo, o recurso pode ser trocado para cancelamento de documento de saída e o payload é reestruturado com mapeamento de campos:

Exemplo de payload enviado:

{
  "F2_FILIAL": "<F1_FILIAL>",
  "F2_DOC": "<F1_DOC>",
  "F2_SERIE": "<F1_SERIE>",
  "F2_EMISSAO": "<F1_EMISSAO>",
  "F2_CLIENTE": "<F1_FORNECE>",
  "F2_LOJA": "<F1_LOJA>",
  "F2_TIPO": "<F1_TIPO>",
  "F2_ESPECIE": "<F1_ESPECIE>",
  "F3_DTCANC": "<F3_DTCANC>",
  "F3_CODRSEF": "ENT",
  "F3_PROTOC": "<F3_PROTOC>",
  "F2_CHVNFE": "<F1_CHVNFE>"
}

Tratamento de Dados

Integração com o Protheus

Chamada de integração com o Protheus

Exemplo de payload enviado:

{
  "F1_FILIAL": "<F1_FILIAL>",
  "F1_DOC": "<F1_DOC>",
  "F1_SERIE": "<F1_SERIE>",
  "F1_EMISSAO": "<F1_EMISSAO>",
  "F1_FORNECE": "<F1_FORNECE>",
  "F1_LOJA": "<F1_LOJA>",
  "F1_TIPO": "<F1_TIPO>",
  "F1_ESPECIE": "<F1_ESPECIE>",
  "F3_DTCANC": "<F3_DTCANC>",
  "F3_CODRSEF": "<F3_CODRSEF>",
  "F3_PROTOC": "<F3_PROTOC>",
  "F1_CHVNFE": "<F1_CHVNFE>"
}

Tratamento de retorno:

Tratamento de retorno

Encaminhamento em cenário de erro

Quando o fornecedor ainda não estiver integrado no Protheus, o item não segue para a integração de cancelamento. Ele é marcado como suspenso, armazenando o motivo e a chave de identificação (no padrão F1_LOJA-F1_FORNECE), permitindo retomar o processamento após a regularização do pré-requisito.

Notificação

A notificação de erros seleciona itens com falha do serviço ProtheusCancelamentoDocumentoEntrada na tabela wosk_queue, priorizando os mais antigos pela ordenação por data de processamento. Em seguida, encaminha a notificação 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 e continuidade	Ao consultar a origem WOSK_SERVICO_ENVIA_PROTHEUS_ENTRADAS_CANCELAMENTO com CAPTURADO_ISNAPP = 0 e limite via SELECT {{TOP}}, deve atualizar a posição de execução em wosk_monitor (offset, chave e datas), evitando duplicidades.	Posição persistida em wosk_monitor e itens novos registrados em wosk_queue com chave consistente.
Capturador	Captura manual por chave	Ao informar uma ou mais chaves com pelo menos F1_FILIAL-F1_DOC-F1_SERIE, deve consultar a origem com WHERE dinâmico (incluindo F1_FORNECE/F1_LOJA quando presentes) e registrar os itens correspondentes para processamento.	Itens pendentes registrados em wosk_queue para o serviço ProtheusCancelamentoDocumentoEntrada.
Fila de Processamento	Validações e integração	Ao processar um item pendente do serviço ProtheusCancelamentoDocumentoEntrada, deve validar o pré-requisito do fornecedor (F1_LOJA-F1_FORNECE), decidir o recurso (documento_entrada ou documento_saida) e enviar ao Protheus via PUT com cabeçalho tenantId no padrão <UF>,<F1_FILIAL>.	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 entrada 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.