ProtheusPedidoOmni (STATUS: PARCIAL)

Documentação Técnica

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

Histórico de Versões

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

Descrição

Esta biblioteca integra pedidos Omni do LINX para o Protheus, garantindo captura por chave ou por data e registro do resultado da integração.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais pedidos pelo identificador cpedsite e a captura por agendador de tarefas com base em janela temporal, consultando a origem e registrando cada item para processamento assíncrono.

A captura por data 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_OMNI.

Fontes complementares consultadas para compor o pedido completo:
- view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_ITEM (itens).
- view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_PGTO (títulos).

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

SELECT
    cfilial,
    cpedsite,
    cpedlinx,
    cemissao,
    nvlfrete,
    ccod,
    cloja,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI (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,
    cpedsite,
    cpedlinx,
    cemissao,
    nvlfrete,
    ccod,
    cloja,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'

Consulta utilizada para recuperar itens do pedido (WHERE construído dinamicamente por cpedsite):

SELECT
    ccodprod,
    citem,
    nquant,
    nvalorunit,
    nvalortotal,
    ndesconto,
    nvalorliq,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_ITEM (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'

Consulta utilizada para recuperar títulos do pedido (WHERE construído dinamicamente por cpedsite):

SELECT
    cprefix,
    nqtparcelas,
    nvalor,
    chist,
    cnsu,
    ciderp,
    cautorizacao,
    ctid,
    ccodadmin,
    ccusto,
    cbanco,
    cagencia,
    cconta,
    ctipopgto,
    cnatureza,
    cpedsite,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_PGTO (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI para obter o registro atual do pedido (cfilial, cpedsite, cpedlinx, cemissao, nvlfrete, ccod, cloja, DATA_PARA_TRANSFERENCIA) e definir a chave do item como cpedsite.

- Enriquecimento do registro atual: para cada cpedsite capturado, complementa o conteúdo com:
- itens a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_ITEM.
- titulos a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_PGTO.

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

- Registro para processamento: cada pedido capturado é persistido como pendência na tabela wosk_queue sob o serviço ProtheusPedidoOmni, com chave cpedsite e conteúdo completo (incluindo itens e titulos) 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

Campo no payload	Origem no item de fila (conteúdo)
`cfilial`	`cfilial`
`cpedsite`	`cpedsite`
`cpedlinx`	`cpedlinx`
`cemissao`	`cemissao`
`nvlfrete`	`nvlfrete`
`cliente.ccod`	`ccod` (do item da fila) e/ou `cliente.ccod` após normalização interna
`cliente.cloja`	`cloja` (do item da fila) e/ou `cliente.cloja` após normalização interna
`cliente.cpessoa`	`cliente.cpessoa`
`cliente.cinscri`	`cliente.cinscri`
`cliente.cnome`	`cliente.cnome`
`cliente.cender`	`cliente.cender`
`cliente.cest`	`cliente.cest`
`cliente.cmun`	`cliente.cmun`
`cliente.cbairro`	`cliente.cbairro`
`cliente.ccodibge`	`cliente.ccodibge`
`cliente.ccep`	`cliente.ccep`
`cliente.cemail`	`cliente.cemail`
`cliente.cddd`	`cliente.cddd`
`cliente.ctel`	`cliente.ctel`
`itens[].ccodprod`	`itens[].ccodprod`
`itens[].citem`	`itens[].citem`
`itens[].nquant`	`itens[].nquant`
`itens[].nvalorunit`	`itens[].nvalorunit`
`itens[].nvalortotal`	`itens[].nvalortotal`
`itens[].ndesconto`	`itens[].ndesconto` (recalculado)
`itens[].nvalorliq`	`itens[].nvalorliq` (pode ser ajustado para consistência)
`titulos[].cprefix`	`titulos[].cprefix`
`titulos[].nqtparcelas`	`titulos[].nqtparcelas`
`titulos[].nvalor`	`titulos[].nvalor`
`titulos[].chist`	`titulos[].chist`
`titulos[].cnsu`	`titulos[].cnsu`
`titulos[].ciderp`	`titulos[].ciderp`
`titulos[].cautorizacao`	`titulos[].cautorizacao`
`titulos[].ctid`	`titulos[].ctid`
`titulos[].ccodadmin`	`titulos[].ccodadmin`
`titulos[].ccusto`	`titulos[].ccusto`
`titulos[].cbanco`	`titulos[].cbanco`
`titulos[].cagencia`	`titulos[].cagencia`
`titulos[].cconta`	`titulos[].cconta`
`titulos[].ctipopgto`	`titulos[].ctipopgto`
`titulos[].cnatureza`	`titulos[].cnatureza`

Exemplo de payload (com todos os campos previstos em $field):

{
  "cfilial": "",
  "cpedsite": "",
  "cpedlinx": "",
  "cemissao": "",
  "nvlfrete": 0,
  "cliente": [
    {
      "ccod": "",
      "cloja": "",
      "cpessoa": "",
      "cinscri": "",
      "cnome": "",
      "cender": "",
      "cest": "",
      "cmun": "",
      "cbairro": "",
      "ccodibge": "",
      "ccep": "",
      "cemail": "",
      "cddd": "",
      "ctel": ""
    }
  ],
  "itens": [
    {
      "ccodprod": "",
      "citem": "",
      "nquant": 0,
      "nvalorunit": 0,
      "nvalortotal": 0,
      "ndesconto": 0,
      "nvalorliq": 0
    }
  ],
  "titulos": [
    {
      "cprefix": "",
      "nqtparcelas": 0,
      "nvalor": 0,
      "chist": "",
      "cnsu": "",
      "ciderp": "",
      "cautorizacao": "",
      "ctid": "",
      "ccodadmin": "",
      "ccusto": "",
      "cbanco": "",
      "cagencia": "",
      "cconta": "",
      "ctipopgto": "",
      "cnatureza": ""
    }
  ]
}

Tratamento de Dados

- Reestruturação do bloco de cliente: o conteúdo do item é preparado com cliente contendo um único elemento, preenchendo cliente[0].ccod e cliente[0].cloja a partir de ccod e cloja do pedido, e inicializando os demais campos (cliente[0].cpessoa, cliente[0].cinscri, cliente[0].cnome, cliente[0].cender, cliente[0].cest, cliente[0].cmun, cliente[0].cbairro, cliente[0].ccodibge, cliente[0].ccep, cliente[0].cemail, cliente[0].cddd, cliente[0].ctel) com "". Após a normalização interna do conteúdo, o envio utiliza cliente como objeto (primeiro elemento do array).

- Validação prévia de integração do cliente: antes de integrar o pedido, valida se o cliente (cloja-ccod) está integrado. Quando a validação falha, o item é concluído como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave preenchidos para rastreio.

- Padronização numérica (precisão padrão do integrador):
  - nvlfrete: normalizado via padronização numérica.
  - itens[].nquant, itens[].nvalorunit, itens[].nvalortotal, itens[].nvalorliq: normalizados via padronização numérica.
  - itens[].ndesconto: recalculado como itens[].nvalortotal - itens[].nvalorliq e normalizado via padronização numérica.
  - titulos[].nqtparcelas, titulos[].nvalor: normalizados via padronização numérica.

- Consistência de totais: soma titulos[].nvalor em totalTitulos e soma itens[].nvalorliq em totalItens; se nvlfrete > 0, adiciona nvlfrete em totalItens.

- Ajuste fino de divergência: quando totalTitulos difere de totalItens e a diferença (diff) estiver entre -0.3 e 0.3, ajusta o último item que possui ndesconto diferente de zero, aplicando:
  - itens[<IDX>].nvalorliq = itens[<IDX>].nvalorliq + diff
  - itens[<IDX>].ndesconto = itens[<IDX>].ndesconto - diff
Ambos os campos são novamente normalizados via padronização numérica.

- Persistência de de/para do pedido (quando aplicável): ao receber no retorno do Protheus o identificador Pedido, verifica existência e, se necessário, insere na tabela OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE o relacionamento PEDIDO_LINX (valor de cpedsite) e PEDIDO_PROTHEUS (valor de Pedido), registrando DATA_PARA_TRANSFERENCIA com GETDATE().

Rotinas Inteligentes

- Cliente Integrado: Garante que o cliente esteja integrado para permitir o vínculo do pedido.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/cliente-integrado

- Pedido Omni: após a integração do pedido ser concluída com sucesso. Registra o pedido como integrado para evitar reenvio no fluxo.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/pedido-omni

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtbomni/vendas
- Método HTTP: não informado explicitamente na chamada (utiliza o padrão do integrador)
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada

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/errorCode), registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Padronização de campos: quando o retorno vier em COD ou errorCode, mapeia para code; quando vier em MSG ou errorMessage, mapeia para message.

Indicadores de sucesso/erro: considera sucesso quando code for S200; demais valores finalizam como erro.

Consolidação de mensagem: a mensagem final é composta por message e, quando existir, complementada por detailedMessage.

Exceção de sucesso por mensagem: quando a mensagem contiver existem itens cadastrados com este id, considera sucesso mesmo que o retorno não esteja no código esperado.

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

Encaminhamento em cenário de erro

Em cenários de falha (ausência de resposta, retorno inválido ou code diferente de S200), o item permanece registrado em wosk_queue com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional. Quando houver dependência de integração do cliente, o item é registrado como suspenso (situacao = 3) até que a pendência seja resolvida.

Notificação

A notificação de erros consulta itens com falha na tabela wosk_queue (serviço ProtheusPedidoOmni e situação de erro), ordenando pela data de processamento para priorizar ocorrências mais antigas.

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` 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 pedido	Ao informar um `cpedsite`, deve consultar a origem filtrando por `cpedsite`, complementar `itens` e `titulos` e registrar o item correspondente na fila.	Item pendente registrado para processamento, associado à chave `cpedsite`, com conteúdo completo do pedido.
Fila de Processamento	Consistência financeira do pedido	Ao processar um item pendente em `wosk_queue` (serviço `ProtheusPedidoOmni`), deve normalizar campos numéricos, recalcular `itens[].ndesconto` e, quando a diferença entre totais estiver entre `-0.3` e `0.3`, ajustar `itens[].nvalorliq` e `itens[].ndesconto` no último item com desconto.	Payload enviado com totais coerentes e item de fila atualizado com retorno e situação final.
Fila de Processamento	Integração e registro do resultado	Ao integrar com o Protheus (`rtbomni/vendas`), deve padronizar retorno para `code`/`message`, considerar sucesso apenas quando `code` = `S200` (ou por exceção de mensagem) e registrar em `wosk_queue` o retorno, a mensagem consolidada, o tempo e a situação final.	Item de fila atualizado em `wosk_queue` com situação coerente (sucesso/erro/suspenso) e rastreabilidade do retorno e mensagem.
Fila de Processamento	Registro de de/para do pedido	Quando o retorno do Protheus contiver `Pedido`, deve registrar (quando inexistente) o relacionamento em `OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE` com `PEDIDO_LINX` = `cpedsite` e `PEDIDO_PROTHEUS` = `Pedido`.	Tabela `OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE` contendo o de/para para auditoria e rastreio de integração.