ProtheusDevolucaoCupomFiscal (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza a integração de devoluções de cupom fiscal do LINX para o Protheus, garantindo que cada documento de entrada (devolução) seja capturado, preparado com seus itens e encaminhado para envio.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais documentos de devolução de cupom fiscal mediante a informação das chaves no padrão F1_FILIAL-F1_DOC-F1_SERIE-F1_FORNECE-F1_LOJA, consultando a origem e carregando os itens antes de registrar o item para processamento assíncrono. Caso a chave informada esteja fora do padrão (menos de 3 partes), o processo é interrompido com erro de chave inválida.

A captura por data 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_DEVOLUCAO_CABECALHO e view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM.

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

SELECT
    F1_FILIAL,
    F1_DOC,
    F1_SERIE,
    F1_FORNECE,
    F1_LOJA,
    F1_COND,
    F1_XNATOPE,
    F1_XCANAL,
    F1_XNATUR,
    F1_DUPL,
    F1_EMISSAO,
    F1_DTDIGIT,
    F1_RECBMTO,
    F1_EST,
    F1_ESTPRES,
    F1_TIPO,
    F1_FORMUL,
    F1_ESPECIE,
    F1_VALMERC,
    F1_VALBRUT,
    F1_FRETE,
    F1_DESPESA,
    F1_SEGURO,
    F1_DESCONTO,
    F1_BASEICM,
    F1_VALICM,
    F1_BASEIPI,
    F1_VALIPI,
    F1_BRICMS,
    F1_ICMSRET,
    F1_BASIMP5,
    F1_VALIMP5,
    F1_BASIMP6,
    F1_VALIMP6,
    BASEPS3,
    VALPS3,
    BASECF3,
    VALCF3,
    F1_MUORITR,
    F1_UFORITR,
    F1_MUDESTR,
    F1_UFDESTR,
    F1_II,
    F1CIF,
    F1_TIPO_NF,
    F1_CHVNFE,
    F1_DAUTNFE,
    F1_HAUTNFE,
    F1_PROTOC,
    F1_NFELETR,
    F1_EMINFE,
    F1_HORNFE,
    F1_TPFRETE,
    F1_TPCTE,
    P1_PLIQUI,
    P1_PBRUTO,
    P1_ESPECI1,
    P1_VOLUME1,
    F1_ORIGLAN,
    F1_NFORIG,
    F1_SERORIG,
    F1_NUMTRIB,
    F1_MOEDA,
    F1_PREFIXO,
    F1_STATUS,
    F1_ESTPRES_2,
    F1_SDOC,
    F1_TRANSP,
    F3_DTCANC,
    F3_CODRSEF,
    CREPROCESSA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<data_posicao>'
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
    ... (colunas da view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO)
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO (NOLOCK)
WHERE
    F1_FILIAL = '<chave[0]>'
    AND F1_DOC = '<chave[1]>'
    AND F1_SERIE = '<chave[2]>'
    AND F1_FORNECE = '<chave[3]>'
    AND F1_LOJA = '<chave[4]>'

Consulta utilizada para carregar os itens do documento (WHERE construído dinamicamente a partir de D1_FILIAL, D1_DOC, D1_SERIE, D1_FORNECE, D1_LOJA):

SELECT
    D1_FILIAL,
    D1_ITEM,
    D1_COD,
    B1_TP,
    B1_UM,
    B1_LOCAL,
    B1_GRUPO,
    D1_TEC,
    D1_QUANT,
    D1_VUNIT,
    D1_TOTAL,
    D1_DESC,
    D1_VALDESC,
    D1_SEGURO,
    D1_VALFRE,
    D1_DESPESA,
    D1_EMISSAO,
    D1_DTDIGIT,
    D1_DOC,
    D1_SERIE,
    F1_SDOC,
    D1_TIPO,
    D1_FORNECE,
    D1_LOJA,
    D1_CLASFIS,
    D1_OPER,
    D1_CF,
    D1_BASEIPI,
    D1_IPI,
    D1_VALIPI,
    D1_BASEICM,
    D1_PICM,
    D1_VALICM,
    D1_VRDICMS,
    D1_VALANTI,
    D1_ICMSDIF,
    D1_BASFECP,
    D1_ALQFECP,
    D1_VALFECP,
    D1_ALIQCMP,
    D1_DIFAL,
    D1_BSFCCMP,
    D1_ALFCCMP,
    D1_VFCPDIF,
    D1_AFCPANT,
    D1_VFCPANT,
    D1_BRICMS,
    D1_ALIQSOL,
    D1_MARGEM,
    D1_ICMSRET,
    D1_BSFCPST,
    D1_ALFCPST,
    D1_VFECPST,
    D1_BASIMP5,
    D1_ALQIMP5,
    D1_VALIMP5,
    D1_BASIMP6,
    D1_ALQIMP6,
    D1_VALIMP6,
    D1_ALIQII,
    D1_II,
    D1_CIF,
    D1_TIPO_NF,
    D1_OP,
    D1_CC,
    D1_CONTA,
    D1_PESO,
    D1_DATORI,
    D1_NFORI,
    D1_SERIORI,
    D1_ITEMORI,
    D1_ORIGLAN,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM (NOLOCK)
WHERE
    D1_FILIAL = '<F1_FILIAL>'
    AND D1_DOC = '<F1_DOC>'
    AND D1_SERIE = '<F1_SERIE>'
    AND D1_FORNECE = '<F1_FORNECE>'
    AND D1_LOJA = '<F1_LOJA>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO para obter o registro atual do documento de devolução e construir o identificador de processamento com base em F1_FILIAL, F1_DOC, F1_SERIE, F1_FORNECE e F1_LOJA.

- Carregamento de itens: para cada registro atual, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM filtrando por D1_FILIAL, D1_DOC, D1_SERIE, D1_FORNECE, D1_LOJA e agrega os itens retornados no campo ITENS, formando o conjunto completo (cabeçalho + itens) para integração.

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

- Registro para processamento: cada documento de devolução capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusDevolucaoCupomFiscal, com o conteúdo vindo da origem (incluindo ITENS) 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, situação e informações para auditoria.

Estruturação de Dados

{
  "F1_FILIAL": "",
  "F1_DOC": "",
  "F1_SERIE": "",
  "F1_FORNECE": "",
  "F1_LOJA": "",
  "F1_COND": "",
  "F1_XNATUR": "",
  "F1_DUPL": "",
  "F1_EMISSAO": "",
  "F1_DTDIGIT": "",
  "F1_RECBMTO": "",
  "F1_EST": "",
  "F1_ESTPRES": "",
  "F1_TIPO": "",
  "F1_FORMUL": "",
  "F1_ESPECIE": "",
  "F1_VALMERC": 0,
  "F1_VALBRUT": 0,
  "F1_FRETE": 0,
  "F1_DESPESA": 0,
  "F1_SEGURO": 0,
  "F1_DESCONT": 0,
  "F1_BASEICM": 0,
  "F1_VALICM": 0,
  "F1_BASEIPI": 0,
  "F1_VALIPI": 0,
  "F1_BRICMS": 0,
  "F1_ICMSRET": 0,
  "F1_BASIMP5": 0,
  "F1_VALIMP5": 0,
  "F1_BASIMP6": 0,
  "F1_VALIMP6": 0,
  "F1_BASEPS3": 0,
  "F1_VALPS3": 0,
  "F1_BASECF3": 0,
  "F1_VALCF3": 0,
  "F1_MUORITR": "",
  "F1_UFORITR": "",
  "F1_MUDESTR": "",
  "F1_UFDESTR": "",
  "F1_II": 0,
  "F1_CIF": 0,
  "F1_TIPO_NF": "",
  "F1_CHVNFE": "",
  "F1_DAUTNFE": "",
  "F1_HAUTNFE": "",
  "F3_PROTOC": "",
  "F1_NFELETR": "",
  "F1_EMINFE": "",
  "F1_HORNFE": "",
  "F1_TPFRETE": "",
  "F1_TPCTE": "",
  "F1_PLIQUI": 0,
  "F1_PBRUTO": 0,
  "F1_ESPECI1": "",
  "F1_VOLUME1": 0,
  "F1_ORIGLAN": "",
  "F1_NFORIG": "",
  "F1_SERORIG": "",
  "F1_NUMTRIB": "",
  "F1_MOEDA": 0,
  "F1_PREFIXO": "",
  "F1_STATUS": "",
  "F1_SDOC": "",
  "F1_TRANSP": "",
  "F1_XNATOPE": "",
  "F1_XCANAL": "",
  "F3_DTCANC": "",
  "F3_CODRSEF": "",
  "CREPROCESSA": "",
  "ITENS": [
    {
      "D1_FILIAL": "",
      "D1_ITEM": "",
      "D1_COD": "",
      "D1_TP": "",
      "D1_UM": "",
      "D1_LOCAL": "",
      "D1_GRUPO": "",
      "D1_TEC": "",
      "D1_QUANT": 0,
      "D1_VUNIT": 0,
      "D1_TOTAL": 0,
      "D1_DESC": 0,
      "D1_VALDESC": 0,
      "D1_SEGURO": 0,
      "D1_VALFRE": 0,
      "D1_DESPESA": 0,
      "D1_EMISSAO": "",
      "D1_DTDIGIT": "",
      "D1_DOC": "",
      "D1_SERIE": "",
      "D1_SDOC": "",
      "D1_TIPO": "",
      "D1_FORNECE": "",
      "D1_LOJA": "",
      "D1_CLASFIS": "",
      "D1_OPER": "",
      "D1_CF": "",
      "D1_BASEIPI": 0,
      "D1_IPI": 0,
      "D1_VALIPI": 0,
      "D1_BASEICM": 0,
      "D1_PICM": 0,
      "D1_VALICM": 0,
      "D1_VRDICMS": 0,
      "D1_VALANTI": 0,
      "D1_ICMSDIF": 0,
      "D1_BASFECP": 0,
      "D1_ALQFECP": 0,
      "D1_VALFECP": 0,
      "D1_ALIQCMP": 0,
      "D1_DIFAL": 0,
      "D1_BSFCCMP": 0,
      "D1_ALFCCMP": 0,
      "D1_VFCPDIF": 0,
      "D1_AFCPANT": 0,
      "D1_VFCPANT": 0,
      "D1_BRICMS": 0,
      "D1_ALIQSOL": 0,
      "D1_MARGEM": 0,
      "D1_ICMSRET": 0,
      "D1_BSFCPST": 0,
      "D1_ALFCPST": 0,
      "D1_VFECPST": 0,
      "D1_BASIMP5": 0,
      "D1_ALQIMP5": 0,
      "D1_VALIMP5": 0,
      "D1_BASIMP6": 0,
      "D1_ALQIMP6": 0,
      "D1_VALIMP6": 0,
      "D1_ALIQII": 0,
      "D1_II": 0,
      "D1_CIF": 0,
      "D1_TIPO_NF": "",
      "D1_OP": "",
      "D1_CC": "",
      "D1_CONTA": "",
      "D1_PESO": 0,
      "D1_DATORI": "",
      "D1_NFORI": "",
      "D1_SERIORI": "",
      "D1_ITEMORI": "",
      "D1_ORIGLAN": ""
    }
  ]
}

Tratamento de Dados

- Normalização numérica (cabeçalho): F1_VALMERC, F1_VALBRUT, F1_FRETE, F1_DESPESA, F1_SEGURO, F1_DESCONT, F1_BASEICM, F1_VALICM, F1_BASEIPI, F1_VALIPI, F1_BRICMS, F1_ICMSRET, F1_BASIMP5, F1_VALIMP5, F1_BASIMP6, F1_VALIMP6, F1_BASEPS3, F1_VALPS3, F1_BASECF3, F1_VALCF3, F1_II, F1_CIF, F1_PLIQUI, F1_PBRUTO, F1_VOLUME1, F1_MOEDA: normalizados via setNumeric().

- Normalização numérica com precisão específica (itens): D1_QUANT normalizado com 3 casas decimais (setNumeric(..., 3, false)); D1_VUNIT normalizado com 5 casas decimais (setNumeric(..., 5, false)).

- Normalização numérica (itens): D1_TOTAL, D1_DESC, D1_VALDESC, D1_SEGURO, D1_VALFRE, D1_DESPESA, D1_BASEIPI, D1_IPI, D1_VALIPI, D1_BASEICM, D1_PICM, D1_VALICM, D1_VRDICMS, D1_VALANTI, D1_ICMSDIF, D1_BASFECP, D1_ALQFECP, D1_VALFECP, D1_ALIQCMP, D1_DIFAL, D1_BSFCCMP, D1_ALFCCMP, D1_VFCPDIF, D1_AFCPANT, D1_VFCPANT, D1_BRICMS, D1_ALIQSOL, D1_MARGEM, D1_ICMSRET, D1_BSFCPST, D1_ALFCPST, D1_VFECPST, D1_BASIMP5, D1_ALQIMP5, D1_VALIMP5, D1_BASIMP6, D1_ALQIMP6, D1_VALIMP6, D1_ALIQII, D1_II, D1_CIF, D1_PESO: normalizados via setNumeric().

- Reestruturação de itens duplicados: quando houver D1_ITEM repetido em ITENS, os itens são renumerados sequencialmente (1, 2, 3, ...) para evitar conflito com o Protheus.

- Validação pré-integração (cliente): chamada de setProtheusClienteIntegrado com chave F1_LOJA-F1_FORNECE antes de prosseguir; em caso de falha, o item é suspenso com suspensaoTipo = ProtheusCliente e situacao = 3.

- Validação pré-integração (cupom e-commerce): quando existirem itens com D1_FORNECE = 359436040 ou itens com D1_DATORI anterior a 01/01/2025, é construída a lista de chaves D1_FILIAL-D1_NFORI-D1_SERIORI-D1_FORNECE-D1_LOJA e validada via setProtheusCupomEcommerceIntegrado; em caso de falha, suspensão com suspensaoTipo = ProtheusCupomEcommerce.

- Validação pré-integração (nota fiscal omni): quando existirem itens com documento de origem a partir de 01/01/2025 e fornecedor diferente de 359436040, é construída a lista de chaves e validada via setProtheusNotaFiscalOmniIntegrado; em caso de falha, suspensão com suspensaoTipo = ProtheusNotaFiscalOmni.

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

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: documento_entrada
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF>,<F1_FILIAL>, em que <UF> é o prefixo de 2 caracteres de F1_FILIAL

Rotinas Inteligentes

- Cliente Integrado: chamada antes de enviar o documento ao Protheus e após validações de cupom/nota, com chave F1_LOJA-F1_FORNECE. Garante que o cliente esteja integrado antes de prosseguir com a integração do documento de devolução.
link: Cliente Integrado

- Cupom Ecommerce Integrado: chamada quando existirem itens de cupom de troca (fornecedor 359436040 ou documento de origem anterior a 01/01/2025). Valida que os cupons de origem estejam integrados antes de enviar a devolução.
link: Cupom Ecommerce Integrado

- Nota Fiscal Omni Integrado: chamada quando existirem itens de documento de devolução omni (documento de origem a partir de 01/01/2025 e fornecedor diferente de 359436040). Valida que os documentos de origem estejam integrados antes de prosseguir.
link: Nota Fiscal Omni Integrado

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 OK e code estiver vazio ou ausente, finalizando com situacao = 2.

Tratamento especial: quando a mensagem detalhada contiver o padrão "ja cadastrado" (case insensitive), o retorno é considerado sucesso (Mensagem ajustado para OK e code removido se existir).

Mensagem detalhada: prioriza Mensagem Detalhada quando disponível; se for array, extrai de erros tipo ou erros devolucao[0].mensagem conforme o caso.

Reprocessamento em cenário de erro: quando houver falha na validação pré-integração (cliente, cupom e-commerce ou nota fiscal omni não integrado), o item é marcado como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave para encaminhamento posterior.

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 = 3 em suspensão, 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. Em caso de suspensão (cliente, cupom e-commerce ou nota fiscal omni não integrado), o item é marcado com situacao = 3 e suspensaoTipo/suspensaoChave para encaminhamento posterior.

Notificação

Fluxo do Processo

Critérios de Aceitação