ProtheusDevolucaoCupomFiscalPontual (STATUS: REVISADO)

Documentação Técnica

Histórico de Versões

Descrição

Este serviço integra devoluções de cupom fiscal do LINX para o Protheus, capturando documentos por dia e encaminhando cada um para processamento assíncrono.

Capturador

Descrição Conceitual

A captura automática utiliza processamento cronológico por dia, aplicando filtro DATA_PARA_TRANSFERENCIA BETWEEN <início_do_dia> AND <fim_do_dia>, com ordenação temporal e paginação para garantir a correta sequência de processamento dos registros ao longo da execução.

Permite a captura manual de uma ou mais devoluções de cupom fiscal mediante a informação das chaves, com validação obrigatória do formato no padrão F1_FILIAL-F1_DOC-LQ_SERIE-F1_FORNECE-F1_LOJA. Caso a chave informada esteja fora do padrão esperado, o processo é imediatamente interrompido com erro de chave inválida, garantindo integridade e previsibilidade no fluxo.

Fonte

Consulta principal: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL.

Operações com Dados

Leitura: Consulta de registros com base no campo DATA_PARA_TRANSFERENCIA, aplicando filtro diário no formato DATA_PARA_TRANSFERENCIA BETWEEN dataInicio AND dataFim.

Ordenação: Os registros são ordenados de forma crescente por DATA_PARA_TRANSFERENCIA ASC, garantindo processamento cronológico.

Paginação: A consulta utiliza OFFSET/FETCH NEXT para paginação dos resultados, permitindo o processamento incremental e controlado dos registros.
link: Cronológico

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

SELECT
    F1_FILIAL,
    F1_DOC,
    LQ_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,
    F1_XCBSIBS,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL (NOLOCK)

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

SELECT ... FROM WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA BETWEEN '{dataInicio}' AND '{dataFim}'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    {OFFSET} ROWS
FETCH NEXT
    {TOP} ROWS ONLY

Consulta de itens do documento:

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,
    DKD_XCBSBS,
    DKD_XCBSAL,
    DKD_XCBSVL,
    DKD_XIBSBS,
    DKD_XIBSAL,
    DKD_XIBSVL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM_PONTUAL (NOLOCK)
WHERE
    D1_FILIAL = '{F1_FILIAL}'
    AND D1_DOC = '{F1_DOC}'
    AND D1_SERIE = '{LQ_SERIE}'
    AND D1_FORNECE = '{F1_FORNECE}'
    AND D1_LOJA = '{F1_LOJA}'

Captura manual: o filtro WHERE é montado dinamicamente a partir da chave, restringindo por F1_FILIAL, F1_DOC, LQ_SERIE, F1_FORNECE e F1_LOJA. Chave inválida quando count(chave) < 5.

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.

Antes do envio, valida a integração prévia do cliente (F1_LOJA-F1_FORNECE); quando houver itens com documento de origem (D1_NFORI, D1_SERIORI), classifica-os em cupons de troca (fornecedor 359436040 ou data de origem anterior a 2025-01-01) ou documentos de devolução Omni (demais casos), validando cada grupo via rotinas inteligentes. Em falha, o registro é marcado como suspenso por dependência. Ao final, registra o retorno e a situação na tabela de fila.

Estruturação de Dados

ITENS_DEV

Exemplo de payload enviado

{
  "CAB_DEV": {
    "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,
    "BASEPS3": 0,
    "VALPS3": 0,
    "BASECF3": 0,
    "VALCF3": 0,
    "F1_II": 0,
    "F1CIF": 0,
    "P1_PLIQUI": 0,
    "P1_PBRUTO": 0,
    "P1_VOLUME1": 0,
    "F1_MOEDA": 0,
    "F1_TIPO_NF": "",
    "F1_CHVNFE": "",
    "F1_DAUTNFE": "",
    "F1_HAUTNFE": "",
    "F1_PROTOC": "",
    "F1_NFELETR": "",
    "F1_EMINFE": "",
    "F1_HORNFE": "",
    "F1_TPFRETE": "",
    "F1_TPCTE": "",
    "F1_ORIGLAN": "",
    "F1_NFORIG": "",
    "F1_SERORIG": "",
    "F1_NUMTRIB": "",
    "F1_PREFIXO": "",
    "F1_STATUS": "",
    "F1_SDOC": "",
    "F1_TRANSP": "",
    "F1_XNATOPE": "",
    "F1_XCANAL": "",
    "F3_DTCANC": "",
    "F3_CODRSEF": "",
    "F1_XCBSIBS": "",
    "ITENS_DEV": []
  }
}

