Documentação Oficial OficinaOS

Guia Completo de Backup & Notificações

Estrutura de scripts, menu interativo Windows, arquivos de log, progresso em tempo real e tokens das APIs do Telegram, Google Drive e Dropbox.

Menu de Backup & Estrutura de Logs do Sistema

Conheça o menu interativo para controle dos backups, os agendamentos no Windows Task Scheduler e como inspecionar os arquivos de log e status.

1
Menu Interativo CLI (menu_backup.bat)

O arquivo c:\laragon\www\oficinaos\backup\menu_backup.bat é um utilitário em linha de comando desenvolvido para facilitar a gestão dos backups sem precisar abrir o navegador.

C:\laragon\www\oficinaos\backup\menu_backup.bat

Opções disponíveis no Menu:

Opção Nome da Ação Descrição / O que faz
[1] BackUp BD Exporta a estrutura e dados do banco de dados MySQL para um arquivo .sql, compacta em .zip com senha e envia para o Telegram.
[2] BackUp FULL Realiza o backup total (Código do sistema + Banco MySQL) criptografado com senha. Faz upload automático para o Google Drive, Dropbox e envia o banco para o Telegram.
[3] BackUp BD (Local) Exporta o banco de dados MySQL apenas para a pasta local da máquina (sem enviar para o Telegram nem nuvem).
[4] BackUp FULL (Local) Gera o arquivo .zip completo do sistema e do banco apenas na pasta local, sem realizar nenhuma transmissão pela rede.
[5] Agendar a cada Hora Cria uma rotina automatizada no Agendador de Tarefas do Windows (Task Scheduler) chamada OficinaOS_Backup_Hourly para executar de hora em hora.
[6] Agendar Diariamente Cria uma rotina diária no Windows Task Scheduler chamada OficinaOS_Backup_Daily para rodar automaticamente todos os dias às 02:00.
[7] Remover Tarefas Exclui os agendamentos automáticos do Windows Task Scheduler.
[8] Status do Último Backup Lê e exibe na tela o conteúdo do arquivo backup_status.json e lista os últimos arquivos .zip gerados.
[9] Abrir Pasta de Backups Abre a pasta C:\laragon\www\backups_oficinaos diretamente no Windows Explorer.
2
Pasta de Destino e Arquivos de Log (backups_oficinaos)

Todos os arquivos compactados finais e relatórios de execução ficam centralizados no diretório:

C:\laragon\www\backups_oficinaos

Significado de cada arquivo na pasta:

Arquivo Tipo Finalidade / Conteúdo
backup_status.json JSON Mapeia o progresso em tempo real (0% a 100%), mensagem atual (ex: "Fazendo upload para Dropbox..."), nome do arquivo e timestamp. Usado pelo SweetAlert2 no painel web para exibir a barra de progresso.
telegram_log.txt LOG Registra todas as tentativas de envio de arquivos via Telegram Bot API, incluindo confirmação de entrega ou erros de chat_id / token.
drive_log.txt LOG Registra a renovação de tokens OAuth2 do Google Drive, requisições de upload resumável (Resumable Upload v3) e links de compartilhamento gerados.
dropbox_log.txt LOG Registra as chamadas para a API v2 do Dropbox (Upload `/2/files/upload`, tokens OAuth2 e criação de links compartilhados públicos).
mysqldump_error.log LOG Armazena mensagens de aviso ou erro caso o utilitário nativo mysqldump.exe encontre falhas durante a exportação das tabelas.
💡 Dica de Diagnóstico: Quando um upload para o Drive ou Dropbox falhar, abra o arquivo drive_log.txt ou dropbox_log.txt. Eles contêm o código exato de erro retornado pela API (ex: HTTP 401 token expirado, HTTP 403 sem permissão).
Telegram Bot (Bot Token & Chat ID)

O Telegram envia o arquivo compactado do banco de dados (.zip criptografado) diretamente no seu celular ou grupo corporativo, além dos links de download do Drive e Dropbox.

1
Criar um Robô no Telegram via @BotFather

Abra o seu aplicativo Telegram e pesquise pelo robô oficial de criação de bots:

