ProtheusCancelamentoDocumentoEntrada (STATUS: REVISANDO)

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

Este serviço 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 Semáforo.

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

~~Leitura (captura por critério de pendência)~~~~: consulta a origem com filtro de pendência (~~CAPTURADO_ISNAPP = 0~~), aplicando limite dinâmico via~~ {{TOP}}.

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

Leitura (captura manual por chave): consulta a mesma origem aplicando WHERE construído dinamicamente. A chave exige no mínimo F1_FILIAL-F1_DOC-F1_SERIE; os filtros de F1_FORNECE e F1_LOJA só são incluídos quando presentes na chave.

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)>'

Operações com Dados

Leitura (captura por critério de pendência): consulta a origem com filtro de pendência (CAPTURADO_ISNAPP = 0), aplicando limite dinâmico via {{TOP}}.

Persistência (controle de continuidade): grava/atualiza a posição de execução na tabela wosk_monitor, incluindo evento, offset, filtro, chave_posicao, situacao, data_posicao e data_iniciado.
Persistência (itens pendentes): registra os itens para processamento na fila de processamento (banco integrador), utilizando chave composta no padrão F1_FILIAL-F1_DOC-F1_SERIE-F1_FORNECE-F1_LOJA-F1_TIPO.

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

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

Campo no payload (Protheus)	Campo de origem
`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`

~~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:

Campo no payload (Protheus)	Regra / origem
`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`	fixo `ENT`
`F3_PROTOC`	`F3_PROTOC`
`F2_CHVNFE`	`F1_CHVNFE`

~~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

Transformações aplicadas no payload antes do envio:

F3_CODRSEF: avaliado como numérico para decidir se a validação do documento de cancelamento será exigida (quando diferente de 102).
endpoint (recurso Protheus): definido como documento_entrada por padrão e trocado para documento_saida quando o documento de entrada não estiver integrado e o fluxo indicar envio alternativo; nesse cenário, o payload é reestruturado para o conjunto F2_* e F3_CODRSEF recebe o valor fixo ENT.
tenantId (cabeçalho): formado a partir de F1_FILIAL no padrão <primeiros 2 caracteres>,<F1_FILIAL>.
chave (notificação): decomposta em F1_FILIAL, F1_DOC, F1_SERIE, F1_FORNECE, F1_LOJA, F1_TIPO para apresentar os componentes do registro com falha.
ERRO (notificação): se a mensagem contiver marcador de SQL Server, é extraído o trecho relevante a partir de [SQL Server] até antes de Error :; se existir :, é mantido apenas o conteúdo após o primeiro :; sequências de quebra de linha (escapadas ou reais) são convertidas para quebra de linha padrão.
data_adicionado, data (notificação): formatados para d/m/Y H:i:s.

Integração com o Protheus

Chamada: Requisição HTTP
Recurso: documento_entrada ou documento_saida (conforme regra do processo)
Método HTTP: PUT
Cabeçalhos:
- tenantId:"tenantId": "<UF>,<F1_FILIAL>"

Exemplo de payload enviado (JSON):

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

Sucesso: quando o retorno estiver decodificado e não houver indicador de erro, o registro é finalizado como integrado.
Erro: quando houver exceção no fluxo, retorno ausente, retorno inválido ou indicador de erro, o registro é finalizado como erro com o retorno armazenado no campo de auditoria.
Suspensão: quando a validação prévia do fornecedor não estiver atendida, o registro é marcado como suspenso e registra o tipo e a chave de suspensão para permitir retomada após correção do pré-requisito.
Persistência de status: o registro é atualizado na fila de processamento, incluindo mensagem, retorno decodificado, tempo de processamento e situação final.
Persistência de limpeza pós-sucesso: quando aplicável, são removidos registros de suporte nas tabelas ProtheusDocumentoEntrada, ProtheusDocumentoEntradaPontual, ProtheusDevolucaoCupomFiscal, ProtheusDocumentoEntradaLog, ProtheusDocumentoEntradaBase e ProtheusDocumentoEntradaFull, utilizando chaves derivadas de F1_FILIAL, F1_DOC, F1_SERIE, F1_FORNECE e F1_LOJA.

Encaminhamento em cenário de erro

Quando o fornecedor ainda não estiver integrado no Protheus, o registro 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

AExiste um mecanismo de notificação deque ~~erros~~identifica ~~seleciona~~os ~~registros~~itens com ~~falha do serviço~~ ProtheusCancelamentoDocumentoEntradaerro na fila de processamento, ~~priorizando os mais antigos pela ordenação~~ordenando por data de ~~processamento.~~processamento Eme ~~seguida,~~enviando ~~encaminha~~em um relatório a ~~notificação para os~~ destinatários ~~configurados, incluindo a chave do registro e a mensagem de erro higienizada.~~

pré-definidos.

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 registros novos registrados na fila de processamento 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 registros correspondentes para processamento.	~~registros~~Registros pendentes registrados na fila de processamento para o serviço `ProtheusCancelamentoDocumentoEntrada`.
Fila de Processamento	Validações e integração	Ao processar um registro 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>`.	~~fila~~Fila de processamento atualizado com situação final coerente: sucesso, suspenso ou 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 registro como sucesso e registrar a mensagem de resalva definida no processo.	~~registro~~Registro finalizado como sucesso na fila de processamento, com mensagem de resalva persistida.