# Integración server-side | Docs de AudioDN

> Usa la API de AudioDN directamente desde tu servidor para máximo control sobre subidas, reproducción y gestión de acceso.

Source: https://audiodeliverynetwork.com/es/docs/integration/server-side/

---

# Integración server-side

Usa la API de ADN directamente para almacenar pistas y gestionar la reproducción. Crea experiencias totalmente personalizadas sin componentes de ADN.

#### Ideal para

Plataformas a medida, enterprise y equipos que necesitan control total de la API. La configuración tarda 1-2 horas.

## Reproducir pistas

Crea sesiones de reproducción y obtén URLs de pista desde tu servidor.

Usa la API de ADN directamente desde tu servidor para crear sesiones de reproducción y obtener URLs de pista. Crea experiencias de reproducción totalmente personalizadas — sin componentes web de ADN.

### 1\. Crear una clave API

Ve a **Settings → API Keys** y crea una clave **API Access**.

### 2\. Crear una sesión de reproducción

```
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({
    collection_id,
    variants: ['preview'],
    is_downloadable: false,
    expires_in: 3600 // session duration in seconds (default: 3600, min: 60, max: 86400)
  })
});

const { play_session_id, tracks } = await response.json();
```

Aquí es donde aplicas la lógica de negocio — comprobar suscripciones, verificar compras o aplicar reglas de acceso antes de crear la sesión.

### 3\. Obtener datos de la pista

```
const { id: track_id } = tracks[0];

// No auth needed - the session ID acts as a bearer token
const response = await fetch(`https://api.audiodelivery.net/v1/play/${play_session_id}/${track_id}`);

const { variants } = await response.json();
const preview = variants.find(v => v.variant.index === 'preview');
console.log(`Play Audio File: ${preview.url}`);
```

### 4\. Reproducción personalizada

Usa la URL devuelta en tu propia implementación de reproductor de audio. Funciona con cualquier librería de player o APIs de audio nativas de móvil.

#### Datos de forma de onda

ADN genera automáticamente datos de forma de onda RMS normalizados (320 muestras) para cada pista. El campo `levels` en la respuesta de la pista contiene los datos — úsalos para renderizar formas de onda en tu propio player, o genera formas de onda personalizadas mediante el tipo de variante Audio Analysis.

#### Imágenes de portada y colores de tema

ADN analiza cada pista subida en busca de arte de portada incrustado y lo pone disponible como `cover_image` en la respuesta de la pista (en tamaños icon/small/regular/large). También puedes subir una imagen de portada por separado vía la API. Cuando hay una imagen de portada, ADN extrae una paleta de colores y selecciona un `player_color` principal — úsalos para estilizar la UI de tu player. Junto a él, las respuestas incluyen `player_color_light` y `player_color_dark`, variantes ajustadas por contraste para dibujar el color sobre fondos claros y oscuros respectivamente. El array completo `theme` contiene todos los colores extraídos con valores hex, área, luminosidad y saturación.

#### ¿Pistas públicas? Omite la sesión

Para pistas disponibles públicamente, puedes firmar URLs de entrega en tu propio servidor con una clave URL Signing y omitir por completo las sesiones de reproducción — sin round trip a la API por oyente. Consulta la vía rápida de [Signed Delivery](/docs/integration/signed-delivery) y la [Signing Keys API](/docs/api/signing-keys).

## Subir pistas

Usa la API de ADN para gestionar todo el flujo de subida desde tu servidor.

Usa la API de ADN directamente desde tu servidor para crear sesiones de subida, almacenar pistas y gestionar todo el flujo de subida. Crea interfaces de subida totalmente personalizadas — sin componentes web de ADN.

### 1\. Crear una clave API

Ve a **Settings → API Keys** y crea una clave **API Access**.

### 2\. Crear una sesión de subida

```
const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_id: 'COLLECTION-ID',
    expires_in: 3600 // session duration in seconds (default: 3600, min: 60, max: 86400)
    // Optional: add track: { file_name: 'song.wav' } to also create a track and get track_upload.upload_url
  })
});

const { upload_session } = await response.json();
```

### 3\. Crear pistas dentro de la sesión

```
const { id: upload_session_id } = upload_session;

// One request per file. No Authorization header needed here — the
// upload session ID authorizes track creation.
const response = await fetch(`https://api.audiodelivery.net/v1/upload/${upload_session_id}/track`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ file_name: 'song.wav' })
});

const { track_id, track_upload } = await response.json();
const { method, upload_url, expires_at } = track_upload;
```

### 4\. Subir archivos

```
const file = document.querySelector('input[type="file"]').files[0];

await fetch(upload_url, {
  method,
  headers: { 'Content-Type': file.type },
  body: file
});
```

Repite los pasos 3 y 4 por cada archivo que quieras añadir a la sesión — cada pista necesita su propia solicitud `POST /v1/upload/:upload_session_id/track` y su propia URL de subida firmada. También puedes incluir un objeto anidado `track` en `POST /v1/upload_session` para crear la primera pista de antemano, y luego usar el paso 3 para cualquier archivo adicional.

### 5\. Esperar a que la pista esté lista

El procesamiento comienza automáticamente una vez que el archivo llega al almacenamiento. Espera hasta que el estado de la pista sea `ready` antes de crear una sesión de reproducción o firmar URLs de entrega — ya sea haciendo polling o con un webhook.

```
// Processing runs automatically after the upload. Poll the track until it is
// ready, or configure a webhook (below) to be notified instead of polling.
let track;
do {
  await new Promise((r) => setTimeout(r, 5000));
  const res = await fetch(`https://api.audiodelivery.net/v1/track/${track_id}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  ({ track } = await res.json());
} while (track.track_status_id !== 'ready');

// The track is now ready — create a play session or sign a delivery URL.
```

### 6\. Opcional: Webhooks

En lugar de hacer polling, habilita un webhook en **Settings → Webhook** para recibir notificaciones cuando una pista alcanza un resultado terminal (`ready`, `incomplete`, `error` o `init_error`) y cuando su conjunto completo de archivos está listo. Consulta la documentación del [webhook Track Processing](/docs/webhooks/track-processing).

#### Imágenes de portada

ADN analiza automáticamente las pistas subidas en busca de arte de portada incrustado. También puedes subir una imagen de portada por separado vía la Covers API. Cuando hay una imagen, ADN extrae colores (disponibles como `theme`) que se pueden usar para estilizar la UI de tu player.

## Generar claves

Genera claves Client-Side con alcance desde tu servidor.

Una vez que tienes una clave **API Access**, puedes generar claves `player` y `uploader` de forma programática — por ejemplo, una clave de player por cliente con alcance a una sola colección. Las claves **Inline Share** y **URL Signing** no se crean a través de la API; aprovisiónalas desde **Settings → API Keys** en el panel. Consulta la referencia de [API Keys](/docs/api/api-keys) para todos los parámetros.

### Crear una clave con alcance

```
// Use your API Access key to mint a scoped Client-Side Player key.
const response = await fetch('https://api.audiodelivery.net/v1/api_key', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Customer Player Key',
    api_key_type_id: 'player',   // 'player' | 'uploader' (share & signing keys are dashboard-only)
    collection_id: 'COLLECTION_ID' // optional: limit the key to one collection
    // expires_at is optional via the API — omit for a key that never expires
  })
});

// The full key is returned once — store it securely, it cannot be retrieved again.
const { api_key } = await response.json();
```

Vía la API, `expires_at` es opcional para ambos tipos de clave — omítelo para una clave que no caduque por tiempo. Las claves API Access, Inline Share y URL Signing deben crearse en el panel.