ProtheusNotaFiscalOmni (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_nota_fiscal_omni
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	Criação da documentação técnica do processo ProtheusNotaFiscalOmni.

Descrição

Esta biblioteca organiza o envio de Notas Fiscais Omni do LINX para o Protheus, garantindo captura por chave ou por data, montagem dos itens e registro do resultado da integração.

Capturador

Descrição Conceitual

Permite a captura manual de uma ou mais Notas Fiscais Omni por chave no padrão cfilial-cdoc-cserie-ccliente-cloja, com validação obrigatória do formato; quando a chave estiver fora do padrão, o processo é interrompido com erro de chave inválida para evitar registros inconsistentes.

A captura por data consulta a origem filtrando e ordenando por DATA_PARA_TRANSFERENCIA, com paginação por OFFSET/FETCH, caracterizando processamento cronológico (ordenação/paginação por data); link conceitual: Processamento cronológico. A execução periódica pode ser acionada por agendador de tarefas.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA e view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_ITEM.

Consulta utilizada na captura por data (WHERE e paginação construídos dinamicamente conforme posição e limite configurado):

SELECT
    cfilial,
    cdoc,
    cserie,
    ccliente,
    cloja,
    cest,
    cemissao,
    cespecie,
    ctipo,
    ctpfrete,
    csdoc,
    cchvnfe,
    cdautnfe,
    chautnfe,
    cxnatope,
    cxcanal,
    cpedsite,
    cpedlinx,
    cender,
    cbairro,
    codibge,
    cmun,
    ccep,
    cnome,
    cinscri,
    cemail,
    cddd,
    ctel,
    cpessoa,
    creprocessa,
    cufdest,
    cuforig,
    cespeci1,
    nvolume1,
    npliqui,
    npbruto,
    ctransp,
    nvalmerc,
    nvalbrut,
    nfrete,
    nseguro,
    ndespesa,
    ndescont,
    nvalfat,
    nvalicm,
    nbaseicm,
    nicmfret,
    nvalipi,
    nbaseipi,
    nicmsret,
    nbricms,
    nbasimp6,
    nbasimp5,
    nvalimp6,
    nvalimp5,
    nbasfecp,
    nbsfccmp,
    nbsfcpst,
    nbaseps3,
    nvalps3,
    nbasecf3,
    nvalcf3,
    F2_XCBSIBS,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
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
    cfilial,
    cdoc,
    cserie,
    ccliente,
    cloja,
    cest,
    cemissao,
    cespecie,
    ctipo,
    ctpfrete,
    csdoc,
    cchvnfe,
    cdautnfe,
    chautnfe,
    cxnatope,
    cxcanal,
    cpedsite,
    cpedlinx,
    cender,
    cbairro,
    codibge,
    cmun,
    ccep,
    cnome,
    cinscri,
    cemail,
    cddd,
    ctel,
    cpessoa,
    creprocessa,
    cufdest,
    cuforig,
    cespeci1,
    nvolume1,
    npliqui,
    npbruto,
    ctransp,
    nvalmerc,
    nvalbrut,
    nfrete,
    nseguro,
    ndespesa,
    ndescont,
    nvalfat,
    nvalicm,
    nbaseicm,
    nicmfret,
    nvalipi,
    nbaseipi,
    nicmsret,
    nbricms,
    nbasimp6,
    nbasimp5,
    nvalimp6,
    nvalimp5,
    nbasfecp,
    nbsfccmp,
    nbsfcpst,
    nbaseps3,
    nvalps3,
    nbasecf3,
    nvalcf3,
    F2_XCBSIBS,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA (NOLOCK)
WHERE
    cfilial = '<CFILIAL>'
    AND cdoc = '<CDOC>'
    AND cserie = '<CSERIE>'
    AND ccliente = '<CCLIENTE>'
    AND cloja = '<CLOJA>'

Consulta utilizada para carregar itens da nota (WHERE construído dinamicamente a partir da chave):

SELECT
    cfilial,
    cdoc,
    cserie,
    ccliente,
    cloja,
    citem,
    ccod,
    ctp,
    cum,
    clocal,
    nquant,
    nprcven,
    nprunit,
    ntotal,
    ndescon,
    nseguro,
    nvalfre,
    ndespesa,
    nvalbrut,
    cclasfis,
    ctes,
    ccf,
    nbaseipi,
    nipi,
    nvalipi,
    nbaseicm,
    npicm,
    nvalicm,
    nbasfecp,
    nalqfecp,
    nvalfecp,
    nbricms,
    naliqsol,
    nmargem,
    nicmsret,
    nbsfcpsr,
    nalfcpst,
    nbasimp5,
    nalqimp5,
    nvalimp5,
    nbasimp6,
    nalqimp6,
    nvalimp6,
    nbaseps3,
    naliqps3,
    nvalps3,
    nbasecf3,
    naliqcf3,
    nvalcf3,
    ndesczfp,
    nvfecpst,
    ndesczfc,
    nbasedes,
    naliqcmp,
    nxprmdpr,
    nxaliqba,
    npdori,
    npddes,
    nalqdifal,
    ndifal,
    nbsfccmp,
    nalfccmp,
    cccusto,
    cconta,
    npeso,
    cestoque,
    D2_XCBSBS,
    D2_XCBSAL,
    D2_XCBSVL,
    D2_XIBSBS,
    D2_XIBSAL,
    D2_XIBSVL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_ITEM (NOLOCK)
WHERE
    cfilial = '<CFILIAL>'
    AND cdoc = '<CDOC>'
    AND cserie = '<CSERIE>'
    AND ccliente = '<CCLIENTE>'
    AND cloja = '<CLOJA>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA para obter o registro atual da Nota Fiscal Omni e construir o identificador de processamento no padrão cfilial-cdoc-cserie-ccliente-cloja.

- Carregamento de itens: para cada registro atual da nota, consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA_ITEM e agrega os itens retornados no campo itens, formando o conjunto completo (cabeçalho + itens) para integração.

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

- Registro para processamento: cada Nota Fiscal Omni capturada é persistida como pendência na tabela wosk_queue sob o serviço ProtheusNotaFiscalOmni, com o conteúdo vindo da origem (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

{
  "cfilial": "",
  "cdoc": "",
  "cserie": "",
  "ccliente": "",
  "cloja": "",
  "cest": "",
  "cemissao": "",
  "cespecie": "",
  "ctipo": "",
  "ctpfrete": "",
  "nvalmerc": 0,
  "nvalbrut": 0,
  "nfrete": 0,
  "nseguro": 0,
  "ndespesa": 0,
  "ndescont": 0,
  "nvalfat": 0,
  "nvalicm": 0,
  "nbaseicm": 0,
  "nicmfret": 0,
  "nvalipi": 0,
  "nbaseipi": 0,
  "nicmsret": 0,
  "nbricms": 0,
  "nbasimp6": 0,
  "nbasimp5": 0,
  "nvalimp6": 0,
  "nvalimp5": 0,
  "nbasfecp": 0,
  "nbsfccmp": 0,
  "nbsfcpst": 0,
  "nbaseps3": 0,
  "nvalps3": 0,
  "nbasecf3": 0,
  "nvalcf3": 0,
  "cufdest": "",
  "cuforig": "",
  "cespeci1": "",
  "nvolume1": 0,
  "npliqui": 0,
  "npbruto": 0,
  "ctransp": "",
  "csdoc": "",
  "cchvnfe": "",
  "cdautnfe": "",
  "chautnfe": "",
  "cxnatope": "",
  "cxcanal": "",
  "cpedsite": "",
  "cpedlinx": "",
  "cender": "",
  "cbairro": "",
  "codibge": "",
  "cmun": "",
  "ccep": "",
  "cnome": "",
  "cinscri": "",
  "cemail": "",
  "cddd": "",
  "ctel": "",
  "cpessoa": "",
  "creprocessa": "",
  "F2_XCBSIBS": "",
  "itens": [
    {
      "citem": "",
      "ccod": "",
      "ctp": "",
      "cum": "",
      "clocal": "",
      "nquant": 0,
      "nprcven": 0,
      "nprunit": 0,
      "ntotal": 0,
      "ndescon": 0,
      "nseguro": 0,
      "nvalfre": 0,
      "ndespesa": 0,
      "nvalbrut": 0,
      "cclasfis": "",
      "ctes": "",
      "ccf": "",
      "nbaseipi": 0,
      "nipi": 0,
      "nvalipi": 0,
      "nbaseicm": 0,
      "npicm": 0,
      "nvalicm": 0,
      "nbasfecp": 0,
      "nalqfecp": 0,
      "nvalfecp": 0,
      "nbricms": 0,
      "naliqsol": 0,
      "nmargem": 0,
      "nicmsret": 0,
      "nbsfcpsr": 0,
      "nalfcpst": 0,
      "nvfecpst": 0,
      "nbasimp5": 0,
      "nalqimp5": 0,
      "nvalimp5": 0,
      "nbasimp6": 0,
      "nalqimp6": 0,
      "nvalimp6": 0,
      "nbaseps3": 0,
      "naliqps3": 0,
      "nvalps3": 0,
      "nbasecf3": 0,
      "naliqcf3": 0,
      "nvalcf3": 0,
      "ndesczfp": 0,
      "ndesczfc": 0,
      "nbasedes": 0,
      "naliqcmp": 0,
      "nxprmdpr": 0,
      "nxaliqba": 0,
      "npdori": 0,
      "npddes": 0,
      "nalqdifal": 0,
      "ndifal": 0,
      "nbsfccmp": 0,
      "nalfccmp": 0,
      "cccusto": "",
      "cconta": "",
      "npeso": 0,
      "cestoque": "",
      "D2_XCBSBS": 0,
      "D2_XCBSAL": 0,
      "D2_XCBSVL": 0,
      "D2_XIBSBS": 0,
      "D2_XIBSAL": 0,
      "D2_XIBSVL": 0
    }
  ]
}

Tratamento de Dados

- Pré-validação de dependências: antes de enviar a Nota Fiscal Omni, valida se o cliente (cloja + ccliente) e o pedido (cpedsite) estão integrados. Quando uma dependência não estiver integrada, o item é finalizado como suspenso (situacao = 3) e registra suspensaoTipo e suspensaoChave para rastreio do bloqueio.

- Normalização numérica (cabeçalho): D2_XCBSBS, D2_XCBSAL, D2_XCBSVL, D2_XIBSBS, D2_XIBSAL, D2_XIBSVL, nvolume1, npliqui, npbruto, nvalmerc, nvalbrut, nfrete, nseguro, ndespesa, ndescont, nvalfat, nvalicm, nbaseicm, nicmfret, nvalipi, nbaseipi, nicmsret, nbricms, nbasimp6, nbasimp5, nvalimp6, nvalimp5, nbasfecp, nbsfccmp, nbsfcpst, nbaseps3, nvalps3, nbasecf3, nvalcf3.

- Normalização numérica (itens): nquant, nprcven, nprunit, ntotal, ndescon, nseguro, nvalfre, ndespesa, nvalbrut, nbaseipi, nipi, nvalipi, nbaseicm, npicm, nvalicm, nbasfecp, nalqfecp, nvalfecp, nbricms, naliqsol, nmargem, nicmsret, nbsfcpsr, nalfcpst, nvfecpst, nbasimp5, nalqimp5, nvalimp5, nbasimp6, nalqimp6, nvalimp6, nbaseps3, naliqps3, nvalps3, nbasecf3, naliqcf3, nvalcf3, ndesczfp, ndesczfc, nbasedes, naliqcmp, nxprmdpr, nxaliqba, npdori, npddes, nalqdifal, ndifal, nbsfccmp, nalfccmp, npeso.

- Mapeamento de retorno: quando o Protheus retornar COD e MSG, esses campos são reinterpretados como code e message para padronizar o tratamento do resultado.

- Consolidação de mensagem: quando existir detailedMessage, ele é concatenado à mensagem final para detalhar a causa do sucesso/erro.

- Resalva de duplicidade: quando o retorno indicar erro e a mensagem (ou Log) contiver nota fiscal já cadastrada, o item é reclassificado como sucesso (situacao = 2) e a mensagem é substituída por uma resalva autorizada.

Rotinas Inteligentes

- Cliente Integrado: Evita envio da nota quando o cadastro do cliente ainda não está disponível no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

- Pedido Omni: Garante a consistência do encadeamento entre pedido e nota no Protheus.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/pedido-omni

- Nota Fiscal Omni Integrado: Registra o status de integração para evitar reenvios indevidos.
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: rtbomni/notas
- Método HTTP: POST
- Cabeçalhos:
  - Accept: application/json
  - Content-Type: application/json
  - Connection: close
  - Authorization: Basic <credenciais>

Tratamento de retorno

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

Resposta inválida/inesperada: quando não for possível obter code (direto ou via COD), registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Indicadores de sucesso/erro: considera sucesso quando code for N200. Em retorno diferente, finaliza como erro, exceto quando aplicável a resalva de duplicidade.

Ao final do processamento, o item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem consolidada, a situação final (situacao = 2 em sucesso, situacao = 4 em erro, situacao = 3 quando suspenso por dependência) e o tempo de processamento.

Encaminhamento em cenário de erro

Quando houver falha por ausência de resposta, retorno inválido, code diferente de N200 (sem resalva) ou erro não previsto, o item permanece registrado em wosk_queue com detalhes do retorno e mensagem para acompanhamento e eventual reprocessamento. Quando a falha estiver ligada à integração pendente de cliente ou pedido, o item é suspenso com suspensaoTipo e suspensaoChave para indicar o bloqueio.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura cronológica e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_NOTA com filtro por DATA_PARA_TRANSFERENCIA, ordenação ascendente e paginação por OFFSET/FETCH, deve manter a continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao, filtro).	Posição atualizada em wosk_monitor e itens pendentes registrados para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma chave no padrão cfilial-cdoc-cserie-ccliente-cloja, deve consultar a origem filtrando pelos cinco campos e montar itens a partir da view de itens antes de registrar o item para processamento; quando a chave estiver fora do padrão, deve finalizar com erro de chave inválida.	Item pendente registrado com itens carregados quando a chave for válida; erro quando a chave estiver fora do padrão.
Fila de Processamento	Suspensão por dependência	Quando o cliente (cloja + ccliente) ou o pedido (cpedsite) não estiver integrado, deve finalizar o item como suspenso e registrar suspensaoTipo e suspensaoChave.	Item atualizado em wosk_queue com situacao = 3 e informações de suspensão preenchidas.
Fila de Processamento	Integração com Protheus	Ao processar um item pendente em wosk_queue (serviço ProtheusNotaFiscalOmni), deve enviar requisição POST para o recurso rtbomni/notas com o payload completo (cabeçalho + itens) e registrar retorno, mensagem e situação final.	Item atualizado em wosk_queue com retorno/mensagem e situação final coerente (sucesso quando code = N200 ou quando aplicar a resalva de duplicidade; erro quando não houver resposta, não houver code ou code for diferente sem resalva).