VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Backups

Criar e consultar backups

Lista os backups, pede um backup manual, acompanha o andamento e consulta o estado do agendador noturno.

O backup guarda uma cópia do banco de dados da loja (pedidos, produtos, clientes, configurações) e, junto, um pacote com as mídias enviadas. Ele roda em segundo plano: você pede, recebe 202 e consulta até o status virar completed. A plataforma também faz um backup automático por noite. Todas as rotas desta página exigem o privilégio manage_backups ou manage_settings.

Listar backups

GET/api/v1/admin/backupsAdmin

Lista todos os backups da loja

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/backups" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Backups
json
{
  "backups": [
    {
      "id": "d216291a-0c77-4eec-9c1e-8ffe034b2474",
      "name": "Scheduled 2026-10-09",
      "description": "Created by the backup scheduler (tick 2026-10-09T03:00)",
      "file_size": 997428729,
      "media_file_size": 866636650,
      "status": "completed",
      "started_at": "2026-10-09T03:00:00.171646Z",
      "completed_at": "2026-10-09T03:05:42.379305Z",
      "created_at": "2026-10-09T03:00:00.168726Z",
      "updated_at": "2026-10-09T03:06:14.876154Z"
    }
  ],
  "total": 190
}

Campos da resposta

backupsarray
Todos os backups, sem paginação, do mais novo para o mais antigo.
totalinteger
Quantidade de itens em backups.
backups[].iduuid
Id do backup.
backups[].namestring
Nome. Nos backups automáticos é Scheduled AAAA-MM-DD; nos manuais sem nome é Backup AAAA-MM-DD HH:MM:SS (UTC).
backups[].descriptionstring
Descrição livre. Ausente quando vazia.
backups[].file_sizeinteger
Tamanho do arquivo do banco, em bytes. 0 enquanto não termina ou se falhou.
backups[].media_file_sizeinteger
Tamanho do pacote de mídias (imagens e arquivos enviados), em bytes. 0 quando não há pacote; maior que zero indica que o download de mídias está disponível.
backups[].statusstring
pendingrunningcompletedfailedrestoringrestoredexpired
Estado do backup. Veja a tabela na home da seção.
backups[].error_msgstring
Motivo da falha, quando status é failed.
backups[].created_byuuid
Administrador que pediu o backup. Ausente nos automáticos.
backups[].started_at / completed_at / restored_atstring
Início, fim da geração e fim da última restauração (RFC 3339, UTC). Ausentes enquanto não ocorreram.
backups[].created_at / updated_atstring
Criação e última alteração do registro (RFC 3339, UTC).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_backups","manage_settings"]}
500Falha ao ler os registros.{"error":"failed to list backups","detail":"..."}
Sem paginação

A lista devolve todos os registros de uma vez. Como o histórico cresce um registro por noite, filtre pelo seu lado (por exemplo status == completed) em vez de esperar parâmetros de filtro.

Criar backup

Inicia um backup em segundo plano e devolve o registro ainda pending. Guarde o id e consulte Consultar um backup até o status mudar.

POST/api/v1/admin/backupsAdmin

Pede um backup manual

Corpo da requisição

namestring
Nome do backup. Se vazio ou só espaços, a plataforma usa Backup AAAA-MM-DD HH:MM:SS.
descriptionstring
Descrição livre.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/backups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Antes da migração de catálogo", "description": "Backup manual"}'

Resposta

202Backup aceito
json
{
  "id": "7f1c1b0e-0d2a-4d57-9c3e-2f6b1f6f9a10",
  "name": "Antes da migração de catálogo",
  "description": "Backup manual",
  "file_size": 0,
  "media_file_size": 0,
  "status": "pending",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:30:00Z",
  "updated_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

iduuid
Id do backup.
namestring
Nome. Nos backups automáticos é Scheduled AAAA-MM-DD; nos manuais sem nome é Backup AAAA-MM-DD HH:MM:SS (UTC).
descriptionstring
Descrição livre. Ausente quando vazia.
statusstring
pending no momento da criação.
demais campos-
Os mesmos de Listar backups.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_backups","manage_settings"]}
400Corpo não é JSON válido. Um corpo vazio também dá 400: envie ao menos {}.{"error":"invalid request body","detail":"EOF"}
500Não foi possível registrar o backup.{"error":"failed to create backup","detail":"..."}
O que entra no backup

O arquivo do banco é um dump compactado (.sql.gz). As mídias vão em um segundo pacote (.tar.gz); se o pacote de mídias falhar, o backup do banco ainda termina como completed, com media_file_size igual a 0.

Consultar um backup

GET/api/v1/admin/backups/{id}Admin

Estado de um backup

Parâmetros de caminho

iduuidobrigatório
Id do backup.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/backups/d216291a-0c77-4eec-9c1e-8ffe034b2474" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Backup
json
{
  "id": "d216291a-0c77-4eec-9c1e-8ffe034b2474",
  "name": "Scheduled 2026-10-09",
  "description": "Created by the backup scheduler (tick 2026-10-09T03:00)",
  "file_size": 997428729,
  "media_file_size": 866636650,
  "status": "completed",
  "started_at": "2026-10-09T03:00:00.171646Z",
  "completed_at": "2026-10-09T03:05:42.379305Z",
  "created_at": "2026-10-09T03:00:00.168726Z",
  "updated_at": "2026-10-09T03:06:14.876154Z"
}

Campos da resposta

iduuid
Id do backup.
demais campos-
Os mesmos de Listar backups, sem o envelope.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_backups","manage_settings"]}
404Backup não existe.{"error":"backup not found"}
500id não é um UUID válido (a mensagem vem em português).{"error":"failed to get backup","detail":"o valor \"abc\" não é um uuid válido..."}
Como acompanhar

Consulte a cada 10 a 30 segundos. Passa por pending, running e termina em completed ou failed (com error_msg). Um backup de banco com cerca de 1 GB leva alguns minutos.

Estado do agendador

GET/api/v1/admin/backups/scheduler/statusAdmin

Estado do agendador de backups

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/backups/scheduler/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendador
json
{
  "enabled": true,
  "schedule": "0 3 * * *",
  "fallback_active": false,
  "next_run": "2026-10-12T03:00:00Z",
  "last_pass_at": "2026-10-11T20:50:25.223Z",
  "last_tick": "2026-10-11T03:00"
}

Campos da resposta

enabledboolean
true quando o backup automático está ligado nesta instalação.
schedulestring
Expressão cron do agendamento (0 3 * * * = todo dia às 03:00).
fallback_activeboolean
true quando a expressão configurada era inválida e a plataforma está usando o padrão diário das 03:00.
next_runstring
Próxima execução (RFC 3339, UTC). Pode ser null.
last_pass_atstring
Última passada do agendador neste processo. Ausente se ainda não houve.
last_tickstring
O horário do agendamento que a última passada cobriu (AAAA-MM-DDTHH:MM).

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_backups","manage_settings"]}
O agendamento não é editável pela API

Horário e retenção são configuração da instalação, não da loja. Esta rota só mostra o estado.

Veja também

  • Baixar backups
  • Restaurar e excluir
  • Erros da API
Anterior
Backups
Próxima
Baixar backups
Nesta página
  • Listar backups
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar backup
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um backup
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estado do agendador
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também