Abrir @BotFather no Telegram →
  • Envie a mensagem /newbot.
  • O BotFather pedirá um nome para o robô (ex: OficinaOS Backup Bot).
  • Em seguida, defina um nome de usuário único terminando com bot (ex: oficinaos_meubackup_bot).
  • O BotFather enviará uma mensagem de sucesso contendo o HTTP API Token.
    Exemplo: 8769004229:AAHgdkZV2ZPCq59gL-xwp-MukMivr1kOFZM
  • Copie esse código completo: ele será usado no campo Token no OficinaOS.
2
Obter o seu Chat ID (Seu usuário ou Grupo)

O Chat ID indica para qual conversa ou grupo o Telegram enviará o arquivo de backup:

Opção A: Enviar para sua conta pessoal

  1. Pesquise no Telegram pelo bot @userinfobot ou @GetIDBot.
  2. Clique em Começar (/start).
  3. O bot responderá imediatamente com o seu Id numérico (ex: 5021194943).

Opção B: Enviar para um Grupo da Oficina

  1. Crie um Grupo no Telegram e adicione o robô que você criou no Passo 1.
  2. Adicione também o bot @GetIDBot no grupo.
  3. O bot enviará o Chat ID do grupo (Geralmente um número negativo, ex: -100123456789).
3
Iniciar conversa com o Robô

Antes do primeiro envio, abra a conversa individual com o robô que você criou (pesquisando pelo username dele) e clique em COMEÇAR (/start).

⚠️ Atenção: O Telegram proíbe bots de enviarem mensagens para usuários que nunca iniciaram conversa com eles antes. É obrigatório dar /start no bot uma vez.
Google Drive API (Client ID, Secret & Refresh Token)

O Google exige a criação de uma aplicação OAuth2 no Google Cloud Console para obter permissão de envio dos backups diretamente para a nuvem.

1
Criar um Projeto no Google Cloud Console

Acesse o console de desenvolvedores do Google com a conta onde deseja salvar os backups:

Abrir Google Cloud Console →
  • Clique no menu superior ao lado do logotipo "Google Cloud" e clique em Novo Projeto.
  • Defina o nome do projeto (ex: OficinaOS Backup) e clique em Criar.
2
Ativar a API do Google Drive

No menu lateral esquerdo do projeto criado:

  1. Vá em APIs e Serviços > Biblioteca.
  2. Pesquise por Google Drive API.
  3. Clique no resultado e clique no botão ATIVAR.
3
Configurar a Tela de Consentimento OAuth
  1. Vá em APIs e Serviços > Tela de permissão OAuth.
  2. Selecione o tipo de usuário: Externo e clique em Criar.
  3. Preencha o nome do app (ex: OficinaOS Backup) e seu e-mail de suporte.
  4. Avance até a aba Usuários de Teste e adicione o seu próprio endereço de e-mail Gmail.
⚠️ Atenção: Adicionar seu e-mail em "Usuários de teste" é essencial para conseguir gerar o token sem precisar passar pela verificação oficial do Google.
4
Criar Credenciais OAuth 2.0
  1. Vá em APIs e Serviços > Credenciais.
  2. Clique em + Criar Credenciais > ID do cliente OAuth.
  3. Selecione Tipo de aplicativo: Aplicação Web ou Desktop Application.
  4. Se escolher Web, adicione em URIs de redirecionamento autorizados o endereço:
    https://developers.google.com/oauthplayground
  5. Clique em Criar. Guarde o ID do Cliente (Client ID) e a Chave secreta do cliente (Client Secret).
5
Gerar o Refresh Token via OAuth Playground

Para conseguir um token permanente de atualização (Refresh Token):

Abrir Google OAuth Playground →
  1. No canto superior direito, clique no ícone de engrenagem ⚙️ (OAuth 2.0 configuration).
  2. Marque a opção Use your own OAuth credentials.
  3. Cole o seu OAuth Client ID e OAuth Client Secret gerados no Passo 4.
  4. Na lista de escopos à esquerda, role até Drive API v3 e marque https://www.googleapis.com/auth/drive.file.
  5. Clique no botão azul Authorize APIs e faça login com sua conta do Google.
  6. No Passo 2 do Playground, clique no botão Exchange authorization code for tokens.
  7. Copie o código gerado no campo Refresh token.
