ProtheusOrdemProducao (STATUS: PARCIAL)

Documentação Técnica

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

Descrição

Esta biblioteca organiza o envio de Ordens 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 uma ou mais ordens mediante chave no padrão filial-codigopa-operacao-numop 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.

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

SELECT
    filial,
    operacao,
    numop,
    codigopa,
    qtdebase AS quant,
    emissao,
    inicio,
    fim,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OP (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,
    operacao,
    numop,
    codigopa,
    qtdebase AS quant,
    emissao,
    inicio,
    fim,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OP (NOLOCK)
WHERE
    filial = '<FILIAL>'
    AND codigopa = '<CODIGOPA>'
    AND operacao = '<OPERACAO>'
    AND numop = '<NUMOP>'

 

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OP para obter o registro atual da ordem (filial, operacao, numop, codigopa, quant, emissao, inicio, fim, DATA_PARA_TRANSFERENCIA).

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

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusOrdemProducao, 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.

- Persistência de posição/continuidade: registra e atualiza o controle do capturador na tabela wosk_monitor (banco {$this->bancoIntegrador}) usando evento = 'ProtheusOrdemProducao', 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 ordem capturada é persistida como pendência na tabela wosk_queue (banco {$this->bancoIntegrador}) sob o serviço ProtheusOrdemProducao, com chave filial-codigopa-operacao-numop e conteúdo do registro atual 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 é 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

{
  "filial": "",
  "operacao": "",
  "numop": "",
  "codigopa": "",
  "quant": 0,
  "emissao": "",
  "inicio": "",
  "fim": ""
}

Tratamento de Dados

- Validação prévia de dependência (Cadastro PI): antes do envio da ordem, valida se o Cadastro PI (filial-codigopa-operacao) está integrado. 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):
  - quant: normalizado via padronização numérica antes do envio.

- Sucesso por condição específica de erro: quando o retorno indicar erro e a mensagem contiver op já cadastrada, o resultado é reinterpretado como sucesso para concluir o item sem falha operacional.

Rotinas Inteligentes
Ordem de Produção Cadastro Pi Integrado: antes do envio ao Protheus, após carregar o item da fila. Garante que o Cadastro PI (filial-codigopa-operacao) esteja integrado para permitir a criação da ordem.
link: https://kb.illimitar.pro/books/integracao-linx-protheus/page/ordem-de-producao-cadastro-pi-integrado

Ordem de Produção Integrado: após a integração ser interpretada como sucesso, imediatamente antes de finalizar o item 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-integrado

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtblinx/ordemprod
- 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:
  - Cabeçalho da ordem: filial, operacao, numop, codigopa, quant, emissao, inicio, fim.
  - Exemplo em JSON:

{
  "filial": "01",
  "operacao": "001",
  "numop": "OP123",
  "codigopa": "ABC123",
  "quant": 1,
  "emissao": "2026-03-02",
  "inicio": "2026-03-02 10:00:00",
  "fim": "2026-03-02 18:00:00"
}

- 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, exceto quando a mensagem contiver op já cadastrada (tratado como sucesso).

 

Tratamento de retorno

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 do Cadastro PI). 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 fora da condição tratada como sucesso), 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 do Cadastro PI, 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 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, deve consultar a origem filtrando pelos identificadores e registrar o item correspondente na fila.	Item pendente registrado para processamento, associado à chave da ordem.
Fila de Processamento	Validação de dependência e suspensão	Antes de integrar a ordem, deve validar a existência de integração do Cadastro PI (filial-codigopa-operacao). 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 conclusão com regra de sucesso	Ao integrar com o Protheus (rtblinx/ordemprod, POST), deve tratar ausência de resposta ou retorno inválido como erro, considerar erro quando existir code ou Mensagem = ERRO, e concluir como sucesso quando a mensagem contiver op já cadastrada, registrando em wosk_queue o retorno, a mensagem e a situação final.	Item atualizado em wosk_queue com situação coerente (sucesso/erro/suspenso), retorno e mensagem rastreáveis; em sucesso, integração registrada para a chave filial-codigopa-operacao-numop.