ProtheusDevolucaoCupomFiscalPontual (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_devolucao_cupom_fiscal_pontual
Data	03/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
03/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo ProtheusDevolucaoCupomFiscalPontual.

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)

Campo no payload	Campo de origem
`F1_FILIAL`	`F1_FILIAL`
`F1_DOC`	`F1_DOC`
`F1_SERIE`	`LQ_SERIE`
`F1_FORNECE`	`F1_FORNECE`
`F1_LOJA`	`F1_LOJA`
`F1_COND`	`F1_COND`
`F1_XNATUR`	`F1_XNATUR`
`F1_DUPL`	`F1_DUPL`
`F1_EMISSAO`	`F1_EMISSAO`
`F1_DTDIGIT`	`F1_DTDIGIT`
`F1_RECBMTO`	`F1_RECBMTO`
`F1_EST`	`F1_EST`
`F1_ESTPRES`	`F1_ESTPRES`
`F1_TIPO`	`F1_TIPO`
`F1_FORMUL`	`F1_FORMUL`
`F1_ESPECIE`	`F1_ESPECIE`
`F1_VALMERC`	`F1_VALMERC`
`F1_VALBRUT`	`F1_VALBRUT`
`F1_FRETE`	`F1_FRETE`
`F1_DESPESA`	`F1_DESPESA`
`F1_SEGURO`	`F1_SEGURO`
`F1_DESCONT`	`F1_DESCONTO`
`F1_BASEICM`	`F1_BASEICM`
`F1_VALICM`	`F1_VALICM`
`F1_BASEIPI`	`F1_BASEIPI`
`F1_VALIPI`	`F1_VALIPI`
`F1_BRICMS`	`F1_BRICMS`
`F1_ICMSRET`	`F1_ICMSRET`
`F1_BASIMP5`	`F1_BASIMP5`
`F1_VALIMP5`	`F1_VALIMP5`
`F1_BASIMP6`	`F1_BASIMP6`
`F1_VALIMP6`	`F1_VALIMP6`
`BASEPS3`	`BASEPS3`
`VALPS3`	`VALPS3`
`BASECF3`	`BASECF3`
`VALCF3`	`VALCF3`
`F1_MUORITR`	`F1_MUORITR`
`F1_UFORITR`	`F1_UFORITR`
`F1_MUDESTR`	`F1_MUDESTR`
`F1_UFDESTR`	`F1_UFDESTR`
`F1_II`	`F1_II`
`F1CIF`	`F1CIF`
`F1_TIPO_NF`	`F1_TIPO_NF`
`F1_CHVNFE`	`F1_CHVNFE`
`F1_DAUTNFE`	`F1_DAUTNFE`
`F1_HAUTNFE`	`F1_HAUTNFE`
`F1_PROTOC`	`F1_PROTOC`
`F1_NFELETR`	`F1_NFELETR`
`F1_EMINFE`	`F1_EMINFE`
`F1_HORNFE`	`F1_HORNFE`
`F1_TPFRETE`	`F1_TPFRETE`
`F1_TPCTE`	`F1_TPCTE`
`P1_PLIQUI`	`P1_PLIQUI`
`P1_PBRUTO`	`P1_PBRUTO`
`P1_ESPECI1`	`P1_ESPECI1`
`P1_VOLUME1`	`P1_VOLUME1`
`F1_ORIGLAN`	`F1_ORIGLAN`
`F1_NFORIG`	`F1_NFORIG`
`F1_SERORIG`	`F1_SERORIG`
`F1_NUMTRIB`	`F1_NUMTRIB`
`F1_MOEDA`	`F1_MOEDA`
`F1_PREFIXO`	`F1_PREFIXO`
`F1_STATUS`	`F1_STATUS`
`F1_SDOC`	`F1_SDOC`
`F1_TRANSP`	`F1_TRANSP`
`F1_XNATOPE`	`F1_XNATOPE`
`F1_XCANAL`	`F1_XCANAL`
`F3_DTCANC`	`F3_DTCANC`
`F3_CODRSEF`	`F3_CODRSEF`
`F1_XCBSIBS`	`F1_XCBSIBS`

ITENS_DEV