Dropbox API (App Key, App Secret & Token)

O Dropbox possui um processo simples de integração de apps que permite gerar tokens de longa duração ou ilimitados diretamente no painel do desenvolvedor.

1
Acessar o Console de Apps do Dropbox

Faça login com a conta do Dropbox onde ficarão os backups do sistema:

Abrir Dropbox App Console →
  • Clique no botão Create app.
  • Em Choose an API, escolha: Scoped access.
  • Em Choose the type of access, escolha: Full Dropbox (ou App folder).
  • Dê um nome para a aplicação (ex: OficinaOS-Backup-Sistemas).
  • Clique em Create app.
2
Configurar Permissões de Leitura e Escrita

Com a página do App aberta:

  1. Clique na aba Permissions no menu superior do App.
  2. Marque a opção files.content.write (Permite salvar e sobrescrever backups).
  3. Marque a opção files.content.read (Permite verificar integridade).
  4. Marque a opção sharing.write (Essencial para gerar os links de download direto no Telegram).
  5. Role até o final da página e clique no botão azul Submit.
⚠️ Importante: Se não marcar a permissão sharing.write, o Dropbox enviará o arquivo mas não conseguirá gerar o link público para o Telegram.
3
Copiar Credenciais (App Key & App Secret)
  1. Clique na aba Settings.
  2. Copie o código do campo App key (Este será usado como a Chave no OficinaOS).
  3. No campo App secret, clique em Show e copie a chave exibida (Usada como o Token).
4
Gerar o Token de Acesso (Access Token / Refresh Token)

Ainda na aba Settings do aplicativo no Dropbox:

  1. Role até a seção OAuth 2.
  2. Procure a subseção Generated access token.
  3. Clique no botão Generate.
  4. Um token longo será gerado. Copie todo o código exibido.
💡 Dica Pro: Você pode usar este token diretamente no campo URL Base do OficinaOS. Ele garantirá envios imediatos sem necessidade de fluxos complexos de renovação.
Cadastrar os Tokens no OficinaOS

Como inserir as credenciais obtidas dentro do painel administrativo do sistema para ativar o backup automático em nuvem.

1
Onde cadastrar no sistema
  1. Abra o OficinaOS no navegador e vá em Configurações > APIs.
  2. Localize os cards Telegram Backup, Google Drive Backup ou Dropbox Backup e clique em Editar.
2
Mapeamento dos Campos no OficinaOS

Preencha os campos exatamente como abaixo para cada serviço de backup:

✈️ Telegram Backup

  • Chave: Cole seu Chat ID (ex: 5021194943 ou ID do Grupo)
  • Token: Cole seu Bot Token (ex: 8769004229:AAHg...)
  • URL Base: Deixar em branco
  • Status: Ativo (1)

🔵 Google Drive Backup

  • Chave: Cole seu Client ID
  • Token: Cole seu Client Secret
  • URL Base: Cole seu Refresh Token
  • Status: Ativo (1)

🔷 Dropbox Backup

  • Chave: Cole sua App Key
  • Token: Cole seu App Secret
  • URL Base: Cole seu Generated Access Token (ou Refresh Token)
  • Status: Ativo (1)
3
Testando o Backup

Para testar se o backup em nuvem e as notificações estão funcionando perfeitamente:

  1. Execute o arquivo c:\laragon\www\oficinaos\backup\menu_backup.bat.
  2. Selecione a **Opção [2]** (BackUp FULL - Sistema Completo + BD).
  3. Acompanhe o log. Se tudo estiver correto, você receberá o arquivo no Telegram com os links de download direto do Drive e Dropbox!
  4. Em caso de erro em qualquer serviço, verifique os arquivos de log gerados na pasta backups_oficinaos:
    • telegram_log.txt (Erros de envio do Telegram)
    • drive_log.txt (Erros do Google Drive)
    • dropbox_log.txt (Erros do Dropbox)