APIs externas

Estos puntos finales están diseñados para ser utilizados por otras aplicaciones e integraciones, por ejemplo Página Principal. Están exentos de CSRF y no utilizan cookies de sesión.

La autenticación es opcional y está desactivada por defecto. Aunque las claves son opcionales, los clientes pueden omitir la clave o enviar una: se acepta y registra una clave válida de ámbito coincidente; una clave incorrecta se ignora y la solicitud sigue adelante. Cuando Requerir claves de API está habilitado en Claves de API, envía la clave como ?api_key=, X-Api-Key, o Authorization: Bearer. Las claves de subida solo funcionan en POST /api/upload. Las claves de lectura solo funcionan en /api/summary y /api/lastbackup*. Las claves de cadena de consulta aparecen en los registros de acceso del proxy inverso.

Una lista de IPs permitidas también puede restringir estas rutas. /api/health y /api/ping permanecen públicas mientras ambas listas estén desactivadas; cuando cualquiera de las listas está habilitada, aceptan loopback y CIDRs de la lista del administrador o externa, y los clientes no loopback tienen un límite de tasa.

Obtener Resumen General - `/api/summary`

Punto final: /api/summary
Método: GET
Descripción: Recupera un resumen de todas las operaciones de copia de seguridad en todos los servidores.

Respuesta:

{
  "totalServers": 3,
  "totalBackupsRuns": 9,
  "totalBackups": 9,
  "totalUploadedSize": 2397229507,
  "totalStorageUsed": 43346796938,
  "totalBackupSize": 126089687807,
  "overdueBackupsCount": 2,
  "secondsSinceLastBackup": 7200
}

Respuestas de Error:
- 401: Clave de API faltante o inválida cuando se requieren claves
- 403: El ámbito de la clave no es read, o la IP del cliente no está en la lista externa permitida
- 429: Límite de tasa de API de lectura excedido
- 500: Error del servidor al obtener datos de resumen
Notas:
- En la versión 0.5.x, el campo totalBackupedSize fue reemplazado por totalBackupSize
- En la versión 0.7.x, el campo totalMachines fue reemplazado por totalServers
- El campo overdueBackupsCount muestra el número de copias de seguridad actualmente pendientes
- El campo secondsSinceLastBackup muestra el tiempo en segundos desde la última copia de seguridad en todos los servidores
- Devuelve una respuesta de reserva con ceros si la obtención de datos falla
- Nota: Para uso en el panel interno, considera usar /api/dashboard que incluye estos datos más información adicional

Obtener Última Copia de Seguridad - `/api/lastbackup/:serverId`

Punto final: /api/lastbackup/:serverId
Método: GET
Descripción: Recupera la información de la última copia de seguridad para un servidor específico.
Parámetros:
- serverId: el identificador del servidor (ID o nombre)

nota

El identificador del servidor debe estar codificado en URL.

Respuesta:

