Tu integración por API

Límites

Límites de petición, cola de sincronizaciones y cupo de llamadas por conexión, con qué hacer ante cada rechazo.

Emisso tiene pocos límites, y esta página los junta todos. Los números que leas aquí salen del código que los aplica; cuando un tope depende del plan y no de una constante, la prosa lo dice y el valor vigente está en el dashboard, en connect.emisso.ai/billing.

Límites de petición

Cuerpo de la petición: 256 KB. Aplica a toda la superficie (/v1/tools/{id}/execute y las rutas de control). Se valida el Content-Length declarado y además se lee el cuerpo con tope, así que un header mentiroso no lo evade. Al excederlo la respuesta es 413 payload_too_large.

Emisión de enlaces de conexión: 60 por hora por organización. Es el tope de POST /v1/connect_sessions, el que acota la emisión masiva de páginas con la marca de Emisso. Pasado el tope, la respuesta es 429 rate_limited con un header Retry-After en segundos.

Carril agente: 5 enlaces por hora por actor. La tool conexiones.enlace.crear tiene un tope propio encima del de organización. Una conversación real necesita uno a tres enlaces; el tope deja margen para un reintento y acota lo que puede emitir un agente con el prompt comprometido.

Sincronizaciones

El sistema externo (el portal del SII, el banco) es el recurso escaso, y los topes de esta sección existen para no quemarlo:

  • Candado por conexión. Cada conexión admite una sola operación contra su sistema a la vez. Si el candado está tomado, la respuesta es 409 connection_busy; es reintentable y el candado se suelta solo.
  • Capacidad compartida de operaciones externas. No es un cupo de simultaneidad por organización. Si está ocupada, una operación puede responder 409 connection_busy; los trabajos en cola se difieren automáticamente. La capacidad operativa puede cambiar: no la uses para calcular un plazo de término.
  • Un trabajo activo por conexión y período. Por POST /v1/connections/{conn}/syncs, encolar un período que ya tiene un trabajo en cola o corriendo devuelve 409 connection_sync_in_progress; la tool conexion.sincronizar no crea otro y responde yaEnCurso: true. Sondea el trabajo en vuelo en lugar de encolar otro: puede que ya haya datos.
  • Cola de pendientes por organización, y hasta 24 períodos por petición. Superar el cupo de pendientes o el tamaño del lote responde 429 too_many_pending; sigue los trabajos existentes y reintenta después con un lote menor. No hay un rendimiento fijo de trabajos por minuto ni una hora de término garantizada.
  • Presupuesto de ejecución acotado por conector. El tiempo del handler no es un plazo de término del trabajo: también puede haber espera en cola, cierre y reintentos. Para rangos largos, la vía es asíncrona: POST /v1/connections/{conn}/syncs responde 202 con los job_ids, y el avance se sondea en GET /v1/syncs/{id} o llega por webhook.

Las cadencias programadas del enum son off, daily, 12h, 6h y 4h, y ninguna se elige a mano: la decide Emisso por conector en los sistemas que sincronizan (detalle). La frecuencia depende del sistema (por ejemplo, SII y Santander cada 4 horas; TGR y Poder Judicial diariamente); si necesitas una frecuencia de actualización mayor, escríbenos a contacto@tryemisso.com y te preparamos una propuesta. La sincronización a pedido convive con la programada bajo los mismos candados.

No hay un parámetro público para priorizar un trabajo. Si es urgente o no avanza, escríbenos desde el chat con la conexión, el período y el id del trabajo; lo revisamos sin garantizar prioridad ni plazo. El ejemplo de agosto y septiembre muestra cómo encolar y seguir cada resultado.

Medición y plan

La fuente de la medición es la bitácora: cada llamada deja exactamente una fila, con sus billable_units. No hay un contador paralelo que pueda divergir de lo auditado.

Qué cuenta contra el cupo de llamadas de una conexión:

  • Solo llamadas exitosas, de las categorías que ejecutan trabajo real: acciones, sincronizaciones y consultas del plano persistido. Un error factura 0.
  • El peso por llamada lo declara cada conector; el peso por defecto es 1.
  • Los conectores open (core, indicadores) y el plano de control (conexiones.*) facturan 0 siempre: la fila de bitácora existe igual, con billable_units en cero.
  • Las sincronizaciones cuentan, también las automáticas que agenda Emisso: cada una es una llamada de la conexión.
  • Cuando el SII no responde o está saturado durante una sincronización automática, Emisso vuelve a intentar las partes que faltaron unos minutos después. Esos reintentos no cuentan contra el cupo ni se frenan si la conexión ya lo alcanzó: la sincronización original es la única llamada que cuenta.
  • Lo que haces desde el dashboard o desde el flujo hosted no consume cuota: guardar tu propia credencial o paginar tus propios datos no puede gastar el presupuesto de tu integración.

El cupo es de 2.000 llamadas por conexión al mes, y es el mismo número en los tres planes. Corta por conexión, no por organización: cada conexión mide su propio período contra su propio techo, y cuando una lo alcanza sólo ESA conexión responde 429 quota_exceeded. Las demás conexiones de la misma organización siguen operando sin cambios. Subir de plan no mueve este techo, porque no es un atributo del plan sino una constante del producto. Si tu organización tiene un cupo ampliado negociado, el vigente es el que aparece en /billing, junto al uso del período en curso. Para pedir más cupo, escríbenos a contacto@tryemisso.com o por el chat contándonos qué conexión lo necesita y cuántas llamadas esperas al mes.

