ProtheusNotaFiscalMarketplacePontual (STATUS: VERIFICADO)

DocumentaçãDocumentação TéTécnica

HistóHistórico de VersõVersões

DescriçãDescrição

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

Capturador

DescriçãDescrição Conceitual

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

Na captura manual, éé necessánecessário informar uma chave no formato F2_FILIAL-F2_DOC-F2_SERIE-F2_CLIENTE-F2_LOJA, em que cada parte identifica unicamente uma nota fiscal na origem.
A captura automáautomática segue processamento cronolócronológico (ordenaçãordenação/paginaçãpaginação por data) para priorizar registros mais antigos e manter continuidade por posiçãposição; link conceitual: Processamento cronoló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áautomática (janela diádiária calculada a partir de DATA_PARA_TRANSFERENCIA e paginaçã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í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çõ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ãserão anexados ao conteúconteúdo do item da fila.

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

- Registro para processamento: cada nota fiscal capturada éé persistida como pendêpendência na tabela wosk_queue  sob o serviçserviço ProtheusNotaFiscalMarketplacePontual, com chave composta e conteúconteúdo (incluindo itens) para processamento assíassíncrono.

Fila de Processamento

DescriçãDescrição Conceitual

A fila recupera um registro pendente e utiliza o conteúconteúdo do registro como base do payload de integraçãintegração. Em seguida, aplica transformaçõtransformações obrigatóobrigatórias de padronizaçãpadronização e realiza a chamada ao Protheus.

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

- PadronizaçãPadronização numénumérica (precisãprecisão padrã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çãcondição obrigatóobrigatória por cliente). Garante que a integraçãintegração da nota fiscal só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ó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çãIntegração com o Protheus

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

Tratamento de retorno

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

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

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

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

Sucesso: quando a situaçã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çãprévalidação de cliente nã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ácenário de erro

Em cenácenários de falha (ausêausência de resposta, retorno invá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ácenários de dependêdependência (cliente nãnão integrado), o item éé marcado como suspenso (situacao = 3) para impedir processamento indevido atéaté que a condiçãcondição seja resolvida.

NotificaçãNotificação

Fluxo do Processo

CritéCritérios de AceitaçãAceitação