Skip to main content

API Backup

O plugin Accelero API Backup (apibackup) expõe um endpoint HTTP que dispara um backup completo do banco de dados do ACCELERO e o envia, como arquivo, para uma URL de callback informada na própria requisição. É uma ferramenta de infraestrutura/automação, usada por rotinas externas da IONGRADE para coletar backups sob demanda.

Ferramenta de infraestrutura (uso interno)

Este plugin não tem interface de usuário, telas de configuração nem itens de menu. Ele apenas registra uma rota HTTP que executa um dump do banco e o entrega a um endpoint externo. É instalado pela equipe técnica da IONGRADE quando há necessidade de automatizar a coleta de backups — não é um recurso voltado ao cliente final.

Disponibilidade

Disponibilizado como plugin (apibackup), instalado e habilitado pela equipe técnica da IONGRADE.

Compatibilidade

Versão atual do plugin: 0.0.1 — compatível com ACCELERO 2.16.5, 2.16.6, 2.16.7 e 2.16.8 (conforme manifest.json).

O que o plugin faz​

FuncionalidadeO que acontece no ACCELERO
Endpoint de backupRegistra a rota POST external/apibackup/create, que recebe uma callbackUrl e enfileira o backup
Geração do backupUm job assíncrono carrega as credenciais do banco e gera um dump completo via BackupDatabase
Entrega via callbackO arquivo de backup é enviado por POST multipart (campo file) para a callbackUrl informada
LimpezaApós o envio bem-sucedido, o arquivo temporário é removido do servidor
Benefício

Permite que uma rotina externa solicite um backup do banco e o receba automaticamente, sem acesso direto ao servidor do ACCELERO.

Endpoint​

ItemValor
MétodoPOST
Caminhoexternal/apibackup/create

Corpo da requisição​

O corpo deve ser um JSON com um único campo:

CampoTipoDescrição
callbackUrlstring (URL)URL para a qual o arquivo de backup será enviado após a geração. Validada com FILTER_VALIDATE_URL — URLs inválidas são rejeitadas

Exemplo de corpo:

{
  "callbackUrl": "https://exemplo.iongrade.com/recebe-backup"
}

Respostas​

SituaçãoStatus HTTPCorpo
Requisição aceita e enfileirada200{ "message": "Backup request created successfully" }
callbackUrl ausente, inválida ou JSON malformado400{ "error": "<mensagem>" }
Resposta é apenas o enfileiramento

O 200 indica que a solicitação foi aceita e enfileirada — não que o backup já foi gerado e entregue. A geração e o envio ocorrem de forma assíncrona, depois da resposta.

Autenticação

A rota está registrada sob o prefixo external/. O hardcode do plugin não contém verificação de autenticação/token dentro do controller — qualquer controle de acesso depende da configuração do roteador external do núcleo do ACCELERO.

TODO: Confirmar proteção da rota

Confirmar com o núcleo (plugins/accelero) como as rotas sob external/ são protegidas (token, IP allowlist, rede interna) e documentar o requisito de autenticação real desta rota.

Como o backup é processado​

O endpoint apenas enfileira o trabalho; toda a geração e a entrega acontecem em um job assíncrono (AcceleroApiBackupDatabaseJob), executado pelo runner assíncrono do ACCELERO.

Fluxo do job:

  1. Valida a callbackUrl novamente; se ausente ou inválida, aborta sem gerar backup.
  2. Carrega as credenciais do banco (CredentialManager → credencial database); se não encontradas, aborta.
  3. Gera o backup do banco via BackupDatabase, gravando o arquivo em um diretório temporário privado do servidor.
  4. Envia o arquivo por POST multipart (campo file) para a callbackUrl. Se a resposta não for 200, registra erro e lança exceção.
  5. Remove o arquivo temporário após o envio bem-sucedido.
Falha no envio não limpa nem reenvia

Se o destino (callbackUrl) responder com status diferente de 200, o job lança exceção. Não há, no hardcode, lógica de retry própria nem limpeza do arquivo nesse caminho de erro — o tratamento depende do runner assíncrono do núcleo.

TODO: Confirmar comportamento de retry

Verificar no runner assíncrono do ACCELERO se jobs que lançam exceção são reagendados/retentados e documentar o comportamento real em caso de falha de entrega.

Instalação​

Após instalar/atualizar o plugin, o post_install.php executa:

  • Accelero::restartServices() — reinicia os serviços do ACCELERO para registrar a nova rota.
  • Limpeza do cache (CacheInterface::clear()).

Não há migrations, permissões nem configuração inicial — o plugin não cria tabelas nem campos.

Casos de uso​

Coletar um backup sob demanda a partir de uma rotina externa​

  1. A rotina externa expõe um endpoint capaz de receber um upload multipart (campo file).
  2. A rotina chama POST external/apibackup/create no ACCELERO com a callbackUrl apontando para esse endpoint.
  3. O ACCELERO responde 200 confirmando o enfileiramento.
  4. De forma assíncrona, o ACCELERO gera o dump do banco e o envia para a callbackUrl.
  5. O endpoint externo recebe e armazena o arquivo de backup.

Boas práticas​

  • Destino confiável: a callbackUrl recebe um dump completo do banco — aponte apenas para endpoints controlados pela IONGRADE, idealmente em rede privada ou com transporte criptografado (HTTPS).
  • Endpoint receptor pronto antes de disparar: a rotina receptora precisa responder 200 ao upload; caso contrário o job falha e o backup não é entregue.
  • Instalar sob demanda: por se tratar de uma rota que exporta o banco inteiro, mantenha o plugin instalado apenas enquanto a automação de backup estiver em uso.

Troubleshooting​

A requisição retorna 400​

Possíveis causas:

  • Corpo não é um JSON válido.
  • Campo callbackUrl ausente.
  • callbackUrl não é uma URL válida.

Solução: envie um JSON bem-formado contendo callbackUrl com uma URL válida.

Requisição retorna 200 mas o backup não chega ao destino​

Possíveis causas:

  • Credenciais do banco (database) não encontradas pelo CredentialManager — o job aborta antes de gerar o dump.
  • O endpoint da callbackUrl não respondeu 200 ao receber o arquivo.
  • Falha durante a geração do dump (BackupDatabase).

Solução:

  1. Verifique os logs do ACCELERO — o job registra mensagens em cada etapa (Starting backup process, Backup process completed successfully, ou os erros correspondentes).
  2. Confirme que o endpoint receptor aceita upload multipart e responde 200.
  3. Confirme que a credencial database está configurada no servidor.

Integração com outros módulos​

Próximos Passos​