ProtheusDevolucaoCupomFiscalPontual (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, capturando documentos por dia e encaminhando cada um para processamento em fila.

Capturador

Descrição Conceitual

Captura devoluções de cupom fiscal a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL e encaminha cada documento (com seus itens) para processamento em fila. A captura suporta processamento cronológico por dia (filtro DATA_PARA_TRANSFERENCIA BETWEEN do início ao fim do dia, ordenação e paginação), e também permite captura manual por chave no padrão F1_FILIAL-F1_DOC-LQ_SERIE-F1_FORNECE-F1_LOJA.

A origem dos dados é a view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL, consultada com projeção predefinida. O filtro WHERE DATA_PARA_TRANSFERENCIA BETWEEN 'dataInicio' AND 'dataFim' (dataInicio = 00:00:00, dataFim = 23:59:59 do dia) e a ordenação por DATA_PARA_TRANSFERENCIA ASC com OFFSET/FETCH NEXT são aplicados na captura automática. Ao concluir o dia, o próximo dia é agendado. Para cada registro retornado, os itens são obtidos da view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM_PONTUAL e o documento é registrado na fila de processamento.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL.

Itens: view WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_ITEM_PONTUAL.

Operações com Dados

Processamento cronológico (ordenação/paginação por data): a captura consulta registros com filtro por dia (DATA_PARA_TRANSFERENCIA BETWEEN dataInicio AND dataFim), ordena por DATA_PARA_TRANSFERENCIA ASC e pagina com OFFSET/FETCH NEXT.
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 item é marcado como suspenso por dependência. Ao final, registra o retorno e a situação na tabela de fila.

Estruturação de Dados

O payload enviado ao Protheus segue o schema definido no array $field da fila. Reestruturação: o conteúdo da fila chega com ITENS; o processo renomeia para ITENS_DEV, envolve o cabeçalho em CAB_DEV e aplica getConteudo para mapear os campos conforme o schema. Abaixo está o mapeamento oficial de origem → payload.

Cabeçalho (CAB_DEV)

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

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

Validação de dependência
- F1_FORNECE, F1_LOJA: exige confirmação de integração prévia do cliente via rotina inteligente Cliente Integrado; em falha, o item é marcado como suspenso por dependência (suspensaoTipo = ProtheusCliente, suspensaoChave = F1_LOJA-F1_FORNECE).
- Quando houver itens com documento de origem (D1_NFORI, D1_SERIORI): classifica em cupons de troca (fornecedor = 359436040 ou D1_DATORI anterior a 2025-01-01) ou documentos de devolução Omni (demais casos); valida cupons de troca via Cupom Ecommerce Integrado (suspensaoTipo = ProtheusCupomEcommerce) e documentos Omni via Nota Fiscal Omni Integrado (suspensaoTipo = ProtheusNotaFiscalOmni).

Padronização numérica (setNumeric)
- 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 com o padrão do setNumeric(...).

- D1_QUANT: normalizado com 3 casas decimais (setNumeric(..., 3, false)).
- D1_VUNIT: normalizado com 5 casas decimais (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: 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: POST
- Cabeçalhos:
  - tenantId: <primeiros 2 caracteres de F1_FILIAL>,<F1_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.
- 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 item é finalizado como sucesso.

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

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 (cliente não integrado, cupom ecommerce ou nota fiscal Omni pendente).
- 4: Erro.

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 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` = 'ProtheusDevolucaoCupomFiscalPontual'
    AND `situacao` = 4
ORDER BY
    `data` ASC

Fluxo do Processo

Critérios de Aceitação