Tratamento de Dados

• F1_FORNECE, F1_LOJA: valida dependência de integração prévia do cliente por meio da rotina Cliente Integrado; em caso de falha, o registro é marcado como suspenso por dependência com suspensaoTipo = ProtheusCliente e suspensaoChave = F1_LOJA-F1_FORNECE.
• D1_NFORI, D1_SERIORI: quando presentes nos itens, indicam documento de origem. Os registros são classificados como cupons de troca (quando o fornecedor for 359436040 ou D1_DATORI anterior a 2025-01-01) ou como documentos de devolução Omni (demais casos). Cupons de troca são validados pela rotina Cupom Ecommerce Integrado (suspensaoTipo = ProtheusCupomEcommerce), enquanto documentos Omni são validados pela rotina Nota Fiscal Omni Integrado (suspensaoTipo = ProtheusNotaFiscalOmni).
• 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: normalização numérica dos campos de cabeçalho utilizando o padrão setNumeric(...).
• D1_QUANT: normalização numérica com precisão de 3 casas decimais, utilizando setNumeric(..., 3, false).
• D1_VUNIT: normalização numérica com precisão de 5 casas decimais, utilizando setNumeric(..., 5, false).
• 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, DKD_XCBSBS, DKD_XCBSAL, DKD_XCBSVL, DKD_XIBSBS, DKD_XIBSAL, DKD_XIBSVL: normalização numérica dos campos de itens utilizando o padrão setNumeric(...).

Integração com o Protheus

Chamada de integração com o Protheus

• Chamada: Requisição HTTP
  
• Recurso: /rest/cupom
  
• Método HTTP: POST
  
• Cabeçalhos:
    - tenantId: <primeiros 2 caracteres de F1_FILIAL>,<F1_FILIAL>
  
  

Rotinas Inteligentes

Cupom Ecommerce Integrado: chamada antes do envio ao Protheus, quando houver itens classificados como cupons de troca (fornecedor 359436040 ou data de origem anterior a 2025-01-01). Garante que os cupons de origem estejam integrados para permitir a devolução.
link: Cupom Ecommerce Integrado

Nota Fiscal Omni Integrado: chamada antes do envio ao Protheus, quando houver itens classificados como documentos de devolução Omni (data de origem a partir de 2025-01-01 ou vazia). Garante que os documentos de origem estejam integrados para permitir a devolução.
link: Nota Fiscal Omni Integrado

Cliente Integrado: chamada no início do processamento, antes do envio ao Protheus. Garante que o cliente do documento esteja integrado para permitir a integração da devolução de cupom fiscal.
link: Cliente Integrado

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.

Ajuste de sucesso por mensagem: quando Mensagem Detalhada contém indicação de “já cadastrado”, a resposta é tratada como sucesso (Mensagem = OK) e o campo code é removido (se existir).

Condição de erro: quando existir code na resposta ou quando Mensagem = ERRO, o processamento é marcado como falha.

Condição de sucesso: quando o retorno é considerado OK, o registro é finalizado como sucesso.

Persistência do resultado: o registro processado é atualizado na tabela Fila de Processamento (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.

Encaminhamento em cenário de erro

Quando a falha ocorre por dependência prévia (cliente não integrado, cupom ecommerce ou documento Omni ainda pendente), o registro 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

Fluxo do Processo

Critérios de Aceitação