Ir para o conteúdo principal

ProtheusTransferencia (STATUS: REVISANDO)

Documentação Técnica
Nome do cliente OSKLEN
Nome do projeto Integração LINX → Protheus
Biblioteca wosk_protheus_transferencia
Data 27/02/2026


Histórico de Versões
Data Versão Modificado por Descrição da Mudança
27/02/2026 1.0 Maykon Criação da documentação técnica do processo ProtheusTransferencia.

Descrição

Este serviço faz a integração de transferências entre armazéns do LINX para o Protheus, garantindo captura consistente e envio com validação de retorno.

Capturador

Descrição Conceitual

Permite a captura manual (por chave composta) e a captura automática (por agendador de tarefas) das transferências pendentes de integração, consultando a origem e registrando os itens para processamento assíncrono.

A captura automática segue processamento cronológico (ordenação/paginação por data), a partir do campo 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_TRANSFERENCIA.
Consulta utilizada na captura automática (WHERE e paginação construídos dinamicamente conforme posição e configuração de limite):

SELECT
    D3_FILIAL,
    D3_EMISSAO,
    D3_DOC,
    D3_XLOCALORIG,
    D3_XLOCALDEST,
    D3_COD,
    D3_DESCRI,
    D3_QUANT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_TRANSFERENCIA
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 composta e WHERE construído dinamicamente a partir da chave informada):

SELECT
    D3_FILIAL,
    D3_EMISSAO,
    D3_DOC,
    D3_XLOCALORIG,
    D3_XLOCALDEST,
    D3_COD,
    D3_DESCRI,
    D3_QUANT,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_TRANSFERENCIA
WHERE
    D3_FILIAL = '<D3_FILIAL>'
    AND D3_EMISSAO = '<D3_EMISSAO>'
    AND D3_DOC = '<D3_DOC>'
    AND D3_COD = '<D3_COD>'

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_TRANSFERENCIA para obter o registro atual de transferência e encaminhar para processamento assíncrono.

- Chave de identificação do registro: composta no padrão D3_FILIAL-D3_EMISSAO-D3_DOC-D3_COD, utilizada para registrar o registro na fila e para reconstrução de campos no processo de notificação de falhas.

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

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
Campo no payload Origem no registro atual
D3_FILIAL D3_FILIAL
D3_EMISSAO D3_EMISSAO
D3_DOC D3_DOC
D3_XLOCALORIG D3_XLOCALORIG
D3_XLOCALDEST D3_XLOCALDEST
D3_COD D3_COD
D3_DESCRI D3_DESCRI
D3_QUANT D3_QUANT

Tratamento de Dados

Transformações aplicadas no payload antes do envio:

  • D3_QUANT: Padronizado para número com precisão de 3 casas decimais

Integração com o Protheus
  • Chamada: Requisição HTTP
  • Recurso: /rest/transferencia_armazens
  • Método HTTP: POST
  • Cabeçalhos:
    • tenantId: <UF_DA_FILIAL>,<D3_FILIAL> (montado a partir dos 2 primeiros caracteres de D3_FILIAL + vírgula + o valor completo de D3_FILIAL)

Exemplo de payload enviado:

enviado
(JSON):

{
  "D3_FILIAL": "",
  "D3_EMISSAO": "",
  "D3_DOC": "",
  "D3_XLOCALORIG": "",
  "D3_XLOCALDEST": "",
  "D3_COD": "",
  "D3_DESCRI": "",
  "D3_QUANT": ""
}



Tratamento de Dados

Antes do envio, o campo D3_QUANT é padronizado para número com precisão de 3 casas decimais, garantindo consistência de formato para integração.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: /rest/transferencia_armazens
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: <UF_DA_FILIAL>,<D3_FILIAL> (montado a partir dos 2 primeiros caracteres de D3_FILIAL + vírgula + o valor completo de D3_FILIAL)

Tratamento de retorno

Ausência de resposta: registra erro com mensagem de “não houve resposta” e finaliza o registro como falha.

Resposta inválida/inesperada: se o retorno não puder ser interpretado como estrutura contendo Mensagem, registra erro de decodificação e finaliza como falha.

Indicadores de erro: finaliza como falha quando houver code no retorno ou quando Mensagem for ERRO. Quando disponível, utiliza Mensagem Detalhada como mensagem final.

Sucesso: quando não houver indicadores de erro, finaliza como sucesso e persiste o retorno para auditoria.

Ao final do processamento, o registro é atualizado na fila de processamento com o retorno do Protheus (quando existir), a mensagem consolidada e a situação final (sucesso/erro). O tempo de processamento é registrado para acompanhamento operacional.

 
Encaminhamento em cenário de erro

Quando ocorre erro na integração (ausência de resposta, resposta inválida ou retorno com indicador de falha), o registro é finalizado como erro e permanece registrado em fila de processamento com detalhes de mensagem e retorno, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação
A notificação de erros consulta itens com falha na fila de processamento (serviço ProtheusTransferencia e situação de erro), ordenando pela data de processamento para priorizar ocorrências mais antigas. Para compor a listagem, a chave do registro é decomposta para preencher os campos D3_FILIAL, D3_EMISSAO, D3_DOC e D3_COD, e as datas data_adicionado e data são formatadas para apresentação.

Fluxo do Processo

Diagrama sem nome.jpg


Critérios de Aceitação
Processo Subprocesso Descrição Situação esperada
Capturador Captura cronológica e controle de posição Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_TRANSFERENCIA com ordenação por DATA_PARA_TRANSFERENCIA e paginação, deve manter a continuidade por posição persistida em wosk_monitor (evento, offset, chave_posicao, data_posicao). Posição atualizada na tabela wosk_monitor e itens pendentes registrados para processamento assíncrono.
Capturador Captura manual por chave composta Ao informar uma chave no padrão D3_FILIAL-D3_EMISSAO-D3_DOC-D3_COD, deve consultar a view com filtros exatos desses campos e registrar o registro correspondente para processamento. registroRegistro pendente registrado para processamento, associado à chave composta e apto a integração.
Fila de Processamento Integração com Protheus Ao processar um registro pendente em fila de processamento (serviço ProtheusTransferencia), deve montar payload conforme $field,estrutura definida, padronizar D3_QUANT com precisão de 3 casas decimais e realizar a requisição ao recurso /rest/transferencia_armazens. registroRegistro atualizado em fila de processamento com retorno/mensagem e situação final coerente (sucesso quando não houver erro; erro quando houver ausência de resposta, resposta inválida, code ou Mensagem = ERRO).
Voltar ao topo