Límites de uso y cuotas para la API de SmartPyme

La API externa de SmartPyme aplica límites de uso por hora para garantizar el uso justo y la estabilidad de la plataforma. Tu cuota depende de si incluyes filtros de fecha en tus solicitudes: agregar fecha_inicio y fecha_fin duplica tu permiso. Entender cómo funcionan los límites te ayuda a diseñar integraciones que se mantengan cómodamente dentro de la cuota.

Límites

Tipo de solicitud	Límite
Sin filtros de fecha	1.000 solicitudes/hora
Con `fecha_inicio` + `fecha_fin`	2.000 solicitudes/hora

Ventana de reinicio

Los límites de uso operan en ventanas horarias fijas. El contador se reinicia exactamente al comienzo de cada hora; por ejemplo, a las 14:00, 15:00, 16:00, y así sucesivamente. Las solicitudes hechas entre las 14:00 y las 14:59 cuentan todas dentro de la misma ventana, y el contador comienza nuevamente a las 15:00, sin importar cuándo hiciste tu primera solicitud durante esa hora.

Encabezados de límite de uso

Cada respuesta de la API incluye los siguientes encabezados para que puedas rastrear tu uso actual en tiempo real:

Encabezado	Descripción
`X-RateLimit-Limit`	Tu límite actual para esta ventana
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana actual
`X-RateLimit-Reset`	Marca de tiempo Unix de cuándo se reinicia el límite

Cómo consultar tu estado

Puedes consultar tu estado actual de límite de uso en cualquier momento llamando a GET /system/rate-limit. Este endpoint cuenta dentro de tu cuota, pero devuelve un panorama completo de tu uso para la ventana actual.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.smartpyme.site/api/external/v1/system/rate-limit"

{
  "success": true,
  "data": {
    "requests_used": 25,
    "max_requests": 1000,
    "remaining_requests": 975,
    "reset_time": "2024-01-01T15:00:01Z",
    "window_minutes": 60,
    "limits": {
      "standard": 1000,
      "with_date_filters": 2000
    },
    "current_limit_type": "standard",
    "empresa_nombre": "Mi Empresa"
  }
}

Manejo del HTTP 429

Cuando excedes tu límite de uso, la API devuelve HTTP 429 Too Many Requests. Para recuperarte y evitar alcanzar el límite nuevamente, sigue estas recomendaciones:

Revisa el encabezado X-RateLimit-Reset para determinar exactamente cuándo se renueva tu cuota, luego espera hasta esa marca de tiempo antes de reintentar.
Agrega los filtros de fecha fecha_inicio y fecha_fin a tus solicitudes: esto duplica tu cuota por hora a 2.000 solicitudes.
Usa per_page=200 para obtener más registros por solicitud y reducir la cantidad total de llamadas que hace tu integración.
Usa endpoints de resumen (por ejemplo, GET /sales/summary) para obtener datos agregados en lugar de paginar a través de todos los registros individuales.

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": 429
}

Agrega siempre fecha_inicio y fecha_fin a tus solicitudes: duplica tu cuota por hora a 2.000 y suele reducir la cantidad total de solicitudes necesarias al acotar los resultados a un rango de tiempo específico.

Visión general

Endpoints

Límites de uso y cuotas para la API de SmartPyme

Límites

Ventana de reinicio

Encabezados de límite de uso

Cómo consultar tu estado

Manejo del HTTP 429

​Límites

​Ventana de reinicio

​Encabezados de límite de uso

​Cómo consultar tu estado

​Manejo del HTTP 429

Límites

Ventana de reinicio

Encabezados de límite de uso

Cómo consultar tu estado

Manejo del HTTP 429