VerikoDocs

Escribe para buscar. Enter abre el primer resultado.

EN

Rastrear cuota de API y consumo del ciclo de facturación

Objetivo

Entiende cuántas validaciones has consumido en el ciclo de facturación actual, dónde estás en relación al límite mensual de tu plan, qué operaciones representan la mayor parte del consumo y cómo han cambiado los patrones de uso con el tiempo. Usa estas señales para planificar eventos de escalado y para construir alertas de uso en tu propio stack de monitoreo.

Requisitos previos

  • Una API key activa (veriko_…). No se requiere permiso adicional más allá de la autenticación para los endpoints de uso.

Pasos

1. Verificar el snapshot de cuota del ciclo actual

GET /v1/usage/summary devuelve el límite mensual de tu plan, validaciones consumidas, validaciones restantes y un indicador tone preclasificado (ok, warn, danger).

curl 'https://api.veriko.mx/v1/usage/summary' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": {
    "type": "usage_summary",
    "attributes": {
      "limit": 5000,
      "used": 2100,
      "remaining": 2900,
      "used_percent": 42.0,
      "tone": "ok",
      "resets_at": "2025-05-01T00:00:00Z",
      "quota_kind": "cycle",
      "renews": true
    }
  }
}

Umbrales del tone:

toneSignificado
okPor debajo del 70% consumido.
warn70–89% consumido.
danger90%+ consumido, o cuota en cero.

quota_kind y renews. Una cuenta que aún no reclama el plan gratuito consume, mientras dure, una cuota de prueba independiente del ciclo de suscripción: quota_kind: "trial" lo señala, y renews: false avisa que resets_at marca el fin de un periodo técnico, no la promesa de una recarga — agotada la prueba, no llegan más unidades hasta reclamar el plan. Con quota_kind: "cycle" (el caso de siempre) renews es true: el ciclo de facturación sí repone la cuota. Los dos campos son aditivos — un cliente que no los lea sigue funcionando igual — y aparecen también en meta.quota de GET /v1/billing/subscription.

Si la cuota de prueba se agota, cualquier endpoint que valide responde 429 con meta.plan_unclaimed: true: no es un límite que se reinicie solo, es una cuenta que todavía no reclama su plan y por lo tanto no tiene nada más que consumir.

2. Obtener contadores crudos de uso de API

GET /v1/api/usage proporciona un snapshot más amplio que incluye peticiones de hoy, peticiones del mes, cuota del plan y el estado actual del servicio Banxico.

curl 'https://api.veriko.mx/v1/api/usage' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": {
    "type": "api_usage",
    "attributes": {
      "requests_today": 42,
      "requests_month": 580,
      "quota": {
        "plan_slug": "basic",
        "limit": 1000,
        "used": 420,
        "remaining": 580,
        "resets_at": "2025-04-01T00:00:00Z"
      }
    }
  }
}

3. Verificar límites de tasa

El plan aplica límites por minuto, además de la cuota mensual: peticiones por clave en la API y entregas de webhook por host destino. Consulta los límites configurados con:

curl 'https://api.veriko.mx/v1/usage/limits' \
  -H 'Authorization: Bearer veriko_••••'

La respuesta devuelve rate_limits.api.key_per_minute y rate_limits.webhooks.host_per_minute, que fija el plan, junto con el techo por IP y el tope global por host, de forma separada del conteo de cuota mensual. El consumo de la ventana en curso lo informan las cabeceras X-RateLimit-* de cada respuesta de la API (límites de tasa).

4. Inspeccionar el desglose por operación

Ve qué endpoints consumen más cuota en el ciclo actual:

curl 'https://api.veriko.mx/v1/usage/breakdown' \
  -H 'Authorization: Bearer veriko_••••'

5. Ver tendencias históricas de uso

GET /v1/usage/history devuelve datos de uso agrupados por tiempo. Combínalo con el endpoint de tendencias de insights para análisis de series temporales más enriquecidos.

curl 'https://api.veriko.mx/v1/usage/history' \
  -H 'Authorization: Bearer veriko_••••'

6. Ver el mapa de calor de uso

GET /v1/usage/heatmap muestra la densidad de actividad por hora del día y día de la semana — útil para entender las ventanas de uso pico.

curl 'https://api.veriko.mx/v1/usage/heatmap' \
  -H 'Authorization: Bearer veriko_••••'

7. Exportar datos de uso

Descarga datos de uso crudos como CSV o XLSX para ingestión en tu pipeline de analítica:

curl 'https://api.veriko.mx/v1/api/usage/export?format=csv' \
  -H 'Authorization: Bearer veriko_••••' \
  --output exportacion-uso.csv

Siguientes pasos