# Resumen de la API | Docs de AudioDN

> URL base, autenticación, formato de solicitud y manejo de errores de la API de AudioDN.

Source: https://audiodeliverynetwork.com/es/docs/api/

---

# Resumen de la API

Todo lo que necesitas saber antes de hacer tu primera solicitud a la API.

## URL base

Todos los endpoints de la API llevan el prefijo `/v1/`. Usa la siguiente URL base para todas las solicitudes:

```
https://api.audiodelivery.net/v1/
```

## Autenticación

La mayoría de las solicitudes a la API requieren autenticación mediante un token Bearer en la cabecera `Authorization`. Si usas los componentes web de ADN con una clave API Client-Side, los componentes gestionan la autenticación automáticamente — esta sección se aplica a las solicitudes directas a la API.

```
Authorization: Bearer your_api_key_here
```

Algunos endpoints de subida y reproducción se autorizan con un ID de sesión en la URL en lugar de un token Bearer, y no llevan cabecera `Authorization`: `GET /v1/upload_session/:upload_session_id`, `POST /v1/upload/:upload_session_id/track` y `GET /v1/play/:play_session_id/:play_track_id`. Cada uno se indica en su referencia de endpoint.

### Tipos de clave API

| Tipo de clave | Caso de uso | Seguridad |
| --- | --- | --- |
| API Access | Solicitudes de servidor a servidor — crear sesiones, gestionar pistas, configurar variantes | Mantenla en secreto. Nunca la expongas en código del cliente. |
| Client-Side | Componentes web y apps móviles — reproducir audio, subir archivos | Segura para incluir en código front-end. Limitada solo a operaciones de reproducción y subida. |
| Inline Share | Enlaces de compartir públicos — redirigen directamente a una sola variante de pista sin cabecera Authorization | La clave está en la URL. Cualquiera con el enlace puede reproducir hasta que caduque o se elimine. Se crea en el panel. Ver [Inline Share](/docs/api/share). |
| URL Signing | Firmar URLs de entrega en tu propio servidor para pistas públicas — sin sesión de reproducción ni cabecera Authorization | El secreto de firma permanece en el servidor. Se crea en el panel. Ver [Signing Keys](/docs/api/signing-keys). |

#### Crear claves API

Crea tu primera clave **API Access** desde la página de **Settings** en el [panel de AudioDN](https://account.audiodeliverynetwork.com). Con esa clave puedes generar después claves **Client-Side** (player y uploader) de servidor a servidor vía [POST /v1/api\_key](/docs/api/api-keys). Las claves **Inline Share** y **URL Signing** no se gestionan a través de la API — créalas desde **Settings → API Keys** en el panel.

## Formato de solicitud

Todos los cuerpos de solicitud y respuesta usan JSON. Incluye la cabecera `Authorization` en cada solicitud autenticada (ver las excepciones anteriores) y establece `Content-Type: application/json` al enviar un cuerpo de solicitud. Aquí un ejemplo creando una sesión de reproducción en todas las plataformas:

#### Ejemplo de solicitud

    

```
curl -X POST "https://api.audiodelivery.net/v1/play_session/collection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}'
```

```
const payload = {
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
};

const response = await fetch('https://api.audiodelivery.net/v1/play_session/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/collection")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/collection")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/play_session/collection"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

## Respuestas

Las respuestas correctas incluyen `“ok”: true` junto con los datos solicitados. Los errores devuelven `“ok”: false` con un mensaje y un ID de solicitud único para depuración:

### Éxito

```
{
"ok": true,
...
}
```

### Error

```
{
"ok": false,
"message": "Description of what went wrong",
"api_request_id": "uuid"
}
```

### Códigos de estado HTTP

| Código | Significado |
| --- | --- |
| 200 | Éxito |
| 400 | Solicitud incorrecta — revisa el cuerpo o los parámetros de la solicitud |
| 401 | No autorizado — clave API ausente o no válida |
| 403 | Prohibido — la clave API no tiene permiso para esta operación |
| 404 | No encontrado — el recurso no existe o no es accesible |
| 410 | Gone — la sesión ha caducado |
| 500 | Error interno del servidor — reintenta o contacta con soporte |

## Paginación

Los endpoints de listado devuelven todos los registros coincidentes. Para colecciones grandes, filtra por `collection_id` o `creator_id` para acotar los resultados.

## IDs y formatos

Todos los IDs de recurso son UUIDs (p. ej. `04ea3a34-a0f7-45e8-a711-9c7274490e2e`). Las marcas de tiempo se devuelven como cadenas ISO 8601 en UTC.