El período del cupo empieza el día del mes en que se contrató el plan, no el día 1, y al renovarse el consumo vuelve a cero. Para ver cuánto lleva cada conexión:

  • En el dashboard, la pestaña Uso de cada conexión muestra lo consumido, la fecha de renovación, una proyección al ritmo actual y de dónde vinieron las llamadas: sincronización automática, cada clave de API y cada agente MCP. El panel de inicio y /billing avisan cuando una conexión pasa el 80 % de su cupo.
  • Por API, cada respuesta de una llamada que cuenta trae el cupo de esa conexión después de la llamada:
Emisso-Uso-Llamadas: 1684
Emisso-Uso-Limite: 2000
Emisso-Uso-Renueva: 2026-11-04

El 429 quota_exceeded trae el mismo uso en error.details y un Retry-After con los segundos que faltan para la renovación.

Tres códigos distintos avisan que algo se frenó, y conviene no confundirlos:

CódigoEstadoReintentableQué significaQué hacer
rate_limited429SíSuperaste un tope de tasa puntual (por ejemplo, la emisión de enlaces).Espera y reintenta con backoff; respeta Retry-After cuando viene.
quota_exceeded429NoEsta conexión alcanzó su cupo de llamadas del período. Tus demás conexiones siguen funcionando.Espera el período siguiente o pide una ampliación. Subir de plan no cambia el cupo, y reintentar tampoco.
billing_past_due402NoLa organización tiene un pago pendiente y sus conexiones están en pausa.Paga en /billing. Reintentar no cambia nada.

Lo ya sincronizado queda guardado

Con un pago pendiente, las conexiones no sincronizan ni le responden consultas a tu integración, igual que sin un plan activo. Lo que ya sincronizaste queda guardado y se sigue viendo en el panel. Al pagar, tus conexiones vuelven a responder.

El plan contratado sí gobierna otras dos cosas, y ninguna es el cupo de llamadas: cuántas conexiones incluye antes de que las siguientes se cobren como add-on, y si incluye webhooks (Starter, Pro y Max los incluyen; la prueba gratuita no). La sincronización programada no es una diferencia de plan: los tres la incluyen; la frecuencia depende del conector. Ninguno de los dos topes anteriores es una constante del código; el número vigente de tu organización está en /billing. Crear un endpoint de webhook sin la función responde 403 feature_not_in_plan.

Cargar histórico del SII y Previred

La prueba incluye el mes actual y los dos anteriores. Para cargar meses anteriores se requiere un plan activo; los precios vigentes están en Facturación. Guardar una tarjeta o autorizar un acuerdo sin pago aprobado no habilita esta capacidad.

En Conexiones → tu conexión → Sincronización → Cargar histórico, el dueño o un administrador elige los meses y sigue la carga en un mapa. El panel ofrece meses desde el inicio de actividades de la empresa; la API no aplica ese piso. Se procesan primero los meses más recientes, con cargas escalonadas y sin cambiar la frecuencia automática. Cerrar la página no cancela los trabajos.

SistemaMódulos que se carganVentana de solicitud
SIICompras y ventas, boletas electrónicas, boletas de honorariosSegún disponibilidad del SII, sin tope de antigüedad impuesto por Emisso
SIIGuías de despachoHasta 6 meses
PreviredPlanillas pagadas, cotizaciones por trabajador, archivo para el F30-1Según disponibilidad de Previred, sin tope de antigüedad impuesto por Emisso

Cada carga acepta hasta 24 períodos. Es un límite del tamaño del lote, no de la antigüedad: puedes solicitar, por ejemplo, enero a diciembre de 2019 para SII o Previred, y después otro rango. El SII sitúa el inicio del RCV en agosto de 2017; esto no garantiza datos para cada empresa o período. Previred documenta un máximo de 36 meses por certificado de cotizaciones, que limita el rango de cada documento y no establece un máximo de antigüedad de las planillas.

Del 10 al 13 de cada mes, Previred solo acepta el mes actual y los dos anteriores (su período de pago); los meses más antiguos se pueden cargar desde el 14.

Las ventanas expresadas en meses incluyen el mes corriente. La disponibilidad depende del acceso de la conexión y de lo que conserve el portal: solicitar un período no garantiza que existan datos ni cobertura completa. Las nóminas actuales, la deuda actual, las empresas y la emisión de certificados nuevos de Previred no se repiten por cada mes. Esta carga no incluye bancos ni la recuperación de XML del SII. Los meses anteriores de un banco se piden a tu agente o por API, con <sistema>.conexion.sincronizar y periodo. Cada portal conserva una ventana distinta: Santander, por ejemplo, solo entrega 90 días, y la cartola de Itaú no tiene carga histórica (detalle). Las operaciones de XML y certificados que ya ofrece la API conservan su disponibilidad y permisos; quedar fuera de la selección del panel no las deshabilita para los clientes con acceso pagado.

La misma restricción de acceso se aplica al encolado REST y a las ejecuciones de sincronización por API o MCP; los períodos fuera de prueba devuelven feature_not_in_plan sin consultar el sistema. Las consultas a datos ya guardados permanecen disponibles según los permisos de la conexión.

Próximos pasos

  • El catálogo completo de códigos, con qué significa y qué hacer en cada uno: errores.
  • Configurar los avisos de sincronización en lugar de sondear: webhooks.
  • Qué es una conexión y por qué es la unidad de facturación: conexiones.
  • La superficie de control que aplica estos topes: API de control.

En esta página