ProtheusContaContabil (STATUS: PARCIAL)
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
Esta biblioteca 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 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 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.
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).
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
O endpoint não realiza chamada HTTP ao Protheus. A integração ocorre por persistência direta na tabela CTB_CONTA_PLANO.
- 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.
Encaminhamento em cenário de erro
Não há encaminhamento para fila ou fluxo alternativo. Os erros são propagados via exceção ao chamador do endpoint.
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