ProtheusNotaFiscalMarketplacePontual (STATUS: VERIFICADO)

Documentação Técnica

Histórico de Versões

Descrição

Este serviço organiza o envio pontual de notas fiscais de marketplace do LINX para o Protheus, garantindo captura por chave ou por período.

Capturador

Descrição Conceitual

Permite a captura manual (por chave composta) e a captura automática (por agendador de tarefas) de notas fiscais pendentes, consultando a origem e registrando cada item para processamento assíncrono.

A captura automática segue processamento cronológico (ordenação/paginação por data) para priorizar registros mais antigos e manter continuidade por posição; link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL.

Origem auxiliar de itens: view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL.

Consulta utilizada na captura automática (janela diária calculada a partir de DATA_PARA_TRANSFERENCIA e paginação conforme OFFSET e limite configurado):

SELECT
    TIPO,
    E1_XFILORI,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA BETWEEN '<DATA_INICIO_DIA>' AND '<DATA_FIM_DIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Consulta utilizada na captura manual (chave informada e WHERE construído dinamicamente):

SELECT
    TIPO,
    E1_XFILORI,
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_PEDIDO,
    F2_TIPO,
    F2_FORMUL,
    F2_EMISSAO,
    F2_CLIENTE,
    F2_LOJA,
    F2_ESPECIE,
    F2_COND,
    F2_XNATOPE,
    F2_CHVNFE,
    F2_HAUTNFE,
    F2_DAUTNFE,
    F2_PROTOCOLO,
    F2_FRETE,
    F2_SEGURO,
    F2_DESPESA,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

Consulta utilizada para recuperar itens da nota fiscal (itens vinculados à chave principal):

SELECT
    F2_FILIAL,
    F2_DOC,
    F2_SERIE,
    F2_CLIENTE,
    F2_LOJA,
    D2_CCUSTO,
    D2_LOCAL,
    D2_ITEM,
    D2_COD,
    D2_QUANT,
    D2_PRCVEN,
    D2_TOTAL,
    D2_TES,
    D2_BASEICM,
    D2_PICM,
    D2_VALICM,
    D2_DESCON,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL (NOLOCK)
WHERE
    F2_FILIAL = '<F2_FILIAL>'
    AND F2_DOC = '<F2_DOC>'
    AND F2_SERIE = '<F2_SERIE>'
    AND F2_CLIENTE = '<F2_CLIENTE>'
    AND F2_LOJA = '<F2_LOJA>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_PONTUAL para obter o registro atual da nota fiscal e montar a chave composta F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.

- Leitura auxiliar de itens: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_NOTA_OMNIMKTPLACE_ITEM_PONTUAL para obter os itens relacionados à chave, que serão anexados ao conteúdo do item da fila.

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

- Registro para processamento: cada nota fiscal capturada é persistida como pendência na tabela wosk_queue sob o serviço ProtheusNotaFiscalMarketplacePontual, com chave composta e conteúdo (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.

Estruturação de Dados

{
  "TIPO": "",
  "e1_xfilori": "",
  "f2_filial": "",
  "f2_doc": "",
  "f2_serie": "",
  "f2_pedido": "",
  "f2_tipo": "",
  "f2_formul": "",
  "f2_emissao": "",
  "f2_cliente": "",
  "f2_loja": "",
  "f2_especie": "",
  "f2_chvnfe": "",
  "f2_hautnfe": "",
  "f2_dautnfe": "",
  "f2_protocolo": "",
  "f2_cond": "",
  "f2_frete": "",
  "f2_seguro": "",
  "f2_despesa": "",
  "f2_xnatope": "",
  "itens": [
    {
      "d2_item": "",
      "d2_cod": "",
      "d2_quant": "",
      "d2_prcven": "",
      "d2_total": "",
      "d2_tes": "",
      "d2_baseicm": "",
      "d2_picm": "",
      "d2_valicm": "",
      "D2_DESCON": ""
    }
  ]
}

Tratamento de Dados

- Validação prévia obrigatória: antes do envio da nota fiscal, valida se o cliente da nota está integrado consultando a rotina inteligente setProtheusClienteIntegrado com a chave F2_LOJA-F2_CLIENTE. Se não estiver integrado, o item é finalizado como suspenso (situacao = 3) com suspensao_tipo e suspensao_chave preenchidos para tratamento posterior.

- Padronização numérica (precisão padrão):
  - f2_frete, f2_seguro, f2_despesa: normalizados com setNumeric(...).
  - itens[].d2_quant, itens[].d2_prcven, itens[].d2_total, itens[].d2_baseicm, itens[].d2_picm, itens[].d2_valicm, itens[].D2_DESCON: normalizados com setNumeric(...).

Rotinas Inteligentes

- Cliente Integrado: validada antes de iniciar o envio da nota fiscal (condição obrigatória por cliente). Garante que a integração da nota fiscal só prossiga quando o cliente estiver pronto para o Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

- Nota Fiscal Omni Integrado: executada após retorno de sucesso do Protheus para a nota fiscal. Marca a nota fiscal como integrada usando a chave F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA para evitar reprocessamento.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/nota-fiscal-omni-integrado

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: linx/nota_fiscal
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <prefixo_2_caracteres_de_F2_FILIAL>,<F2_FILIAL>
 

Tratamento de retorno

Ausência de resposta: registra erro com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o item como falha.

Resposta inválida/inesperada: quando não houver code no retorno, registra erro com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera erro quando code for maior que 299; caso contrário, considera sucesso.

Regra de idempotência: quando a mensagem contiver numero de nota fiscal ja gravado, o retorno é reinterpretado como sucesso (força code = 0 e Mensagem = OK).

Sucesso: quando a situação for sucesso, marca a nota fiscal como integrada pela rotina inteligente Nota Fiscal Omni Integrado usando a chave F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA.

Quando a prévalidação de cliente não for atendida, o item é finalizado como suspenso (situacao = 3) e a fila registra suspensao_tipo = 'ProtheusCliente' e suspensao_chave = 'F2_LOJA-F2_CLIENTE' para direcionar o tratamento.

Encaminhamento em cenário de erro

Em cenários de falha (ausência de resposta, retorno inválido ou code > 299), o item permanece registrado em wosk_queue com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional. Em cenários de dependência (cliente não integrado), o item é marcado como suspenso (situacao = 3) para impedir processamento indevido até que a condição seja resolvida.

Notificação

Fluxo do Processo

Critérios de Aceitação