Límites de uso

Quién puede usar la API, cuántas peticiones entran por minuto y al mes, y qué pasa cuando te pasas.

Quién tiene acceso

La API REST está en todos los planes. Cualquier cuenta con un plan vivo —Lite, Standard, Advanced o Premium— puede generar sus claves y empezar a integrar; lo que cambia entre planes es el ritmo, no el acceso.

La única excepción es el servidor MCP: conectar un asistente de IA a tu cuenta requiere el extra de IA contratado (Tier 1 o superior). Son las mismas claves; lo que cambia es quién puede usar esa puerta.

La comprobación de plan se hace en cada petición, no solo al generar la clave: si una cuenta se queda sin plan, sus claves dejan de funcionar en ese momento y la API responde 403. No hace falta revocar nada a mano.

{
  "errorCode": 403,
  "errorMsg": "This account does not have an active plan with API access. Current plan: unknown.",
  "data": null
}

Cuánto puedes pedir

Hay dos ventanas: por minuto, que protege de las ráfagas, y llamadas al mes, que es la cuota del plan. La cuota mensual está dimensionada para el volumen de facturación que cubre cada plan, con margen para el trabajo de integración habitual: sincronizar contactos, leer el catálogo, sacar informes.

Los límites son por cuenta, no por clave: repartir el tráfico entre varias claves no da más cupo. Las claves activas son las que puedes tener a la vez; revocar una libera su hueco al momento, y rotar una clave no consume cupo porque no crea ninguna nueva.

Las llamadas del servidor MCP salen de la misma bolsa: un asistente conectado consume la cuota de la cuenta igual que tu integración.

El contador mensual se reinicia el día 1 (hora del servidor) y el de minuto, al empezar cada minuto de reloj. En tu cuenta los ves en Configuración → Integraciones → API de Afer.

Cabeceras de cada respuesta

No hace falta que esperes al error para saber cómo vas: todas las respuestas traen el estado del límite que esté más cerca de agotarse.

Cuando te pasas

La API responde 429 con el envelope de siempre y la cabecera Retry-After. La petición no se ejecuta: nada se crea ni se modifica, así que reintentar es seguro.

{
  "errorCode": 429,
  "errorMsg": "Rate limit exceeded: 120 requests per minute on the standard plan. Retry after 23 seconds.",
  "data": null
}

Cómo no llegar al límite

• Reintenta con espera creciente. Ante un 429, espera lo que diga Retry-After y dobla la espera en cada reintento. Machacar la API con reintentos inmediatos solo alarga el bloqueo.
• Pide páginas grandes. Una llamada con por_pagina: 500 gasta lo mismo que una de 10 resultados. Bajar la paginación multiplica las peticiones sin traer más datos.
• Usa los agregados. consultarResumen trae en una llamada lo que si no son ocho; los agrupar de ventas, compras y resultado evitan recorrer documento a documento.
• Cachea los catálogos. métodos de pago, series, estados, familias o funnels cambian muy de vez en cuando: cárgalos una vez y guárdalos.
• Acota por fechas. Sincroniza solo lo que ha cambiado desde tu última pasada en lugar de releer el histórico entero.