ProtheusOrdemProducaoApontamento (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca organiza o envio de apontamentos de Ordem de Produção 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 apontamentos mediante chave no padrão filial-codigopa-operacao-numop-idservico (com idservico opcional) 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) usando DATA_PARA_TRANSFERENCIA para priorizar registros mais antigos e manter continuidade por posição; link conceitual: Processamento cronológico.

Fonte

Origem consultada: view WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO_CABECALHO.

Fonte complementar consultada para compor os materiais do apontamento: view WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO.

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

SELECT
    FILIAL AS filial,
    OPERACAO AS operacao,
    NUMOP AS numop,
    CODIGOPA AS codigopa,
    FASE AS fase,
    QTDPROD AS qtdprod,
    QTDPERDA AS qtdperda,
    ENCERRA AS encerra,
    [DATA] AS [data],
    IDSERVICO,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO_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, com IDSERVICO opcional):

SELECT
    FILIAL AS filial,
    OPERACAO AS operacao,
    NUMOP AS numop,
    CODIGOPA AS codigopa,
    FASE AS fase,
    QTDPROD AS qtdprod,
    QTDPERDA AS qtdperda,
    ENCERRA AS encerra,
    [DATA] AS [data],
    IDSERVICO,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO_CABECALHO (NOLOCK)
WHERE
    FILIAL = '<FILIAL>'
    AND CODIGOPA = '<CODIGOPA>'
    AND OPERACAO = '<OPERACAO>'
    AND NUMOP = '<NUMOP>'
    AND IDSERVICO = '<IDSERVICO>'

Consulta utilizada para recuperar materiais do apontamento (WHERE construído dinamicamente por FILIAL, CODIGOPA, OPERACAO, NUMOP e IDSERVICO):

SELECT
    FILIAL AS filial,
    OPERACAO AS operacao,
    NUMOP AS numop,
    CODIGOPA AS codigopa,
    FASE AS fase,
    QTDPROD AS qtdprod,
    QTDPERDA AS qtdperda,
    ENCERRA AS encerra,
    [DATA] AS [data],
    MATERIAL AS material,
    QUANTIDADE AS quantidade,
    [LOCAL] AS [local],
    IDSERVICO
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO (NOLOCK)
WHERE
    FILIAL = '<FILIAL>'
    AND CODIGOPA = '<CODIGOPA>'
    AND OPERACAO = '<OPERACAO>'
    AND NUMOP = '<NUMOP>'
    AND IDSERVICO = '<IDSERVICO>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO_CABECALHO para obter o registro atual do apontamento (filial, operacao, numop, codigopa, fase, qtdprod, qtdperda, encerra, data, IDSERVICO, DATA_PARA_TRANSFERENCIA).

- Chave do item: define a chave do item como filial-codigopa-operacao-numop-idservico para identificação e rastreio na fila; quando IDSERVICO não estiver presente na chave informada, o filtro manual omite esse campo e utiliza o IDSERVICO retornado pela origem.

- Enriquecimento do registro atual: inclui no conteúdo do item o campo materiais, obtido pela consulta à view WOSK_SERVICO_ENVIA_PROTHEUS_OP_APONTAMENTO, listando para cada material os campos material, quantidade e local.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusOrdemProducaoApontamento, 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 apontamento capturado é persistido como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusOrdemProducaoApontamento, com chave filial-codigopa-operacao-numop-idservico e conteúdo enriquecido (incluindo materiais) 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": "",
  "operacao": "",
  "numop": "",
  "codigopa": "",
  "fase": "",
  "qtdprod": 0,
  "qtdperda": 0,
  "encerra": "",
  "data": "",
  "materiais": [
    {
      "material": "",
      "quantidade": 0,
      "local": ""
    }
  ]
}

Tratamento de Dados

- Validação prévia da Ordem de Produção: antes do envio do apontamento, valida se a ordem (filial-codigopa-operacao-numop) está integrada. Quando a validação falha, o item é finalizado como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave preenchidos para rastreio.

- Padronização numérica (precisão padrão do integrador):
  - qtdprod, qtdperda: normalizados via padronização numérica antes do envio.
  - materiais[].quantidade: normalizado via padronização numérica para cada material quando a lista existir.

Rotinas Inteligentes

Ordem de Produção Integrado: Garante que a ordem (filial-codigopa-operacao-numop) esteja integrada para permitir o apontamento.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/ordem-de-producao-integrado

 

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtblinx/apontamento
- 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.

- Tratamento de retorno:

 

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 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 item é atualizado na tabela wosk_queue com o retorno do Protheus (quando existir), a mensagem final (incluindo detalhamento quando aplicável), o tempo de processamento e a situação final (situacao = 2 em sucesso, situacao = 4 em erro, situacao = 3 quando suspenso por dependência de integração da ordem). Os dados de suspensão (suspensaoTipo e suspensaoChave) são mantidos para rastreio quando aplicável.

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 item é finalizado como erro e permanece registrado em wosk_queue com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional. Em cenários de dependência de integração da ordem, o item é finalizado como suspenso (situacao = 3).

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_OP_APONTAMENTO_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 itens pendentes registrados para processamento assíncrono.
Capturador	Captura manual por chave	Ao informar uma chave no padrão filial-codigopa-operacao-numop-idservico (com idservico opcional), deve consultar a origem filtrando pelos identificadores, complementar o conteúdo com materiais e registrar o item correspondente na fila.	Item pendente registrado para processamento, associado à chave do apontamento, com conteúdo enriquecido.
Fila de Processamento	Validação de dependência e suspensão	Antes de integrar o apontamento, deve validar a existência de integração da ordem (filial-codigopa-operacao-numop). Quando a validação falhar, deve registrar o item como suspenso (situacao = 3) com suspensaoTipo e suspensaoChave.	Item permanece rastreável em wosk_queue como suspenso, sem tentativa de envio, até que a dependência seja resolvida.
Fila de Processamento	Integração e registro do resultado	Ao integrar com o Protheus (rtblinx/apontamento, POST), deve tratar ausência de resposta ou retorno inválido como erro, considerar erro quando existir code ou Mensagem = ERRO, 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.