ProtheusCustoMedio (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_custo_medio
Data	02/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
02/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo ProtheusCustoMedio.

Descrição

Este endpoint registra custos médios recebidos para produtos ou materiais, garantindo validação de existência e persistência controlada dos dados.
O processo mantém rastreabilidade por código de custo e produto, criando ou atualizando registros conforme a variação do valor informado.

Endpoint (API)

O endpoint recebe um COD_CUSTO_MEDIO e, opcionalmente, uma lista PRODUTOS com custos por item. Para cada item, valida se o cadastro de referência existe (produto acabado em PRODUTOS ou matéria prima em MATERIAIS) e persiste o custo na tabela OSK_RECEBE_CUSTO_MEDIO, criando o registro quando inexistente ou atualizando apenas quando o valor de CUSTO mudar.

Ao final, retorna Mensagem = OK e Mensagem Detalhada indicando que o registro foi concluído.

Estruturação de Dados

{
  "COD_CUSTO_MEDIO": "00000000",
  "PRODUTOS": [
    {
      "PRODUTO": "00000000000",
      "PA_MP": "PA",
      "CUSTO": 0
    }
  ]
}

Tratamento de Dados

Validação estrutural: o payload é validado conforme o dicionário de campos, exigindo COD_CUSTO_MEDIO e, quando houver itens em PRODUTOS, exigindo PRODUTO e PA_MP por item.

Validação de existência por item (quando PRODUTOS estiver preenchido):
- Se PA_MP for MP, verifica existência do cadastro em MATERIAIS usando filtro MATERIAL = PRODUTO, priorizando o registro mais recente por DATA_PARA_TRANSFERENCIA descendente. Se não existir, retorna erro com a mensagem O 'MATERIAL' = '<PRODUTO>' não foi encontrado..
- Se PA_MP for PA, verifica existência do cadastro em PRODUTOS usando filtro PRODUTO = PRODUTO, priorizando o registro mais recente por DATA_PARA_TRANSFERENCIA descendente. Se não existir, retorna erro com a mensagem O 'PRODUTO' = '<PRODUTO>' não foi encontrado..

Persistência controlada por item: para cada item, monta o conjunto de campos e persiste em OSK_RECEBE_CUSTO_MEDIO com transação, aplicando as regras:
- Sempre define DATA_INSERIDO como data/hora atual e ATUALIZADO = 0 para o registro preparado.
- Insere quando não existir registro com COD_CUSTO_MEDIO e PRODUTO.
- Atualiza apenas quando CUSTO informado for diferente do CUSTO persistido (comparação por casting numérico). Nesse caso, define DATA_ATUALIZADO com o valor NULL() conforme implementado.
- Se o CUSTO for igual ao persistido, não executa atualização.

Integração com o Protheus

Não há chamada de integração externa para o Protheus neste endpoint. O processamento consiste em validações e persistência em banco de dados local, com registro em OSK_RECEBE_CUSTO_MEDIO.

Tratamento de retorno

Sucesso: quando todas as validações passarem e a persistência por item for concluída, o retorno inclui Mensagem = OK e Mensagem Detalhada = Registrado com sucesso..
Erro: quando a validação estrutural falhar, quando um cadastro de referência não for encontrado em MATERIAIS ou PRODUTOS, ou quando ocorrer falha de banco durante insert/update, o endpoint interrompe o processamento e retorna exceção com o detalhe correspondente.

Encaminhamento em cenário de erro

Em erro de banco ao inserir/atualizar, a transação é desfeita e o erro é propagado com prefixo OSK_RECEBE_CUSTO_MEDIO, mantendo integridade dos registros e evitando persistência parcial.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint	Validação de entrada	Ao receber o payload, deve exigir COD_CUSTO_MEDIO e, quando houver itens em PRODUTOS, exigir PRODUTO e PA_MP para cada item.	Payload inválido deve ser rejeitado com mensagem de validação; payload válido segue para validação de existência.
Endpoint	Validação de existência	Para cada item, se PA_MP for MP deve validar o cadastro em MATERIAIS; se for PA deve validar o cadastro em PRODUTOS, priorizando o registro mais recente por DATA_PARA_TRANSFERENCIA.	Item inexistente deve causar erro com mensagem indicando o campo (MATERIAL ou PRODUTO) e o valor informado.
Endpoint	Persistência de custos	Ao persistir em OSK_RECEBE_CUSTO_MEDIO, deve inserir quando não existir registro para COD_CUSTO_MEDIO + PRODUTO e atualizar apenas quando o valor de CUSTO mudar, garantindo transação por item.	Registros devem ser criados/atualizados conforme regra e, em falha de banco, não deve haver persistência parcial (rollback).