ProtheusCentroCusto (STATUS: REVISANDO)
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
| Campo |
Tipo |
Obrigatório |
Descrição |
CENTRO_CUSTO |
string (15) |
Sim |
Nome/Número do Centro de Custo |
DESCRICAO |
string (40) |
Sim |
Descrição do Centro de custo |
INATIVA |
bool (1) |
Sim |
1 para centro de custo inativo |
GRUPO_CENTRO_CUSTO |
number (10) |
Sim |
Grupo do Centro de Custo (EM LISTA). Lista validada a partir da tabela CTB_CENTRO_CUSTO_GRUPO |
RATEIOS |
array |
Não |
Lista do rateio feitos entre os Centros de Custo. Cada registro contém: ITEM (number 14), RATEIO_CENTRO_CUSTO (string 15), PORCENTAGEM (number 14) |
Valores de saída (retorno em sucesso)
| Campo |
Descrição |
Mensagem |
Valor fixo OK em sucesso |
Mensagem Detalhada |
Mensagem descritiva (ex.: "Registrado com sucesso.") |
Demais parâmetros |
Repassados do payload de entrada |
Tratamento de Dados
-CENTRO_CUSTO, MáRATEIO_CENTRO_CUSTO: aplica máscara de centro de custo:custo CENTRO_CUSTO e RATEIO_CENTRO_CUSTO são formatados viautilizando getMaskCentroCusto() antes da persistência.
-
Normalização numérica: PORCENTAGEM: énormaliza normalizadovalor vianumérico utilizando getNumeric() (com padrão de 2 casas decimais)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, ID_GRUPO_CENTRO_CUSTO: repassa valores de 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)s) em atualização.
- Reestruturação para persistência em CTB_CENTRO_CUSTO_RATEIOCTB_CENTRO_CUSTO
(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: =define valor 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_ITEMCTB_CENTRO_CUSTO_RATEIO
(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 para persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM.
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:Sucesso: retorna o array de parâmetros com Mensagem = OK e Mensagem Detalhada = "Registrado com sucesso."
- Erro de validação:o: quando validar() retornar mensagens, o processo é interrompido com exceção contendo as mensagens concatenadas.
- Erro de persistência: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. |