{
  "server": {
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Backup Name",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backup": {
    "id": "backup-id",
    "server_id": "unique-server-id",
    "name": "Backup Name",
    "date": "2024-03-20T10:00:00Z",
    "status": "Success",
    "warnings": 0,
    "errors": 0,
    "messages": 150,
    "fileCount": 249426,
    "fileSize": 113395849938,
    "uploadedSize": 331318892,
    "duration": "00:38:31",
    "duration_seconds": 2311.6018052,
    "durationInMinutes": 38.52669675333333,
    "knownFileSize": 27203688543,
    "backup_list_count": 10,
    "messages_array": ["message1", "message2"],
    "warnings_array": ["warning1"],
    "errors_array": [],
    "available_backups": ["v1", "v2", "v3"]
  },
  "status": 200
}

Respuestas de Error:
- 401: Clave de API faltante o inválida cuando se requieren claves
- 403: El ámbito de la clave no es read, o la IP del cliente no está en la lista externa permitida
- 404: Servidor no encontrado
- 429: Límite de tasa de API de lectura excedido
- 500: Error interno del servidor
Notas:
- En la versión 0.7.x, la clave del objeto de respuesta cambió de machine a server
- El identificador del servidor puede ser ya sea ID o nombre
- Devuelve nulo para latest_backup si no existen copias de seguridad
- Incluye encabezados de control de caché para evitar el almacenamiento en caché

Obtener Últimas Copias de Seguridad - `/api/lastbackups/:serverId`

Punto final: /api/lastbackups/:serverId
Método: GET
Descripción: Recupera la información de las últimas copias de seguridad para todas las copias de seguridad configuradas (por ejemplo, 'Archivos', 'Bases de Datos') en un servidor específico.
Parámetros:
- serverId: el identificador del servidor (ID o nombre)

nota

El identificador del servidor debe estar codificado en URL.

Respuesta:

{
  "server": {
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Default Backup",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backups": [
    {
      "id": "backup1",
      "server_id": "unique-server-id",
      "name": "Files",
      "date": "2024-03-20T10:00:00Z",
      "status": "Success",
      "warnings": 0,
      "errors": 0,
      "messages": 150,
      "fileCount": 249426,
      "fileSize": 113395849938,
      "uploadedSize": 331318892,
      "duration": "00:38:31",
      "duration_seconds": 2311.6018052,
      "durationInMinutes": 38.52669675333333,
      "knownFileSize": 27203688543,
      "backup_list_count": 10,
      "messages_array": "[\"message1\", \"message2\"]",
      "warnings_array": "[\"warning1\"]",
      "errors_array": "[]",
      "available_backups": ["v1", "v2", "v3"]
    },
    {
      "id": "backup2",
      "server_id": "unique-server-id",
      "name": "Databases",
      "date": "2024-03-20T11:00:00Z",
      "status": "Success",
      "warnings": 1,
      "errors": 0,
      "messages": 75,
      "fileCount": 125000,
      "fileSize": 56789012345,
      "uploadedSize": 123456789,
      "duration": "00:25:15",
      "duration_seconds": 1515.1234567,
      "durationInMinutes": 25.25205761166667,
      "knownFileSize": 12345678901,
      "backup_list_count": 5,
      "messages_array": ["message1"],
      "warnings_array": ["warning1"],
      "errors_array": [],
      "available_backups": ["v1", "v2"]
    }
  ],
  "backup_jobs_count": 2,
  "backup_names": ["Files", "Databases"],
  "status": 200
}

Respuestas de Error:
- 401: Clave de API faltante o inválida cuando se requieren claves
- 403: El ámbito de la clave no es read, o la IP del cliente no está en la lista externa permitida
- 404: Servidor no encontrado
- 429: Límite de tasa de API de lectura excedido
- 500: Error interno del servidor
Notas:
- En la versión 0.7.x, la clave del objeto de respuesta cambió de machine a server, y el campo backup_types_count fue renombrado a backup_jobs_count
- El identificador del servidor puede ser ya sea ID o nombre
- Devuelve la última copia de seguridad para cada trabajo de copia de seguridad (backup_name) que tiene el servidor
- A diferencia de /api/lastbackup/:serverId que devuelve solo la copia de seguridad más reciente del servidor (independientemente del trabajo de copia de seguridad)
- Incluye encabezados de control de caché para evitar el almacenamiento en caché

Subir Datos de Copia de Seguridad - `/api/upload`

Punto final: /api/upload
Método: POST
Descripción: Sube datos de operación de copia de seguridad para un servidor. Soporta detección de ejecución de copia de seguridad duplicada y envía notificaciones.

Cuerpo de Solicitud: JSON enviado por duplicati con las siguientes opciones:

--send-http-json-urls=http://my.local.server:9666/api/upload?api_key=YOUR_UPLOAD_KEY
--send-http-log-level=Information
--send-http-max-log-lines=500

En Duplicati anterior a 2.0.9.106, utiliza `--send-http-url` con `--send-http-result-output-format=Json`. Consulta [Configuración del Servidor Duplicati](../installation/duplicati-server-configuration.md).

- **Respuesta**:

  ```json
  {
    "success": true
  }

Respuestas de Error:
- 400: Faltan campos requeridos en las secciones Extra o Data, o MainOperation no válido
- 401: Clave API faltante o no válida cuando se requieren claves
- 403: El ámbito de la clave no es upload, o la IP del cliente no está en la lista de permitidos externa
- 409: Datos de copia de seguridad duplicados (ignorados)
- 413: El cuerpo de la solicitud excede el límite de tamaño de subida configurado (predeterminado 5 MB)
- 429: Se ha superado el límite de tasa de fallo de subida o autenticación (Retry-After está configurado)
- 500: Error del servidor al procesar los datos de copia de seguridad
Notas:
- Solo procesa operaciones de copia de seguridad (MainOperation debe ser "Copia de seguridad")
- Valida los campos requeridos en la sección Extra: machine-id, machine-name, backup-name, backup-id
- Valida los campos requeridos en la sección Data: ParsedResult, BeginTime, Duración
- Detecta automáticamente ejecuciones de copia de seguridad duplicadas y devuelve un estado 409
- Envía notificaciones después de la inserción exitosa de la copia de seguridad (si está configurado)
- Registra los datos de la solicitud en un archivo en el directorio data en la raíz del proyecto en modo de desarrollo para depuración
- Utiliza transacciones para la consistencia de los datos

Obtener Resumen General - /api/summary​

Obtener Última Copia de Seguridad - /api/lastbackup/:serverId​

Obtener Últimas Copias de Seguridad - /api/lastbackups/:serverId​

Subir Datos de Copia de Seguridad - /api/upload​

Obtener Resumen General - `/api/summary`

Obtener Última Copia de Seguridad - `/api/lastbackup/:serverId`

Obtener Últimas Copias de Seguridad - `/api/lastbackups/:serverId`

Subir Datos de Copia de Seguridad - `/api/upload`