ProtheusCancelamentoCupomFiscalRelampago (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca encaminha o cancelamento de cupom fiscal do LINX para o Protheus, garantindo validações antes do envio e registro do resultado.

Capturador

Descrição Conceitual

Captura cancelamentos de cupom fiscal a partir de uma fonte dedicada e encaminha cada documento para processamento em fila, anexando itens e parcelas de pagamento para formar o conteúdo completo.

O fluxo suporta captura automática por agendador de tarefas, com processamento cronológico (ordenação/paginação por data), e captura manual por chave no padrão LQ_FILIAL-LQ_DOC-LQ_SERIE-LQ_CLIENTE-LQ_LOJA.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO.

Operações com Dados

Processamento cronológico (ordenação/paginação por data): a captura consulta registros com filtro por DATA_PARA_TRANSFERENCIA, ordena por DATA_PARA_TRANSFERENCIA ASC e pagina com OFFSET/FETCH NEXT.
link: Cronológico

Consulta base da fonte (projeção completa):

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)

Consulta cronológica por lote (string dinâmica):

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '{DATA_PARA_TRANSFERENCIA}'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    {OFFSET} ROWS
FETCH NEXT
    {TOP} ROWS ONLY

Consulta de itens do documento:

SELECT
    LR_FILIAL,
    LR_PRODUTO,
    LR_DESCRI,
    LR_POSIPI,
    LR_ORIGEM,
    LR_QUANT,
    LR_UM,
    LR_TABELA,
    LR_VRUNIT,
    LR_VLRITEM,
    LR_ENTREGA,
    LR_PRCTAB,
    LR_VEND,
    LR_TES,
    LR_CF,
    LR_CLASFIS,
    LR_DESC,
    LR_VALDESC,
    LR_DESCPRO,
    LR_LOCAL,
    LR_DOC,
    LR_SERIE,
    LR_CLIENTE,
    LR_LOJA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO_ITEM (NOLOCK)
WHERE
    LR_FILIAL = '{LQ_FILIAL}'
    AND LR_DOC = '{LQ_DOC}'
    AND LR_SERIE = '{LQ_SERIE}'
    AND LR_CLIENTE = '{LQ_CLIENTE}'
    AND LR_LOJA = '{LQ_LOJA}'

Consulta de parcelas/pagamentos do documento:

SELECT
    L4_FILIAL,
    L4_DOC,
    L4_SERIE,
    L4_CLIENTE,
    L4_LOJA,
    L4_FORMA,
    L4_DATA,
    L4_VALOR,
    L4_MOEDA,
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_XINUTI,
    LQ_DOCCANC,
    LQ_DATCANC,
    LQ_HORCANC,
    L4_DOCCANC,
    L4_DATCANC,
    L4_HORCANC
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO_PGTO (NOLOCK)
WHERE
    L4_FILIAL = '{LQ_FILIAL}'
    AND L4_DOC = '{LQ_DOC}'
    AND L4_SERIE = '{LQ_SERIE}'
    AND L4_CLIENTE = '{LQ_CLIENTE}'
    AND L4_LOJA = '{LQ_LOJA}'

Captura manual: o filtro WHERE é construído dinamicamente conforme a chave informada, restringindo por LQ_FILIAL, LQ_DOC, LQ_SERIE e, quando informado, por LQ_CLIENTE e LQ_LOJA.

SELECT
    LQ_FILIAL,
    LQ_DOC,
    LQ_SERIE,
    LQ_CLIENTE,
    LQ_LOJA,
    LQ_VEND,
    LQ_EMISSAO,
    F3_DTCANC,
    F3_CODRSEF,
    LQ_ESPECIE,
    LQ_XNATOPE,
    LQ_XCANAL,
    LQ_HORA,
    LQ_KEYNFCE,
    LQ_FORMA,
    LQ_DINHEIR,
    LQ_FORMPG,
    LQ_CONDPG,
    LQ_OPERADO,
    LQ_PDV,
    LQ_SITUA,
    LQ_VALMERC,
    LQ_VLRTOT,
    LQ_VLRLIQ,
    LQ_VALBRUT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_CANCELAMENTO_RELAMPAGO (NOLOCK)
WHERE
    LQ_FILIAL = '{LQ_FILIAL}'
    AND LQ_DOC = '{LQ_DOC}'
    AND LQ_SERIE = '{LQ_SERIE}'
    [AND LQ_CLIENTE = '{LQ_CLIENTE}']
    [AND LQ_LOJA = '{LQ_LOJA}']

Fila de Processamento

Descrição Conceitual

A fila recupera um cancelamento pendente e utiliza o conteúdo completo (cabeçalho, itens e parcelas) como payload de integração. Antes do envio, valida dependências e aplica padronizações numéricas obrigatórias para consistência.

Ao final, registra o retorno e a situação do processamento na tabela de fila (wosk_queue), permitindo auditoria, notificação de erros e reprocessamento.

Estruturação de Dados

O payload enviado ao Protheus segue o schema definido no array $field da fila. O registro atual capturado é enriquecido com:

- ITENS: lista retornada por consulta na fonte de itens (associada por filial, documento, série, cliente e loja).
- PARCELAS: lista retornada por consulta na fonte de pagamentos (associada pelos mesmos campos).

Cabeçalho

ITENS

PARCELAS

Exemplo de payload enviado

