ProtheusInventario (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca organiza o envio de movimentações de inventário do LINX para o Protheus, garantindo que cada registro seja coletado, preparado e encaminhado com controle de situação.
O processo mantém rastreabilidade pelo uso de chave composta e registra o resultado do envio (sucesso ou erro) para acompanhamento operacional.

Capturador

Descrição Conceitual

O capturador recupera registros na origem WOSK_SERVICO_ENVIA_PROTHEUS_INVENTARIO e, para cada registro encontrado, monta uma chave de rastreio a partir de D3_FILIAL, D3_EMISSAO, D3_TM, D3_LOCAL, D3_DOC e D3_COD, no padrão D3_FILIAL-D3_EMISSAO-D3_TM-D3_LOCAL-D3_DOC-D3_COD, para encaminhamento à fila de processamento.

A captura pode ocorrer automaticamente (via agendador de tarefas) com filtro por data e paginação, caracterizando processamento por ordem temporal (ordenação/paginação por data). Também permite captura manual informando a chave completa; nesse caso, o filtro é construído dinamicamente pelas seis partes e, se a quantidade de partes for menor que 6, o processo é interrompido com erro de chave inválida, evitando enfileiramento incorreto.

Fonte

Origem consultada: WOSK_SERVICO_ENVIA_PROTHEUS_INVENTARIO.

Operações com Dados

Leitura: consulta os registros na origem e aplica filtro por DATA_PARA_TRANSFERENCIA, com ordenação ascendente por data e paginação por OFFSET/FETCH NEXT conforme limite configurado (woskLimiteCaptura::ProtheusInventario).
Persistência: cada registro preparado é armazenado para processamento na tabela wosk_queue (integrador), identificado pela chave D3_FILIAL-D3_EMISSAO-D3_TM-D3_LOCAL-D3_DOC-D3_COD.

Query base (origem):

SELECT
    D3_FILIAL,
    D3_EMISSAO,
    D3_TM,
    D3_COD,
    D3_DESCRI,
    D3_TIPO,
    D3_UM,
    D3_GRUPO,
    D3_QUANT,
    D3_CF,
    D3_LOCAL,
    D3_DOC,
    DATA_PARA_TRANSFERENCIA
FROM 
    WOSK_SERVICO_ENVIA_PROTHEUS_INVENTARIO

Query executada na captura automática (montada a partir da base):

SELECT
    D3_FILIAL,
    D3_EMISSAO,
    D3_TM,
    D3_COD,
    D3_DESCRI,
    D3_TIPO,
    D3_UM,
    D3_GRUPO,
    D3_QUANT,
    D3_CF,
    D3_LOCAL,
    D3_DOC,
    DATA_PARA_TRANSFERENCIA
FROM 
    WOSK_SERVICO_ENVIA_PROTHEUS_INVENTARIO
WHERE
    DATA_PARA_TRANSFERENCIA >= '{$filtro['DATA_PARA_TRANSFERENCIA']}'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    {$offset} ROWS
FETCH NEXT
    {$top} ROWS ONLY

Query executada na captura manual (filtro dinâmico pela chave):

SELECT
    D3_FILIAL,
    D3_EMISSAO,
    D3_TM,
    D3_COD,
    D3_DESCRI,
    D3_TIPO,
    D3_UM,
    D3_GRUPO,
    D3_QUANT,
    D3_CF,
    D3_LOCAL,
    D3_DOC,
    DATA_PARA_TRANSFERENCIA
FROM 
    WOSK_SERVICO_ENVIA_PROTHEUS_INVENTARIO
WHERE
    D3_FILIAL = '{$chave[0]}'
    AND D3_EMISSAO = '{$chave[1]}'
    AND D3_TM = '{$chave[2]}'
    AND D3_LOCAL = '{$chave[3]}'
    AND D3_DOC = '{$chave[4]}'
    AND D3_COD = '{$chave[5]}'

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 processamento prepara o payload conforme a lista oficial de campos e registra o resultado (situação, mensagem e retorno) na tabela wosk_queue para auditoria e notificação.

Estruturação de Dados

{
  "D3_FILIAL": "",
  "D3_EMISSAO": "",
  "D3_TM": "",
  "D3_COD": "",
  "D3_DESCRI": "",
  "D3_TIPO": "",
  "D3_UM": "",
  "D3_GRUPO": "",
  "D3_QUANT": 0,
  "D3_CF": "",
  "D3_LOCAL": "",
  "D3_DOC": ""
}

Tratamento de Dados

Antes do envio ao Protheus, o campo abaixo é normalizado com precisão numérica explícita:

- D3_QUANT: normalizado com 3 casas decimais (setNumeric(..., 3, false)).

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: inventario
- Método HTTP: POST
- Base URL: https://terrasde187162.protheus.cloudtotvs.com.br:4050/rest/
- Cabeçalhos:
  - tenantId: composto por substr(D3_FILIAL, 0, 2) . "," . D3_FILIAL.

Tratamento de retorno
- Ausência de resposta: o item é finalizado como erro com mensagem JSON: NÃO HOUVE RESPOSTA..
- Resposta inválida/inesperada: se não for um array ou não contiver Mensagem, o item é finalizado como erro com mensagem JSON: NÃO FOI POSSÍVEL DECODIFICAR A RESPOSTA..
- Definição de situação: por padrão, sucesso quando não houver code e Mensagem não for ERRO; erro quando houver code ou Mensagem for ERRO.

Persistência do resultado: ao final, a fila grava em wosk_queue a situação e a mensagem do processamento, junto do retorno recebido.

Tratamento de retorno

Sucesso: quando o retorno do Protheus não indicar erro (Mensagem diferente de ERRO e sem campo code), a fila registra a situação de sucesso e persiste o retorno para auditoria.
Erro: quando houver ausência de resposta, resposta não decodificável, ou indicador de erro (code presente ou Mensagem = ERRO), a fila grava o retorno de erro e mensagem para auditoria e notificação.

Encaminhamento em cenário de erro

Quando houver erro no envio ou validação do retorno, o item permanece registrado como erro na tabela wosk_queue, com a mensagem e o retorno, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação

Fluxo do Processo

Critérios de Aceitação