ProtheusContaContabil (STATUS: VERIFICADO)
Documentação Técnica
| Nome do cliente | OSKLEN |
| Nome do projeto | Integração LINX → Protheus |
| Biblioteca | wosk_protheus_conta_contabil |
| 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 ProtheusContaContabil. |
Descrição
Este serviço expõe um endpoint para cadastro e atualização de contas contábeis no plano de contas, recebendo os dados via parâmetros e persistindo diretamente na tabela CTB_CONTA_PLANO.
Endpoint (API)
O endpoint recebe os parâmetros, valida os campos obrigatórios conforme o schema definido, aplica a máscara em CONTA_CONTABIL e persiste ou atualiza o registro na tabela CTB_CONTA_PLANO.
Em caso de falha na validação, o processo é interrompido com exceção contendo as mensagens de erro.
Em sucesso, retorna os parâmetros enriquecidos com CODIGO_RESUMIDO, Mensagem e Mensagem Detalhada.
Estruturação de Dados
| Campo | Tipo | Obrigatório | Descrição |
AGENCIA |
string (5) | Não | Agência da Conta contábil (caso não tenha, enviar nulo) |
BANCO |
string (5) | Não | Banco da Conta Contábil (caso não tenha, enviar nulo) |
CONTA_CONTABIL |
string (21) | Sim | Número da Conta Contábil (ex.: 1.01.01.02.0123) |
CONTA_CORRENTE |
bool (1) | Não | 1 para Conta corrente, 0 para outros tipos de conta |
NOME |
string (251) | Sim | Nome da Conta Contábil |
DESCRICAO |
string (251) | Sim | Descrição detalhada da Conta Contábil |
INATIVA |
bool (1) | Sim | 1 para conta contábil inativa |
MOEDA |
string (6) | Sim | Moeda (ex.: R$). Lista validada a partir da tabela MOEDAS |
NUMERO_CONTA_CORRENTE |
string (21) | Não | Número da Conta Corrente da Conta Contábil (caso não tenha, enviar nulo) |
TIPO_CONTA |
string (11) | Sim | Tipo de conta. Lista validada a partir da tabela CTB_CONTA_TIPO |
GRUPO_CONTABIL |
string (3) | Sim | Grupo contábil. Lista: A (ATIVO), C (CARTEIRA), D (DESPESA VARIÁVEL), E (EXTRA CONTÁBIL), F (DESPESA FIXA), P (PASSIVO), R (RECEITA) |
Valores de saída (retorno em sucesso)
| Campo | Descrição |
CODIGO_RESUMIDO |
Identificador único da conta no plano (gerado ou recuperado) |
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
- Máscara de conta contábil: CONTA_CONTABIL é formatado via getMaskContaContabil() antes da persistência.
- Reestruturação para 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ão removidos do conjunto antes da persistência.
- Geração de CODIGO_RESUMIDO: em cadastro novo (quando não existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada), o código é obtido via sqlGetSequencia('CTB_CONTA_PLANO.CODIGO_RESUMIDO'); em atualização, é mantido o CODIGO_RESUMIDO do registro existente.
- DATA_PARA_TRANSFERENCIA: em cadastro novo, utiliza GETDATE(); em atualização, utiliza a data/hora atual formatada (Y-m-d H:i:s).
Persistência
Tabelas de banco de dados envolvidas: MOEDAS (origem das moedas para lista de validação), CTB_CONTA_TIPO (origem dos tipos de conta para lista de validação), CTB_CONTA_PLANO (persistência do cadastro da conta contábil).
Cadastro: quando não existir registro com a CONTA_CONTABIL informada, é executado INSERT em CTB_CONTA_PLANO com os campos mapeados em hydrateCtbContaPlano.
Atualização: quando 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ção: a operação é executada dentro de transação; em caso de exceção, é realizado rollBack e a mensagem de erro é prefixada com CTB_CONTA_PLANO:.
Tratamento de retorno
Sucesso: retorna o array de parâmetros com CODIGO_RESUMIDO, 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 ou UPDATE, 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 (CONTA_CONTABIL, NOME, DESCRICAO, INATIVA, MOEDA, TIPO_CONTA, GRUPO_CONTABIL) e as listas (MOEDA, TIPO_CONTA, GRUPO_CONTABIL). |
Em parâmetros inválidos, exceção com mensagens de erro; em válidos, prossegue para processamento. |
| Endpoint | Cadastro de conta nova | Quando não existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada (após máscara), deve gerar CODIGO_RESUMIDO, aplicar as 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ção de conta existente | Quando já existir registro em CTB_CONTA_PLANO para a CONTA_CONTABIL informada, deve manter o CODIGO_RESUMIDO, aplicar as 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. |
Nenhum comentário