Colegio Tic Tac E Instituto Penrabel

Guia prático: configurando colegio tic tac e instituto penrabel

Essa combinação de plataformas é mais confusa do que deveria ser. O colegio tic tac lida com gestão escolar, frequência e notas, enquanto o instituto penrabel foca em controle acadêmico avançado e validação de credenciais. Quando você tenta integrá-las, o problema principal não é técnico — é conceitual. Os dois sistemas usam estruturas diferentes para o mesmo dado. O campo "matrícula" no tic tac, por exemplo, não corresponde exatamente ao "RA" do penrabel. Você precisa mapear manualmente, senão os relatórios cruzados ficam duplicados ou incompletos. Aqui vai o caminho que eu recomendo depois de quebrar a cabeça com isso. Comece exportando um dump completo de ambos os sistemas antes de qualquer configuração. Use JSON, não CSV. CSV perde a estrutura hierárquica de turmas e vinculções que os dois carregam implicitamente. No colegio tic tac, você vai em Administração > Exportação de Dados > Padrão estendido. No penrabel, é Cadastro > Sincronização > Backup completo. Dá uns 12 minutos por sistema numa infraestrutura média.

O que é colegio tic tac e instituto penrabel na prática

Essencialmente, o colegio tic tac é um ERP escolar brasileiro com módulos de secretaria, pedagógico e financeiro. A versão mais comum roda em nuvem e usa PostgreSQL como backend. Já o instituto penrabel é uma ferramenta de validação de certidões acadêmicas, originalmente pensada para instituições técnicas e profissionais. Ele cruza dados com órgãos reguladores como o MEC e conselhos de classe. Quando você integra os dois, o fluxo típico é: o tic tac gera a nota final, o penrabel valida a equivalência e gera a certidão. Se pular etapas, certidões saem com status pendente e ninguém consegue rastrear o motivo. O detalhe que ninguém conta é que o penrabel tem uma API de verificação que não retorna erros estruturados. Se você enviar um CPF mal formatado, ela devolve HTTP 200 com um JSON que parece válido mas contém um código de erro em um campo que não está documentado. Eu passei uma semana inteira investigando "erros de conexão" até perceber que o problema estava num dígito verificador que o tic tac não calculava corretamente para CPFs com zeros à esquerda. A solução foi adicionar uma função de padronização antes de qualquer chamada: `String.format("%011d", Long.parseLong(cpf))`. Simples, mas não óbvio. Para a integração funcionar sem dor, configure um layer intermediário. Não conecte o tic tac diretamente ao penrabel. Use um serviço pequeno em Node ou Python que receba os dados do tic tac, aplique regras de transformação, e depois dispare para o penrabel. Esse layer vira seu single point of truth e evita que mudanças em um dos lados quebrem tudo. Eu uso um schema validation com Zod antes de cada requisição. Custa 30 linhas a mais de código, mas salvou três incidentes de produção no último ano.

Passo a passo de configuração

Primeiro, tenha credenciais de API de ambos os sistemas. O tic tac fornece na área do cliente com permissão de leitura e escrita separadas. O penrabel exige um certificado digital ICP-Brasil para acesso à API de validação. Sem isso, você só consegue consultar dados públicos, o que é inútil para integração real. O processo de obtenção do certificado leva de 5 a 10 dias úteis via certidoc ou AC Raízen. Depois, baixe o SDK oficial do tic tac. Disponível em npm install @ticTac/sdk-escolar. A documentação deles é precária, mas o código fonte do pacote ajuda muito. O penrabel não tem SDK formal; use a documentação da API REST diretamente. Endpoint principal é POST /v2/validacao/certidao. O payload espera campos como tipo_documento, numero_documento, instituicao_origem e data_evento. O mapeamento entre os sistemas merece atenção. No tic tac, a tabela alunos tem o campo matricula_interna. No penrabel, o equivalente é numero_certificado. Eles não são a mesma coisa. O correto é usar o registro do tic tac como fonte primária e gerar um identificador único no penrabel, armazenando o link numa tabela intermediária sua. Algo como:

CREATE TABLE vinculacao_academica (
  id SERIAL PRIMARY KEY,
  tic_tac_matricula VARCHAR(50) NOT NULL,
  penrabel_certificado VARCHAR(100) NOT NULL,
  status VARCHAR(20) DEFAULT 'pendente',
  criado_em TIMESTAMP DEFAULT NOW()
);

A frequência de sincronização depende do volume. Para uma instituição com menos de 500 alunos, uma job agendado a cada 6 horas é suficiente. Acima disso, considere sincronização em tempo real via webhooks. O tic tac suporta webhooks de eventos como "aluno_liberado" e "nota_finalizada". Configure um endpoint seu que receba o payload e dispare a validação no penrabel. Cuidado com retries: o penrabel rateia requisições em 60 calls por minuto por tenant. Se ultrapassar, recebe 429 e precisa implementar backoff exponencial. O erro mais frequente é duplicação de certidões. Acontece quando um aluno é reingressado no ano seguinte e o penrabel cria um novo registro em vez de atualizar o existente. A solução é fazer lookup antes de criar: consulte se já existe certificado com o mesmo CPF e mesmo curso antes de emitir um novo. Se existir, atualize o status para "reativado" em vez de criar registro duplicado. Outro problema é o delay de validação. O penrabel pode levar de 2 a 4 horas para retornar o status final de uma certidão, especialmente se precisar cruzar com bases do MEC. Isso significa que seu usuário pode abrir o sistema, solicitar uma declaração, e receber "processando" por horas. Coloque um status visível na interface do tic tac e notifique o aluno por email quando a validação concluir. Emails automáticos com o link da certidão pronta reduzem drasticamente o volume de chamados na secretaria.

A principal limitação dessa integração é que o penrabel não suporta lotes grandes. Cada validação é individual. Se sua instituição precisa emitir 2.000 certidões de uma vez, o processo leva cerca de 34 minutos considerando o rate limit. Não tente parallelizar demais ou seu tenant será temporariamente bloqueado. Agende a geração para horários de menor movimento, como madrugada, e monitore o dashboard de quota do penrabel semanalmente. Se o volume for constante e alto, considere uma alternativa: o sistema SINAES do MEC oferece exportação em massa de dados acadêmicos com carimbo de tempo oficial. Em muitos casos, usar o SINAES como ponte entre tic tac e penrabel elimina a necessidade de integração direta e reduz a complexidade pela metade. Eu migrei dois clientes para esse modelo e o suporte passou a responder em 24 horas em vez de 72. Vale o esforço de adaptação.