ProtheusPedidoMarketplace (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca organiza a integração de pedidos de marketplace do LINX para o Protheus, garantindo captura por chave ou por data 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 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_PEDIDO_OMNIMKTPLACE.

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

Consulta utilizada na captura por data (WHERE 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 (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
    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 (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 (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,
    autori,
    tid
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_FORMA (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 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.
  - c5_xforma a partir da view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE_FORMA.

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

- Controle de continuidade: utiliza DATA_PARA_TRANSFERENCIA como referência de posição (formato Y-m-d H:i:s) e mantém offset e chave_posicao para evitar recaptura, iniciando a janela temporal com 2023-05-01 00:00:00 quando não houver posição anterior.

- Persistência de posição/continuidade: registra e atualiza o controle do capturador na tabela wosk_monitor (banco {$this->bancoIntegrador}) usando evento = 'ProtheusPedidoMarketplace', mantendo token, offset, filtro, chave_posicao, situacao, data_posicao, data_iniciado e data.

- Situações registradas no controle: parado/início (0), em processamento (1), concluído (2) e problema (4). Em caso de falha, o campo filtro recebe um histórico em ERRORS[] com DATE e MESSAGE para auditoria.

- Registro para processamento: cada pedido capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusPedidoMarketplace, 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.

O item de fila é persistido e atualizado na tabela wosk_queue (banco {$this->bancoIntegrador}) ao longo do processamento, registrando chave, conteudo, retorno, mensagem, tempo, situacao e, quando aplicável, dados de suspensão para auditoria.

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": "",
      "autori": "",
      "tid": ""
    }
  ],
  "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: antes do envio do pedido, ao validar o cliente (c5_lojacli-c5_cliente). 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.
- Exemplo de payload enviado:
  - Cabeçalho do pedido: e1_xfilori, c5_filial, c5_cliente, c5_lojacli, c5_condpag, c5_frete, c5_naturez, c5_xidlinx, c5_xtplinx e, quando aplicável, c5_vend1.
  - Formas de pagamento: lista c5_xforma com data, forma, valor, nsu, autori, tid.
  - Itens: lista itens com c6_item, c6_produto, c6_qtdven, c6_prcven, c6_valor, c6_tes, c6_qtdlib e c6_valdesc (quando existir).
- 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.

Tratamento de retorno

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 cronológica e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_PEDIDO_OMNIMKTPLACE 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 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 ProtheusPedidoMarketplace), 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.