Ir para o conteúdo principal

ProtheusProduto (STATUS: REVISANDO)

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


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

Descrição

Este serviço organiza a integração de produtos 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 B1_COD) e a captura automática (por agendador de tarefas) dos produtos pendentes de integração, consultando a origem e registrando os registros para processamento assíncrono. Na captura manual (consulta manual), é necessário informar a chave: no formato B1_COD (código do produto), em que cada uma identifica unicamente um produto na origem.

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_PRODUTO (projeção fixa).

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

SELECT
    B1_COD,
    B1_DESC,
    B1_TIPO,
    B1_UM,
    B1_LOCPAD,
    B1_GRUPO,
    B1_CONTA,
    B1_CONTRAT,
    ASB1_CEST,
    B1_IPI,
    B1_POSIPI,
    B1_PICMRET,
    B1_PICMENT,
    B1_ORIGEM,
    B1_GRTRIB,
    B1_FECP,
    B1_CCCUSTO,
    B1_PESBRU,
    B1_PESO,
    B1_XPRV1,
    B1_MSBLQL,
    DATA_PARA_TRANSFERENCIA
FROM
    WOSK_SERVICO_ENVIA_PROTHEUS_PRODUTO
WHERE
    DATA_PARA_TRANSFERENCIA >= '<DATA_PARA_TRANSFERENCIA>'
ORDER BY
    DATA_PARA_TRANSFERENCIA ASC
OFFSET
    <OFFSET> ROWS FETCH NEXT <LIMITE> ROWS ONLY

Operações com Dados

- Leitura: consulta a view WOSK_SERVICO_ENVIA_PROTHEUS_PRODUTO para obter o registro atual de produto (com chave B1_COD) e encaminhar para processamento assíncrono.
-

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

O registro da fila é persistido e atualizado na fila de processamento ao longo do processamento, registrando chave, conteúdo, retorno, mensagem, tempo e situação final (sucesso/erro) para auditoria.

Estruturação de Dados

A estrutura oficial do payload de integração é definida pelo array $field da fila. Cada registro representa um campo enviado ao Protheus; quando houver mapeamento, o payload usa o nome do campo do Protheus e o valor é obtido de um campo alternativo do registro atual.

Campo no payload Origem no registro atual
B1_COD B1_COD
B1_DESC B1_DESC
B1_TIPO B1_TIPO
B1_UM B1_UM
B1_LOCPAD B1_LOCPAD
B1_GRUPO B1_GRUPO
B1_CONTA B1_CONTA
B1_CONTRAT B1_CONTRAT
B1_CEST ASB1_CEST
B1_IPI B1_IPI
B1_POSIPI B1_POSIPI
B1_PICMRET B1_PICMRET
B1_PICMENT B1_PICMENT
B1_ORIGEM B1_ORIGEM
B1_GRTRIB B1_GRTRIB
B1_FECP B1_FECP
B1_CCCUSTO B1_CCCUSTO
B1_PESBRU B1_PESBRU
B1_PESO B1_PESO
B1_XPRV1 B1_XPRV1
B1_MSBLQL B1_MSBLQL


Tratamento de Dados

Antes do envio, os seguintes campos numéricos do payload são padronizados por rotina de normalização numérica: B1_IPI, B1_PICMRET, B1_PICMENT, B1_FECP, B1_PESBRU, B1_PESO, B1_XPRV1. O objetivo é garantir consistência de formato (ex.: separador decimal e representação) conforme exigência do Protheus.

Integração com o Protheus
  • Chamada: Requisição HTTP
  • Recurso: /rest/produto
  • Método HTTP: POST
  • Cabeçalhos:
    • tenantId: 01,01SD0001

Exemplo de payload enviado:

enviado
(JSON):

{
  "B1_COD": "",
  "B1_DESC": "",
  "B1_TIPO": "",
  "B1_UM": "",
  "B1_LOCPAD": "",
  "B1_GRUPO": "",
  "B1_CONTA": "",
  "B1_CONTRAT": "",
  "B1_CEST": "",
  "B1_IPI": "",
  "B1_POSIPI": "",
  "B1_PICMRET": "",
  "B1_PICMENT": "",
  "B1_ORIGEM": "",
  "B1_GRTRIB": "",
  "B1_FECP": "",
  "B1_CCCUSTO": "",
  "B1_PESBRU": "",
  "B1_PESO": "",
  "B1_XPRV1": "",
  "B1_MSBLQL": ""
}
 


Tratamento de Dados

Antes do envio, os seguintes campos numéricos do payload são padronizados por rotina de normalização numérica: B1_IPI, B1_PICMRET, B1_PICMENT, B1_FECP, B1_PESBRU, B1_PESO, B1_XPRV1. O objetivo é garantir consistência de formato (ex.: separador decimal e representação) conforme exigência do Protheus.

Integração com o Protheus

Chamada de integração com o Protheus
- Chamada: Requisição HTTP
- Recurso: /rest/produto
- Método HTTP: POST
- Cabeçalhos:
  - tenantId: 01,01SD0001

Tratamento de retorno

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 na fila de processamento com detalhes de mensagem e retorno, permitindo acompanhamento e reprocessamento conforme necessidade operacional.

Notificação
AExiste um mecanismo de notificação deque errosidentifica consultaos registrositens com falhaerro na tabela fila de processamento (serviço ProtheusProduto e situação de erro),processamento, ordenando pelapor data de processamento para priorizar ocorrências mais antigas. A mensagem de erro é normalizada para leitura, e oenviando tipoem doum produto (B1_TIPO) é apresentado de forma descritiva (ex.: MP, PA e demais). Por fim,relatório a notificação encaminha a lista para os destinatários configurados.pré-definidos.

Fluxo do Processo

Diagrama sem nome.jpg


Critérios de Aceitação
Processo Subprocesso Descrição Situação esperada
Capturador Captura e registro para processamento Ao consultar a view WOSK_SERVICO_ENVIA_PROTHEUS_PRODUTO com paginação e ordenação por DATA_PARA_TRANSFERENCIA, 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 registros pendentes registrados para processamento assíncrono.
Fila de Processamento Estruturação e envio ao Protheus Ao processar um registro pendentena fila de processamento (serviço ProtheusProduto), deve montar payload conforme $field, aplicar padronização numérica em B1_IPI, B1_PICMRET, B1_PICMENT, B1_FECP, B1_PESBRU, B1_PESO, B1_XPRV1 e realizar a requisição ao recurso produto. registroRegistro atualizado na 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).
Fila de ProcessamentoNotificação de falhasAo identificar registros com falha na fila de processamento (serviço ProtheusProduto, situação de erro), deve ordenar pelas ocorrências mais antigas e normalizar a mensagem de erro para leitura, mantendo B1_TIPO em formato descritivo para contexto.Destinatários recebem a notificação com os registros de falha priorizados e mensagem legível, permitindo tratativa operacional.
Voltar ao topo