ProtheusCentroCusto (STATUS: REVISADO)

Documentação Técnica

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

Histórico de Versões

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

Descrição

Expõe um endpoint para cadastro e atualização de centros de custo e seus rateios, recebendo os dados via parâmetros e persistindo diretamente nas tabelas CTB_CENTRO_CUSTO, CTB_CENTRO_CUSTO_RATEIO e CTB_CENTRO_CUSTO_RATEIO_ITEM.

Endpoint (API)

O endpoint recebe os parâmetros, valida os campos obrigatórios conforme o schema definido, aplica a máscara em CENTRO_CUSTO e persiste ou atualiza os registros nas tabelas de centro de custo.

Quando houver RATEIOS, o fluxo persiste o centro de custo como rateio em CTB_CENTRO_CUSTO_RATEIO, remove os itens antigos de CTB_CENTRO_CUSTO_RATEIO_ITEM e insere/atualiza cada registro do rateio.

Quando não houver RATEIOS, persiste apenas cadastro simples em CTB_CENTRO_CUSTO.

Em sucesso, retorna os parâmetros enriquecidos com Mensagem e Mensagem Detalhada.

Em caso de falha na validação, o processo é interrompido com exceção contendo as mensagens de erro.

Estruturação de Dados

CENTRO_CUSTO, RATEIO_CENTRO_CUSTO: aplica máscara de centro de custo utilizando getMaskCentroCusto() antes da persistência.

PORCENTAGEM: normaliza valor numérico utilizando getNumeric() com padrão de 2 casas decimais antes da persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM.

CENTRO_CUSTO: recebe valor mascarado; DESC_CENTRO_CUSTO: recebe valor de DESCRICAO; INATIVA, ID_GRUPO_CENTRO_CUSTO: repassa valores de INATIVA e GRUPO_CENTRO_CUSTO; DATA_PARA_TRANSFERENCIA: utiliza GETDATE() em cadastro novo ou data/hora atual formatada (Y-m-d H:i:s) em atualização para persistência em CTB_CENTRO_CUSTO.

DESC_RATEIO_CENTRO_CUSTO: recebe valor de DESCRICAO; INATIVO: recebe valor de INATIVA; RATEIO_CENTRO_CUSTO: recebe valor mascarado de CENTRO_CUSTO; RATEIO_ENTRAR_EM_LISTA: define valor 1; DATA_PARA_TRANSFERENCIA: utiliza GETDATE() em cadastro novo ou data/hora atual em atualização para persistência em CTB_CENTRO_CUSTO_RATEIO.

CENTRO_CUSTO: recebe valor mascarado de RATEIO_CENTRO_CUSTO; PORCENTAGEM: recebe valor normalizado; RATEIO_CENTRO_CUSTO: recebe valor mascarado de CENTRO_CUSTO; RATEIO_CENTRO_CUSTO_ITEM: recebe valor de ITEM para persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM.

Persistência

O endpoint não realiza chamada HTTP ao Protheus. A integração ocorre por persistência direta nas tabelas.

Tabelas de banco de dados envolvidas: CTB_CENTRO_CUSTO_GRUPO (origem dos grupos de centro de custo para lista de validação), CTB_CENTRO_CUSTO (persistência do cadastro do centro de custo), CTB_CENTRO_CUSTO_RATEIO (persistência do cadastro de rateio), CTB_CENTRO_CUSTO_RATEIO_ITEM (persistência dos itens de rateio).

- Cadastro simples (sem RATEIOS): quando não existir registro com o CENTRO_CUSTO informado (após máscara), é executado INSERT em CTB_CENTRO_CUSTO; quando já existir, é executado UPDATE em CTB_CENTRO_CUSTO com DATA_PARA_TRANSFERENCIA atualizada.

- Cadastro com rateio (com RATEIOS): primeiro persiste em CTB_CENTRO_CUSTO_RATEIO (INSERT ou UPDATE). Em seguida, executa DELETE FROM CTB_CENTRO_CUSTO_RATEIO_ITEM WHERE RATEIO_CENTRO_CUSTO = ... para remover os itens antigos. Para cada registro do array RATEIOS, persiste em CTB_CENTRO_CUSTO_RATEIO_ITEM (INSERT ou UPDATE).

- Transação: cada operação (setCtbCentroCusto, setCtbCentroCustoRateio, setCtbCentroCustoRateioItem) é executada dentro de transação; em caso de exceção, é realizado rollBack e a mensagem de erro é prefixada com o nome da tabela afetada.

Tratamento de retorno

- Sucesso: retorna o array de parâmetros com Mensagem = OK e Mensagem Detalhada = "Registrado com sucesso."

- Erro de validação: quando validar() retornar mensagens, o processo é interrompido com exceção contendo as mensagens concatenadas.

- Erro de persistência: em falha no INSERT, UPDATE ou DELETE, a transação é revertida e é lançada exceção com detalhes do erro.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint	Validação de parâmetros	Ao receber parâmetros via run(), deve validar os campos obrigatórios (CENTRO_CUSTO, DESCRICAO, INATIVA, GRUPO_CENTRO_CUSTO) e a lista GRUPO_CENTRO_CUSTO (origem em CTB_CENTRO_CUSTO_GRUPO).	Em parâmetros inválidos, exceção com mensagens de erro; em válidos, prossegue para processamento.
Endpoint	Cadastro simples de centro de custo	Quando não houver RATEIOS e não existir registro em CTB_CENTRO_CUSTO para o CENTRO_CUSTO informado (após máscara), deve aplicar as transformações definidas e executar INSERT na tabela.	Registro inserido em CTB_CENTRO_CUSTO e retorno com Mensagem = OK e Mensagem Detalhada.
Endpoint	Cadastro com rateio	Quando houver RATEIOS, deve persistir em CTB_CENTRO_CUSTO_RATEIO, remover itens antigos de CTB_CENTRO_CUSTO_RATEIO_ITEM e inserir/atualizar cada registro do rateio.	Registros persistidos nas tabelas CTB_CENTRO_CUSTO_RATEIO e CTB_CENTRO_CUSTO_RATEIO_ITEM, com retorno de sucesso.