ProtheusOrdemProducaoCadastroPi (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza o envio de dados de 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: Processamento por data (ordenação/paginação).

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 item: define a chave do item como filial-codigopa-operacao para identificação e rastreio na fila.

- Enriquecimento do registro atual: inclui no conteúdo do item 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 itens 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.

- Persistência de posição/continuidade: registra e atualiza o controle do capturador na tabela wosk_monitor (banco {$this->bancoIntegrador}) usando evento = 'ProtheusOrdemProducaoCadastroPi', 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 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.

O item é persistido e atualizado na tabela wosk_queue (banco {$this->bancoIntegrador}) ao longo do processamento, registrando chave, conteudo, retorno, mensagem, tempo e situacao para auditoria e rastreabilidade.

Estruturação de Dados

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

Tratamento de Dados

- Padronização numérica (precisão padrão do integrador):
  - 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 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-cadastro-pi-integrado

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: 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:
  - Cabeçalho da ordem: filial, codigopa, operacao, ggf, qtdbase.
  - Fases: lista fases com codigo, descricao, codigomod.
  - Exemplo em JSON:

{

"filial":

"01",
  "codigopa": "ABC123",
  "operacao": "001",
  "ggf": "0",
  "qtdbase": 1,
  "fases": [
    {
      "codigo": "10",
      "descricao": "FASE EXEMPLO",
      "codigomod": "MOD01"
    }
  ]
}

-

Tratamento de retorno:
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.

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). 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 item é finalizado como erro e permanece registrado em wosk_queue com detalhes do retorno e mensagem, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação

Fluxo do Processo

Critérios de Aceitação