ProtheusNotaFiscalOmniCancelamento (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

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