ProtheusPedidoMarketplacePontual (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_pedido_marketplace_pontual
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 ProtheusPedidoMarketplacePontual.

Descrição

Esta biblioteca organiza a integração pontual de pedidos de marketplace do LINX para o Protheus, garantindo captura por chave ou por janela diária e registro do resultado do envio.

Capturador

Descrição Conceitual

Permite a captura manual de um ou mais pedidos por chave no padrão c5_filial-c5_xidlinx e a captura por agendador de tarefas com base em janela diária, 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_PEDIDO_OMNIMKTPLACE_PONTUAL.

Fontes complementares consultadas para compor o pedido completo:
- view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_ITEM_PONTUAL (itens).
- view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_FORMA_PONTUAL (formas de pagamento).

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

SELECT
    TIPO,
    e1_xfilori,
    c5_filial,
    c5_cliente,
    c5_lojacli,
    c5_condpag,
    c5_naturez,
    c5_xidlinx,
    c5_xtplinx,
    C5_frete,
    c5_vend1,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_PONTUAL (NOLOCK)
WHERE
    DATA_PARA_TRANSFERENCIA BETWEEN '<DATA_INICIO>' AND '<DATA_FIM>'
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
    TIPO,
    e1_xfilori,
    c5_filial,
    c5_cliente,
    c5_lojacli,
    c5_condpag,
    c5_naturez,
    c5_xidlinx,
    c5_xtplinx,
    C5_frete,
    c5_vend1,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_PONTUAL (NOLOCK)
WHERE
    c5_filial = '<C5_FILIAL>'
    AND c5_xidlinx = '<C5_XIDLINX>'

Consulta utilizada para recuperar itens do pedido (WHERE construído dinamicamente por c5_filial e c5_xidlinx):

SELECT
    c5_filial,
    c5_cliente,
    c5_lojacli,
    c5_xidlinx,
    c5_xtplinx,
    c6_item,
    c6_produto,
    c6_qtdven,
    c6_prcven,
    c6_valor,
    c6_tes,
    c6_qtdlib,
    C6_VALDESC,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_ITEM_PONTUAL (NOLOCK)
WHERE
    c5_filial = '<C5_FILIAL>'
    AND c5_xidlinx = '<C5_XIDLINX>'

Consulta utilizada para recuperar formas de pagamento do pedido (WHERE construído dinamicamente por c5_filial e c5_xidlinx):

SELECT
    c5_filial,
    c5_cliente,
    c5_lojacli,
    c5_xidlinx,
    [DATA] AS [data],
    FORMA AS forma,
    VALOR_TOTAL AS valor,
    DATA_PARA_TRANSFERENCIA,
    NSU,
    E1_XNSU,
    E1_XAUTORI,
    E1_XTID,
    E1_XPEDIDO
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_FORMA_PONTUAL (NOLOCK)
WHERE
    c5_filial = '<C5_FILIAL>'
    AND c5_xidlinx = '<C5_XIDLINX>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_PONTUAL para obter o registro atual do pedido (TIPO, e1_xfilori, c5_filial, c5_cliente, c5_lojacli, c5_condpag, c5_naturez, c5_xidlinx, c5_xtplinx, C5_frete, c5_vend1, DATA_PARA_TRANSFERENCIA).

- Chave do item: define a chave do item como c5_filial-c5_xidlinx para identificação e rastreio na fila.

- Enriquecimento do registro atual: para cada chave capturada, complementa o conteúdo com:
  - itens a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_ITEM_PONTUAL.
  - c5_xforma a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_FORMA_PONTUAL.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusPedidoMarketplacePontual, 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 ProtheusPedidoMarketplacePontual, com chave c5_filial-c5_xidlinx e conteúdo completo (incluindo itens e c5_xforma) 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

{
  "TIPO": "",
  "e1_xfilori": "",
  "c5_filial": "",
  "c5_cliente": "",
  "c5_lojacli": "",
  "c5_condpag": "",
  "C5_frete": 0,
  "c5_naturez": "",
  "c5_xidlinx": "",
  "c5_xtplinx": "",
  "C5_vend1": "",
  "c5_xforma": [
    {
      "data": "",
      "forma": "",
      "valor": 0,
      "nsu": "",
      "E1_XNSU": "",
      "E1_XAUTORI": "",
      "E1_XTID": "",
      "E1_XPEDIDO": ""
    }
  ],
  "itens": [
    {
      "c6_item": "",
      "c6_produto": "",
      "c6_qtdven": 0,
      "c6_prcven": 0,
      "c6_valor": 0,
      "c6_tes": "",
      "c6_qtdlib": 0,
      "C6_VALDESC": 0
    }
  ]
}

Tratamento de Dados

- Validação prévia de integração do cliente: antes de enviar o pedido, valida se o cliente (c5_lojacli-c5_cliente) 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):
  - c5_frete: normalizado via padronização numérica.
  - c5_xforma[].valor: normalizado via padronização numérica.
  - itens[].c6_qtdven, itens[].c6_prcven, itens[].c6_valor, itens[].c6_qtdlib: normalizados via padronização numérica.
  - itens[].C6_VALDESC: normalizado via padronização numérica quando existir no item.

