# Inicio rápido

Quantis v2 es una superficie de API más rica para datos de tasas de cambio venezolanas. Usa tokens separados a los de v1, un nuevo envelope de respuesta y endpoints dedicados por fuente de datos.

1. **Crea tu token de API**

   Abre la aplicación móvil de vzla.io, ve a **Ajustes → API → Generar token**. Cópialo de inmediato — el token en texto plano solo se muestra una vez.

   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/quantis/v2/rates/bcv/' \
     --header 'Authorization: Bearer vzlaio_TU_TOKEN_AQUI'
   ```

3. **Lee la respuesta**

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

   ```json
   {
     "data": {
       "current": {
         "valid_date": "2026-05-06",
         "timestamp": "2026-05-06T09:32:03.108501+00:00",
         "rates": {
           "USD": {
             "rate": "493.37650000",
             "indicator_pct": "0.78066864",
             "indicator_amount": "3.82180000"
           },
           "EUR": { "...": "..." }
         }
       },
       "next": null
     },
     "meta": {
       "source": "BCV",
       "currency_quote": "VES"
     }
   }
   ```

## Autenticación

Cada solicitud (excepto [Mi Cuota](/es/quantis/v2/me/quota)) debe incluir:

```http
Authorization: Bearer vzlaio_TU_TOKEN_AQUI
```

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

## Encabezados de cuota

Cada respuesta incluye estos encabezados para que puedas monitorear tu uso sin llamar a `/me/quota/`:

| Encabezado | Descripción |
|---|---|
| `X-Quota-Limit` | Tu límite mensual de solicitudes |
| `X-Quota-Remaining` | Solicitudes restantes este mes |
| `X-Quota-Reset` | Timestamp ISO 8601 del próximo reinicio de cuota |
| `X-Request-ID` | UUID de esta solicitud — inclúyelo al contactar soporte |

Las cuotas se reinician el **primer día de cada mes calendario**. Al superar tu límite la API devuelve `429 Too Many Requests`.

## Endpoints

| Endpoint | Qué devuelve | Caché |
|---|---|---|
| [`GET /api/quantis/v2/rates/bcv/`](/es/quantis/v2/rates/bcv) | Tasas BCV oficiales (USD, EUR, CNY, TRY, RUB) | 60 min |
| [`GET /api/quantis/v2/rates/markets/`](/es/quantis/v2/rates/markets) | Tasa USDT Binance + AVG + DIFF vs BCV | 5 min |
| [`GET /api/quantis/v2/rates/banks/`](/es/quantis/v2/rates/banks) | Tasas compra/venta/promedio por banco | 30 min |
| [`GET /api/quantis/v2/rates/international/`](/es/quantis/v2/rates/international) | ~170 monedas internacionales (base USD) | 30 min |
| [`GET /api/quantis/v2/rates/crypto/`](/es/quantis/v2/rates/crypto) | Precios en USD de BTC, ETH, USDT y más | 5 min |
| [`GET /api/quantis/v2/holidays/`](/es/quantis/v2/holidays) | Feriados bancarios y nacionales venezolanos | 24 h |
| [`GET /api/quantis/v2/me/quota/`](/es/quantis/v2/me/quota) | Tu estado de cuota actual (gratis, sin consumo) | — |

## Formato de errores

Todos los errores siguen un envelope estándar:

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid or inactive token.",
    "details": {}
  }
}
```

| Código de error | Estado HTTP | Significado |
|---|---|---|
| `auth_missing` | 401 | No se envió el encabezado `Authorization` |
| `auth_token_unknown` | 401 | Token no encontrado o inactivo |
| `quota_exceeded` | 429 | Límite mensual alcanzado |
**Note:** Los tokens v2 son independientes de los tokens v1. Un token `gtbe_...` no autenticará contra los endpoints v2.