ProtheusPedidoMarketplace (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

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>).

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

- Registro para processamento: cada pedido capturado é persistido como pendência na tabela wosk_queue 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.

Estruturação de Dados

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