{
  "LQ_FILIAL": "",
  "LQ_CLIENTE": "",
  "LQ_LOJA": "",
  "LQ_VEND": "",
  "LQ_EMISSAO": "",
  "LQ_DOC": "",
  "LQ_SERIE": "",
  "LQ_ESPECIE": "",
  "LQ_XNATOPE": "",
  "LQ_XCANAL": "",
  "LQ_HORA": "",
  "LQ_KEYNFCE": "",
  "LQ_FORMA": "",
  "LQ_DINHEIR": 0,
  "LQ_FORMPG": "",
  "LQ_CONDPG": "",
  "LQ_OPERADO": "",
  "LQ_PDV": "",
  "LQ_SITUA": "",
  "LQ_VALMERC": 0,
  "LQ_VLRTOT": 0,
  "LQ_VLRLIQ": 0,
  "LQ_VALBRUT": 0,
  "ITENS": [
    {
      "LR_FILIAL": "",
      "LR_PRODUTO": "",
      "LR_DESCRI": "",
      "LR_POSIPI": "",
      "LR_ORIGEM": "",
      "LR_QUANT": 0,
      "LR_UM": "",
      "LR_TABELA": "",
      "LR_VRUNIT": 0,
      "LR_VLRITEM": 0,
      "LR_ENTREGA": "",
      "LR_VEND": "",
      "LR_TES": "",
      "LR_CF": "",
      "LR_CLASFIS": "",
      "LR_VALDESC": 0,
      "LR_LOCAL": "",
      "LR_DOC": "",
      "LR_SERIE": "",
      "LR_CLIENTE": "",
      "LR_LOJA": ""
    }
  ],
  "PARCELAS": [
    {
      "L4_FILIAL": "",
      "L4_DOC": "",
      "L4_SERIE": "",
      "L4_CLIENTE": "",
      "L4_LOJA": "",
      "L4_FORMA": 0,
      "L4_DATA": "",
      "L4_VALOR": 0,
      "L4_MOEDA": 0,
      "LQ_FILIAL": "",
      "LQ_DOC": "",
      "LQ_SERIE": "",
      "F3_DTCANC": "",
      "F3_CODRSEF": "",
      "LQ_XINUTI": "",
      "LQ_DOCCANC": "",
      "LQ_DATCANC": "",
      "LQ_HORCANC": "",
      "L4_DOCCANC": "",
      "L4_DATCANC": "",
      "L4_HORCANC": ""
    }
  ]
}

Tratamento de Dados

Antes do envio ao Protheus, o payload passa por validações e padronizações obrigatórias.

Validação de dependência
- LQ_CLIENTE, LQ_LOJA: exige confirmação de integração prévia do cliente; em falha, o item é marcado como suspenso por dependência.

Padronização numérica (setNumeric)
- LQ_DINHEIR, LQ_VLRTOT, LQ_VLRLIQ, LQ_VALBRUT: normalizados com o padrão do setNumeric(...).
- LR_QUANT, LR_VRUNIT, LR_VLRITEM, LR_VALDESC: normalizados com o padrão do setNumeric(...).
- L4_FORMA, L4_VALOR, L4_MOEDA: normalizados com o padrão do setNumeric(...).

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: <primeiros 2 caracteres de LQ_FILIAL>,<LQ_FILIAL>

Tratamento de retorno
- Ausência de resposta: gera erro com mensagem JSON: NÃO HOUVE RESPOSTA.
- Resposta inválida/inesperada: se não for array ou não contiver Mensagem, gera erro com JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA.
- Condição de erro: quando existir code na resposta ou quando Mensagem = ERRO, o processamento é marcado como falha.
- Condição de sucesso: quando a resposta não indica erro, o processamento é marcado como sucesso e aciona o registro do cancelamento integrado.

Rotinas Inteligentes

Cliente Integrado (rotina inteligente): chamada no início do processamento, antes da integração do cancelamento. Garante que o cliente esteja integrado no Protheus para permitir o envio do cupom.
link: Cliente Integrado

Documento de Cancelamento de Cupom Fiscal (rotina inteligente): chamada após retorno de sucesso da integração do cupom. Registra/valida o cancelamento integrado para manter consistência do processo.
link: Documento de Cancelamento de Cupom Fiscal

Tratamento de retorno

Persistência do resultado: o item processado é atualizado na tabela wosk_queue (base integrador), registrando retorno, mensagem, requisição, tempo e situação de processamento, incluindo informações de suspensão por dependência quando aplicável.

Situações utilizadas:
- 1: Em envio.
- 2: Sucesso.
- 3: Suspenso por dependência.
- 4: Erro.

Encaminhamento em cenário de erro

Quando a falha ocorre por dependência prévia (cliente não integrado), o item pode ser marcado como suspenso e permanecer aguardando regularização. Demais falhas permanecem como erro com mensagem registrada para correção e reprocessamento.

Notificação

SELECT
    `token`,
    `acao`,
    `chave`,
    `data_adicionado`,
    `data`,
    `mensagem` AS 'ERRO'
FROM
    `{BASE_INTEGRADOR}`.`wosk_queue`
WHERE
    `acao` = 'ProtheusCancelamentoCupomFiscalRelampago'
    AND `situacao` = 4
ORDER BY
    `data` ASC

Fluxo do Processo

Critérios de Aceitação