ProtheusPedidoOmni (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

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

{
  "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

Fluxo do Processo

Critérios de Aceitação