ProtheusContaContabil (STATUS: AJUSTADO)

DocumentaçãDocumentação TéTécnica

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

HistóHistórico de VersõVersões

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

DescriçãDescrição

Este serviçserviço expõexpõe um endpoint para cadastro e atualizaçãatualização de contas contácontábeis no plano de contas, recebendo os dados via parâparâmetros e persistindo diretamente na tabela CTB_CONTA_PLANO.

Endpoint (API)

O endpoint recebe os parâparâmetros, valida os campos obrigatóobrigatórios conforme o schema definido, aplica a mámáscara em CONTA_CONTABIL e persiste ou atualiza o registro na tabela CTB_CONTA_PLANO.

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

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

EstruturaçãEstruturação de Dados

Tratamento de Dados

- MáMáscara de conta contácontábil: CONTA_CONTABIL éé formatado via getMaskContaContabil() antes da persistêpersistência.

- ReestruturaçãReestruturação para persistêpersistência (mapeamento hydrateCtbContaPlano): NOME éé truncado em 40 caracteres quando exceder o limite; DESC_CONTA recebe o valor de NOME; DESC_DETALHADA recebe o valor de DESCRICAO; DESC_CONTA_REDUZIDA recebe os primeiros 20 caracteres de DESCRICAO; LX_GRUPO_CONTABIL recebe o valor de GRUPO_CONTABIL. Os campos NOME, DESCRICAO e GRUPO_CONTABIL sãsão removidos do conjunto antes da persistêpersistência.

- GeraçãGeração de CODIGO_RESUMIDO: em cadastro novo (quando nãnão existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada), o cócódigo éé obtido via sqlGetSequencia('CTB_CONTA_PLANO.CODIGO_RESUMIDO'); em atualizaçãatualização, éé mantido o CODIGO_RESUMIDO do registro existente.

- DATA_PARA_TRANSFERENCIA: em cadastro novo, utiliza GETDATE(); em atualizaçãatualização, utiliza a data/hora atual formatada (Y-m-d H:i:s).

PersistêPersistência

Tabelas de banco de dados envolvidas: MOEDAS (origem das moedas para lista de validaçãvalidação), CTB_CONTA_TIPO (origem dos tipos de conta para lista de validaçãvalidação), CTB_CONTA_PLANO (persistêpersistência do cadastro da conta contácontábil).

Cadastro: quando nãnão existir registro com a CONTA_CONTABIL informada, éé executado INSERT em CTB_CONTA_PLANO com os campos mapeados em hydrateCtbContaPlano.

AtualizaçãAtualização: quando jájá existir registro (identificado por CONTA_CONTABIL e CODIGO_RESUMIDO), éé executado UPDATE em CTB_CONTA_PLANO com os campos mapeados e DATA_PARA_TRANSFERENCIA atualizada.

TransaçãTransação: a operaçãoperação éé executada dentro de transaçãtransação; em caso de exceçãexceção, éé realizado rollBack e a mensagem de erro éé prefixada com CTB_CONTA_PLANO:.

Tratamento de retorno

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

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

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

Fluxo do Processo

CritéCritérios de AceitaçãAceitação

Processo	Subprocesso	DescriçãDescrição	SituaçãSituação esperada
Endpoint	ValidaçãValidação de parâparâmetros	Ao receber parâparâmetros via run(), deve validar os campos obrigatóobrigatórios (CONTA_CONTABIL, NOME, DESCRICAO, INATIVA, MOEDA, TIPO_CONTA, GRUPO_CONTABIL) e as listas (MOEDA, TIPO_CONTA, GRUPO_CONTABIL).	Em parâparâmetros inváinválidos, exceçãexceção com mensagens de erro; em váválidos, prossegue para processamento.
Endpoint	Cadastro de conta nova	Quando nãnão existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada (apóapós mámáscara), deve gerar CODIGO_RESUMIDO, aplicar as transformaçõtransformações de mapeamento e executar INSERT na tabela.	Registro inserido em CTB_CONTA_PLANO e retorno com CODIGO_RESUMIDO, Mensagem = OK e Mensagem Detalhada.
Endpoint	AtualizaçãAtualização de conta existente	Quando jájá existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada, deve manter o CODIGO_RESUMIDO, aplicar as transformaçõtransformações e executar UPDATE na tabela com DATA_PARA_TRANSFERENCIA atualizada.	Registro atualizado em CTB_CONTA_PLANO e retorno com CODIGO_RESUMIDO, Mensagem = OK e Mensagem Detalhada.