# Inicio rápido

Ad Center entrega los banners publicitarios de vzla.io a aplicaciones de terceros. Solicitas los anuncios activos y los muestras en tu propio diseño.

1. **Solicita un token de API**

   Los tokens de Ad Center son emitidos por vzla.io. Para obtener acceso a la API de Ad Center, contacta a vzla.io.

   Los tokens tienen este formato:

   ```
   vzlaio_a1b2c3d4e5f6...
   ```

2. **Realiza tu primera solicitud**

   Envía el token en el encabezado `Authorization`:

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

3. **Lee la respuesta**

   Una respuesta exitosa envuelve los datos en el envelope `{data, meta}`:

   ```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"
       }
     ],
     "meta": {
       "count": 1
     }
   }
   ```

## Autenticación

Toda solicitud (excepto [Mi Cuota](/es/adcenter/v1/me/quota)) debe incluir:

```http
Authorization: Bearer vzlaio_TU_TOKEN_AQUI
```

Las solicitudes sin un token válido devuelven `401 Unauthorized`.

## Cuota

Las cuotas se reinician el **primer día de cada mes calendario**. Cuando superas tu límite mensual, la API devuelve `429 Too Many Requests`. Consulta tu uso cuando quieras con [`/me/quota/`](/es/adcenter/v1/me/quota), que es gratuito y no consume cuota.

Las solicitudes también tienen un límite de **1000 por hora** por token.

## Endpoints

| Endpoint | Qué devuelve | Caché |
|---|---|---|
| [`GET /api/adcenter/v1/ads/`](/es/adcenter/v1/ads) | Banners que se están mostrando actualmente | 5 min |
| [`GET /api/adcenter/v1/me/quota/`](/es/adcenter/v1/me/quota) | Estado actual de tu cuota (gratis, no consume cuota) | — |

## Formato de errores

Todos los errores siguen un envelope estándar:

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

| Código de error | Estado HTTP | Significado |
|---|---|---|
| `auth_missing` | 401 | No se envió el encabezado `Authorization` |
| `auth_token_unknown` | 401 | Token no encontrado, inactivo o mal formado |
| `product_forbidden` | 403 | El token es válido pero fue emitido para otra API de vzla.io |
| `quota_exceeded` | 429 | Se alcanzó el límite mensual |
**Note:** Los tokens de Ad Center son distintos a los de Quantis. Un token emitido para Quantis devuelve `403 product_forbidden` aquí, y un token de Ad Center no autentica contra los endpoints de Quantis.