Campo no payload	Campo de origem
`D1_FILIAL`	`D1_FILIAL`
`D1_ITEM`	`D1_ITEM`
`D1_COD`	`D1_COD`
`D1_TP`	`B1_TP`
`D1_UM`	`B1_UM`
`D1_LOCAL`	`B1_LOCAL`
`D1_GRUPO`	`B1_GRUPO`
`D1_TEC`	`D1_TEC`
`D1_QUANT`	`D1_QUANT`
`D1_VUNIT`	`D1_VUNIT`
`D1_TOTAL`	`D1_TOTAL`
`D1_DESC`	`D1_DESC`
`D1_VALDESC`	`D1_VALDESC`
`D1_SEGURO`	`D1_SEGURO`
`D1_VALFRE`	`D1_VALFRE`
`D1_DESPESA`	`D1_DESPESA`
`D1_EMISSAO`	`D1_EMISSAO`
`D1_DTDIGIT`	`D1_DTDIGIT`
`D1_DOC`	`D1_DOC`
`D1_SERIE`	`D1_SERIE`
`D1_SDOC`	`F1_SDOC`
`D1_TIPO`	`D1_TIPO`
`D1_FORNECE`	`D1_FORNECE`
`D1_LOJA`	`D1_LOJA`
`D1_CLASFIS`	`D1_CLASFIS`
`D1_OPER`	`D1_OPER`
`D1_CF`	`D1_CF`
`D1_BASEIPI`	`D1_BASEIPI`
`D1_IPI`	`D1_IPI`
`D1_VALIPI`	`D1_VALIPI`
`D1_BASEICM`	`D1_BASEICM`
`D1_PICM`	`D1_PICM`
`D1_VALICM`	`D1_VALICM`
`D1_VRDICMS`	`D1_VRDICMS`
`D1_VALANTI`	`D1_VALANTI`
`D1_ICMSDIF`	`D1_ICMSDIF`
`D1_BASFECP`	`D1_BASFECP`
`D1_ALQFECP`	`D1_ALQFECP`
`D1_VALFECP`	`D1_VALFECP`
`D1_ALIQCMP`	`D1_ALIQCMP`
`D1_DIFAL`	`D1_DIFAL`
`D1_BSFCCMP`	`D1_BSFCCMP`
`D1_ALFCCMP`	`D1_ALFCCMP`
`D1_VFCPDIF`	`D1_VFCPDIF`
`D1_AFCPANT`	`D1_AFCPANT`
`D1_VFCPANT`	`D1_VFCPANT`
`D1_BRICMS`	`D1_BRICMS`
`D1_ALIQSOL`	`D1_ALIQSOL`
`D1_MARGEM`	`D1_MARGEM`
`D1_ICMSRET`	`D1_ICMSRET`
`D1_BSFCPST`	`D1_BSFCPST`
`D1_ALFCPST`	`D1_ALFCPST`
`D1_VFECPST`	`D1_VFECPST`
`D1_BASIMP5`	`D1_BASIMP5`
`D1_ALQIMP5`	`D1_ALQIMP5`
`D1_VALIMP5`	`D1_VALIMP5`
`D1_BASIMP6`	`D1_BASIMP6`
`D1_ALQIMP6`	`D1_ALQIMP6`
`D1_VALIMP6`	`D1_VALIMP6`
`D1_ALIQII`	`D1_ALIQII`
`D1_II`	`D1_II`
`D1_CIF`	`D1_CIF`
`D1_TIPO_NF`	`D1_TIPO_NF`
`D1_OP`	`D1_OP`
`D1_CC`	`D1_CC`
`D1_CONTA`	`D1_CONTA`
`D1_PESO`	`D1_PESO`
`D1_DATORI`	`D1_DATORI`
`D1_NFORI`	`D1_NFORI`
`D1_SERIORI`	`D1_SERIORI`
`D1_ITEMORI`	`D1_ITEMORI`
`D1_ORIGLAN`	`D1_ORIGLAN`
`DKD_XCBSBS`	`DKD_XCBSBS`
`DKD_XCBSAL`	`DKD_XCBSAL`
`DKD_XCBSVL`	`DKD_XCBSVL`
`DKD_XIBSBS`	`DKD_XIBSBS`
`DKD_XIBSAL`	`DKD_XIBSAL`
`DKD_XIBSVL`	`DKD_XIBSVL`

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

A notificação de erros consulta itens com falha na tabela wosk_queue para o serviço ProtheusDevolucaoCupomFiscalPontual, ordena por data e prepara a mensagem para envio, extraindo apenas a parte relevante de erros de SQL Server quando aplicável e higienizando a mensagem de erro.

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

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por dia e encaminhamento	Ao consultar a view `WOSK_SERVICO_ENVIA_PROTHEUS_CUPOM_DEVOLUCAO_CABECALHO_PONTUAL`, deve capturar documentos do dia (`DATA_PARA_TRANSFERENCIA BETWEEN` 00:00:00 e 23:59:59), ordenar por `DATA_PARA_TRANSFERENCIA ASC`, paginar e encaminhar cada documento para processamento em fila. Ao concluir o dia, agendar o próximo dia.	Documentos capturados são disponibilizados para processamento e auditáveis em `wosk_queue`.
Fila de Processamento	Validação de dependência	Antes de integrar a devolução de cupom fiscal, deve validar a integração prévia do cliente (`F1_FORNECE`/`F1_LOJA`); e, quando houver itens com documento de origem, deve validar cupons de troca (Cupom Ecommerce Integrado) ou documentos Omni (Nota Fiscal Omni Integrado) conforme classificação por fornecedor e data.	Processamento suspenso (`situacao = 3`) quando houver dependência não atendida, com mensagem registrada.
Fila de Processamento	Normalização numérica	Ao preparar o payload, deve normalizar campos numéricos do cabeçalho e itens, aplicando precisão diferenciada para `D1_QUANT` (3 casas, `false`) e `D1_VUNIT` (5 casas, `false`).	Payload consistente e pronto para envio, com valores padronizados conforme regra.
Fila de Processamento	Integração e persistência do retorno	Após enviar ao Protheus (`POST` no recurso `cupom` com header `tenantId`), deve validar a resposta, tratar “já cadastrado” como sucesso e registrar em `wosk_queue` o retorno, mensagem e situação final.	Fila atualizada com situação final e detalhes de auditoria.