ProtheusCentroCusto (STATUS: PARCIAL)

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

Esta biblioteca 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 um array de parâmetros via método run(), valida os campos obrigatórios conforme o schema definido em $fields, aplica a máscara em CENTRO_CUSTO e persiste ou atualiza os registros nas tabelas de centro de custo. Em caso de falha na validação, o processo é interrompido com exceção contendo as mensagens de erro. 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 item 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.

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).

Estruturação de Dados

Tratamento de Dados

- Máscara de centro de custo: CENTRO_CUSTO e RATEIO_CENTRO_CUSTO são formatados via getMaskCentroCusto() antes da persistência.

- Normalização numérica: PORCENTAGEM é normalizado via getNumeric() (padrão 2 casas decimais) antes da persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM.

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

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

- Reestruturação para persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM (mapeamento hydrateCtbCentroCustoRateioItem): CENTRO_CUSTO recebe o valor mascarado de RATEIO_CENTRO_CUSTO; PORCENTAGEM recebe o valor normalizado; RATEIO_CENTRO_CUSTO recebe o valor mascarado de CENTRO_CUSTO; RATEIO_CENTRO_CUSTO_ITEM recebe o valor de ITEM.

Persistência

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

- 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 item 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 item do rateio.	Registros persistidos nas tabelas CTB_CENTRO_CUSTO_RATEIO e CTB_CENTRO_CUSTO_RATEIO_ITEM, com retorno de sucesso.