ProtheusNotaFiscalOmni (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

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