ProtheusInutilizacaoCupomFiscal (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza a inutilização de cupons fiscais do LINX para o Protheus, garantindo que cada registro seja identificado, preparado e encaminhado para envio da solicitação de inutilização.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais cupons fiscais para inutilização mediante a informação das chaves no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA. Caso a chave informada esteja fora do padrão (menos de 5 partes separadas por hífen), o processo é interrompido com erro de chave inválida.

A captura automática consulta a origem filtrando por DATA_PARA_TRANSFERENCIA, ordenando por DATA_PARA_TRANSFERENCIA ASC e paginando por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico. A execução periódica pode ser acionada por agendador de tarefas.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_INUTILIZACAO.

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

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_INUTILIZACAO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <offset> ROWS FETCH NEXT <top> ROWS ONLY

Consulta utilizada na captura manual (WHERE construído dinamicamente a partir das chaves informadas):

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_ESPECIE,
    F3_DTCANC,
    F3_CODRSEF,
    F3_PROTOC,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_INUTILIZACAO (NOLOCK)
WHERE
    LQ_FILIAL = '<chave[0]>'
    AND LQ_DOC = '<chave[1]>'
    AND LQ_SERIE = '<chave[2]>'
    AND LQ_CLIENTE = '<chave[3]>'
    AND LQ_LOJA = '<chave[4]>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_INUTILIZACAO para obter os registros de cupons fiscais a inutilizar.

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

- Chave de fila: para cada registro, a chave é montada como LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA.

- Registro para processamento: cada cupom fiscal capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusInutilizacaoCupomFiscal, 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.

Estruturação de Dados

{
  "LQ_FILIAL": "",
  "LQ_DOC": "",
  "LQ_SERIE": "",
  "LQ_CLIENTE": "",
  "LQ_LOJA": "",
  "LQ_ESPECIE": "",
  "F3_DTCANC": "",
  "F3_CODRSEF": "",
  "F3_PROTOC": ""
}

Tratamento de Dados

- Cabeçalho de integração: o header tenantId é gerado como <UF>,<LQ_FILIAL>, em que <UF> é o prefixo de 2 caracteres de LQ_FILIAL.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: cupom
- Método HTTP: PUT
- Cabeçalhos:
  - tenantId: <UF>,<LQ_FILIAL> (UF = 2 primeiros caracteres de LQ_FILIAL)

Tratamento de retorno

Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como erro (situacao = 4).

Resposta inválida/inesperada: quando não for possível obter Mensagem ou o retorno não for array, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera erro quando Mensagem for igual a ERRO ou quando code estiver presente (não vazio). Em ambos os casos, situacao = 4. Sucesso quando Mensagem for diferente de ERRO e code estiver vazio ou ausente, finalizando com situacao = 2. A mensagem consolidada prioriza Mensagem Detalhada quando disponível.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada (priorizando Mensagem Detalhada quando disponível), a situação final (situacao = 2 em sucesso, situacao = 4 em erro) e o tempo de processamento.

Encaminhamento em cenário de erro

Quando houver falha por ausência de resposta, retorno inválido, Mensagem igual a ERRO ou presença de code, o item permanece registrado em wosk_queue com detalhes do retorno e mensagem para acompanhamento e eventual reprocessamento.

Notificação

Fluxo do Processo

Critérios de Aceitação