ProtheusOrdemProducaoCadastroPi (STATUS: REVISANDO)

Documentação Técnica

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

Descrição

Este serviço integra Ordem de Produção (Cadastro PI) 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 uma ou mais ordens mediante chave no padrão filial-codigopa-operacao 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 ordenação e paginação por DATA_PARA_TRANSFERENCIA para priorizar registros mais antigos e manter continuidade por posição; link conceitual: Cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI_CABECALHO.

Fonte complementar consultada para compor as fases da ordem: view WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI.

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

SELECT
    FILIAL AS filial,
    CODIGOPA AS codigopa,
    QTDEBASE AS qtdbase,
    GGF AS ggf,
    OPERACAO AS operacao,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI_CABECALHO (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
    FILIAL AS filial,
    CODIGOPA AS codigopa,
    QTDEBASE AS qtdbase,
    GGF AS ggf,
    OPERACAO AS operacao,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI_CABECALHO (NOLOCK)
WHERE
    filial = '<FILIAL>'
    AND codigopa = '<CODIGOPA>'
    AND operacao = '<OPERACAO>'

Consulta utilizada para recuperar fases da ordem (WHERE construído dinamicamente por FILIAL, CODIGOPA e OPERACAO):

SELECT
    FILIAL AS filial,
    CODIGOPA AS codigopa,
    QTDEBASE AS qtdbase,
    GGF AS ggf,
    OPERACAO AS operacao,
    FASE_PRODUCAO AS codigo,
    DESC_FASE_PRODUCAO AS descricao,
    CODIGOMOD AS codigomod,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI (NOLOCK)
WHERE
    FILIAL = '<FILIAL>'
    AND CODIGOPA = '<CODIGOPA>'
    AND OPERACAO = '<OPERACAO>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI_CABECALHO para obter o registro atual da ordem (filial, codigopa, qtdbase, ggf, operacao, DATA_PARA_TRANSFERENCIA).

- Chave do registro: define a chave do registro como filial-codigopa-operacao para identificação e rastreio na fila.

- Enriquecimento do registro atual: inclui no conteúdo do registro o campo fases, obtido pela consulta à view WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI, listando para cada fase os campos codigo, descricao e codigomod.

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

- Continuidade e priorização por data: utiliza DATA_PARA_TRANSFERENCIA como referência de posição e consulta ordenada ascendente com paginação por OFFSET/FETCH, mantendo offset e chave_posicao para evitar recaptura.

- Registro para processamento: cada ordem capturada é persistida como pendência na fila de processamento sob o serviço ProtheusOrdemProducaoCadastroPi, com chave filial-codigopa-operacao e conteúdo enriquecido (incluindo fases) 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

{
  "filial": "",
  "codigopa": "",
  "operacao": "",
  "ggf": "",
  "qtdbase": 0,
  "fases": [
    {
      "codigo": "",
      "descricao": "",
      "codigomod": ""
    }
  ]
}

Tratamento de Dados

-Transformações Padronizaçãoaplicadas numéricano (precisãopayload padrãoantes do integrador):
envio:

-

• qtdbase: normalizado via padronização numérica antes do envio ao Protheus.
  
  

Rotinas Inteligentes

Ordem de Produção Cadastro Pi Integrado: após a integração ser interpretada como sucesso, imediatamente antes de finalizar o registro como concluído. Registra o identificador integrado para evitar recaptura/reenvio e manter rastreabilidade.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/ordem-de-producao-cadastro-pi-integrado

Integração com o Protheus

• Chamada de integração com o ProtheusChamada:
  - Chamada: Requisição HTTP
  -
• Recurso: /rest/rtblinx/estrutura
  -
• Método HTTP: POST
  -
• Cabeçalhos:
  -
  • tenantId: <UF>,<FILIAL>, onde <UF> corresponde aos 2 primeiros caracteres de filial e <FILIAL> ao valor completo de filial.

Exemplo de payload enviado (JSON):

{
  "filial": "",
  "codigopa": "",
  "operacao": "",
  "ggf": "",
  "qtdbase": 0,
  "fases": [
    {
      "codigo": "",
      "descricao": "",
      "codigomod": ""
    }
  ]
}

Tratamento de retorno

Ausência de resposta: registra falha com mensagem JSON: NÃO HOUVE RESPOSTA. e finaliza o registro como erro.

Resposta inválida/inesperada: quando o retorno não for um array ou não contiver o campo Mensagem, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..

Consolidação de mensagem: quando existir status, ele é mapeado para Mensagem; quando existir erro, ele é utilizado como Mensagem Detalhada (caso contrário, utiliza a própria Mensagem).

Indicadores de erro: considera erro quando existir o campo code no retorno ou quando Mensagem for ERRO; caso contrário, considera sucesso.

Ao final do processamento, o registro é atualizado na fila de processamento com o retorno do Protheus (quando existir), a mensagem final (incluindo detalhamento quando aplicável), o tempo de processamento e a situação final. Em cenário de sucesso, também registra o identificador integrado com base na chave filial-codigopa-operacao.

Encaminhamento em cenário de erro

Em cenários de falha (ausência de resposta, retorno inválido/inesperado, presença de code ou Mensagem = ERRO), o registro é finalizado como erro e permanece registrado na fila de processamento com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Capturador	Captura por data e controle de posição	Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_CADASTRO_PI_CABECALHO 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 registros pendentes registrados para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma chave no padrão filial-codigopa-operacao, deve consultar a origem filtrando por filial, codigopa e operacao, complementar o conteúdo com fases e registrar o registro correspondente na fila.	registroRegistro pendente registrado para processamento, associado à chave filial-codigopa-operacao, com conteúdo enriquecido.
Fila de Processamento	Estruturação e padronização do payload	Ao processar um registro pendente na fila de processamento (serviço ProtheusOrdemProducaoCadastroPi), deve montar o payload e normalizar qtdbase via padronização numérica antes do envio.	Payload enviado no formato esperado, contendo filial, codigopa, operacao, ggf, qtdbase e fases.
Fila de Processamento	Integração e registro do resultado	Ao integrar com o Protheus (/rest/rtblinx/estrutura, POST), deve tratar ausência de resposta ou retorno inválido como erro, considerar erro quando existir code ou Mensagem = ERRO, e registrar na fila de processamento o retorno, a mensagem e a situação final.	registroRegistro atualizado na fila de processamento com situação coerente (sucesso/erro) e rastreabilidade do retorno e mensagem; em sucesso, identificador integrado registrado para a chave filial-codigopa-operacao.