ProtheusPedidoOmniElresiduo (STATUS: ESTRANHO)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza o envio de exclusão/ajuste de resíduo de itens de Pedido Omni do LINX para o Protheus, garantindo captura consistente e integração com validação de retorno.

Capturador

Descrição Conceitual

Realiza a captura automática (por agendador de tarefas) dos pedidos Omni pendentes, consultando a origem por janela temporal e registrando os itens para processamento assíncrono.

A captura automática 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_OMNI_EXCLUSAO.

Consulta utilizada na captura automática (WHERE e paginação construídos dinamicamente conforme posição e configuração de limite):

SELECT
    cpedsite,
    cproduto,
    citem,
    nquant,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO (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
    cpedsite,
    cproduto,
    citem,
    nquant,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO (NOLOCK)
WHERE
    cpedsite = '<CPEDSITE>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_OMNI_EXCLUSAO para obter o registro atual de pedido (cpedsite, cproduto, citem, nquant, DATA_PARA_TRANSFERENCIA) e encaminhar para processamento assíncrono.

- Controle de limite de captura: obtém o limite de itens por ciclo via configuração woskLimiteCaptura::ProtheusPedidoOmniElresiduo, 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 (banco {$this->bancoIntegrador}) usando evento = 'ProtheusPedidoOmniElresiduo', mantendo os campos 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.

- Regra de continuidade por data: o filtro DATA_PARA_TRANSFERENCIA é inicializado (quando ausente) com 2023-05-01 00:00:00 e, para cada registro capturado, a posição passa a refletir a data do próximo ponto de continuidade (data_posicao e filtro['DATA_PARA_TRANSFERENCIA'] no formato Y-m-d H:i:s).

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 de fila é persistido e atualizado na tabela wosk_queue (banco {$this->bancoIntegrador}) ao longo do processamento, registrando chave, conteúdo, retorno, mensagem, tempo e situação final (sucesso/erro) para auditoria.

Estruturação de Dados

{
  "cfilial": "",
  "cpedsite": "",
  "cproduto": "",
  "nquant": "",
  "citem": ""
}

Tratamento de Dados

O conteúdo do item de fila é normalizado para garantir disponibilidade consistente dos campos definidos em $field. Para integração, os campos cpedsite, cproduto, citem e nquant são utilizados na composição dos parâmetros enviados ao Protheus, enquanto cfilial permanece como parte do payload oficial do item para padrão de estrutura.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: rtbomni/elresiduo com parâmetros na URL
- Método HTTP: não informado explicitamente na chamada (utiliza o padrão da biblioteca)
- Cabeçalhos: nenhum cabeçalho explícito informado na chamada
- Exemplo de envio:
  - Não há corpo de requisição (payload vazio). Os valores são enviados como parâmetros de URL, montados a partir do conteúdo do item: cpedsite, cproduto, citem, nquant.
  - Exemplo de recurso com parâmetros:
    rtbomni/elresiduo?cpedsite=<CPEDSITE>&cproduto=<CPRODUTO>&citem=<CITEM>&nquant=<NQUANT>
- 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 for possível obter um código de retorno, registra falha com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..
  - Mapeamento de campos de retorno: quando presentes, COD é reinterpretado como code e MSG como message para padronização de leitura do retorno.
  - Indicadores de sucesso/erro: considera sucesso quando code for R200 ou X200; demais valores finalizam como erro.
  - Consolidação de mensagem: a mensagem final é composta por message e, quando existir, complementada por detailedMessage.

Tratamento de retorno

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. O tempo de processamento é registrado e a situação é definida como sucesso (2) ou erro (4) conforme o código retornado.

Encaminhamento em cenário de erro

Quando ocorre erro na integração (ausência de resposta, resposta inválida ou código diferente de R200/X200), o item é finalizado como erro e permanece registrado em wosk_queue com detalhes do retorno e da mensagem para acompanhamento operacional. Quando houver aplicação de suspensão (quando identificada no fluxo), a situação pode ser marcada como suspenso (3).

Notificação

Fluxo do Processo

Critérios de Aceitação