# Anuncios

## GET /api/adcenter/v1/ads/

Devuelve todos los banners que se están mostrando actualmente, en el orden previsto de presentación — el primero de la lista va primero.

| | |
|---|---|
| **Método** | `GET` |
| **URL** | `https://app.vzla.io/api/adcenter/v1/ads/` |
| **Autenticación** | `Authorization: Bearer vzlaio_...` |
| **Parámetros** | Ninguno |

### Solicitud

```bash
curl --request GET \
  --url 'https://app.vzla.io/api/adcenter/v1/ads/' \
  --header 'Authorization: Bearer vzlaio_TU_TOKEN_AQUI'
```

### Respuesta

#### `data`

Un arreglo de objetos de anuncio. Vacío cuando no hay anuncios activos.

| Campo | Tipo | Descripción |
|---|---|---|
| `ad_id` | string (UUID) | Identificador público estable del anuncio. Úsalo para deduplicar y atribuir clics |
| `title` | string | Titular del banner. Siempre presente |
| `link` | string (URL) | Destino a abrir cuando se toca el banner. Siempre presente |
| `description` | string o null | Línea de apoyo opcional. Muestra el anuncio sin ella cuando sea `null` |
| `expires_at` | string (fecha-hora ISO 8601) o null | Cuándo deja de mostrarse el anuncio. `null` significa que no expira |

#### `meta`

| Campo | Tipo | Descripción |
|---|---|---|
| `count` | integer | Cantidad de anuncios en `data` |

### Respuesta de ejemplo

```json
{
  "data": [
    {
      "ad_id": "5edce7fa-0109-49a7-8aff-0e5eb27e9560",
      "title": "⚽ ¿Cuánto sabes realmente de fútbol?",
      "link": "https://futbble.com/descargar",
      "description": null,
      "expires_at": "2026-09-21T12:00:20-04:00"
    },
    {
      "ad_id": "daa03fb6-9647-4ce6-ba53-f1700177fe92",
      "title": "DressDocs",
      "link": "https://futbble.com/#descargar",
      "description": "No dejes que tus documentos salgan mostrando picon.",
      "expires_at": "2026-09-22T12:20:14-04:00"
    }
  ],
  "meta": {
    "count": 2
  }
}
```

### Códigos de estado HTTP

| Código | Significado |
|---|---|
| `200 OK` | Éxito. |
| `401 Unauthorized` | Token faltante o inválido. |
| `403 Forbidden` | El token fue emitido para otra API de vzla.io. |
| `405 Method Not Allowed` | Solo se admite GET. |
| `429 Too Many Requests` | Cuota mensual agotada, o límite por hora alcanzado. |
| `500 Internal Server Error` | Error del servidor. Reintenta tras una breve pausa. |

#### 401 — sin encabezado Authorization

```json
{
  "error": {
    "code": "auth_missing",
    "message": "Authentication credentials were not provided"
  }
}
```

#### 401 — token inválido

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid token format"
  }
}
```

#### 403 — el token pertenece a otra API

```json
{
  "error": {
    "code": "product_forbidden",
    "message": "This token is not valid for this API"
  }
}
```

#### 429

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exceeded. Limit: 1000 requests/month"
  }
}
```
**Note:** Este endpoint tiene caché de **5 minutos**. Un anuncio desactivado o que pase su `expires_at` puede tardar ese tiempo en desaparecer de la respuesta.
**Tip:** Respeta `expires_at` también de tu lado. Si guardas los anuncios en caché por más de 5 minutos, descarta cualquier anuncio cuyo `expires_at` ya haya pasado antes de mostrarlo.