- Padronização de data em forma de pagamento: c5_xforma[].data é convertida para o formato d/m/Y antes do envio.

- Ajuste condicional de campos: quando TIPO for OMNI, remove o campo c5_vend1 do payload. Em seguida, remove o campo TIPO do payload em todos os cenários.

- Persistência de de/para do pedido (quando aplicável): ao receber no retorno do Protheus o identificador id, verifica existência e, se necessário, insere na tabela OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE o relacionamento PEDIDO_LINX (valor de c5_xidlinx) e PEDIDO_PROTHEUS (valor de id), 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

 

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: linx/pedido_venda
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF>,<C5_FILIAL>, onde <UF> corresponde aos 2 primeiros caracteres de c5_filial e <C5_FILIAL> ao valor completo de c5_filial.

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

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 ja integrado, o retorno é reinterpretado como sucesso (define Mensagem = OK e ajusta code para 0).

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

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 maior que 299), 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

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por janela diária e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_PONTUAL usando DATA_PARA_TRANSFERENCIA por janela do dia (BETWEEN), 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 c5_filial-c5_xidlinx, deve consultar a origem filtrando por c5_filial e c5_xidlinx, complementar itens e c5_xforma e registrar o item correspondente na fila.	Item pendente registrado para processamento, associado à chave c5_filial-c5_xidlinx, com conteúdo completo do pedido.
Fila de Processamento	Padronização de payload e cabeçalho	Ao processar um item pendente em wosk_queue (serviço ProtheusPedidoMarketplacePontual), deve normalizar campos numéricos (c5_frete, c5_xforma[].valor, itens[].c6_qtdven, itens[].c6_prcven, itens[].c6_valor, itens[].c6_qtdlib, itens[].C6_VALDESC quando existir), formatar c5_xforma[].data para d/m/Y, remover c5_vend1 quando TIPO = OMNI e remover TIPO antes do envio, e montar o cabeçalho tenantId conforme c5_filial.	Payload enviado no formato esperado e integração executada com cabeçalho tenantId consistente.
Fila de Processamento	Integração e registro do resultado	Ao integrar com o Protheus (linx/pedido_venda, POST), deve tratar ausência de resposta/ausência de code como erro, consolidar message com detailedMessage, tratar ja integrado como sucesso e registrar em wosk_queue o retorno, a mensagem e a situação final.	Item 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 id, deve registrar (quando inexistente) o relacionamento em OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE com PEDIDO_LINX = c5_xidlinx e PEDIDO_PROTHEUS = id.	Tabela OSK_DEPARA_PROTHEUS_PEDIDO_OMNI_MARKETPLACE contendo o de/para para auditoria e rastreio de integração.