Saltar al contenido
Vintu API
Tema de la documentación
Ir a la app

Paginación y sincronización

Los listados (/v1/empresas, /v1/comprobantes, /v1/avisos y /v1/vencimientos) devuelven una página a la vez:

Forma de una página (datos ficticios)JSON
{
"datos": [ … ],
"siguiente_cursor": "CURSOR_DE_EJEMPLO",
"marca_superior": "2026-11-12T09:15:41.004000+00:00"
}
CampoQué es
datosLos elementos de esta página.
siguiente_cursorPásalo en cursor para pedir la página siguiente. Nulo en la última.
marca_superiorEl instante en que empezó el recorrido. Es el mismo en todas sus páginas.

Parámetros

ParámetroQué hace
limiteElementos por página, de 1 a 100. Por defecto, 25. Fuera de ese rango, 422 VALIDATION_ERROR.
cursorEl siguiente_cursor de la página anterior, tal cual.
actualizado_desdeSolo lo creado o modificado desde ese instante, incluido. ISO 8601 con zona horaria.
empresa_idSolo los de esa empresa (su id). En comprobantes, avisos y vencimientos.

Orden

Sin actualizado_desde, los elementos salen del más antiguo al más reciente por creado_en. Con actualizado_desde, el orden pasa a ser por actualizado_en. En los dos casos el id desempata, así que el orden es estable entre páginas.

El cursor

El cursor es opaco: no lo interpretes ni lo construyas, pásalo tal como llegó.

  • Repite los mismos filtros en cada página. El cursor vale solo para la consulta que lo produjo: mismo recurso, mismo empresa_id y mismo actualizado_desde. Si cambian, la respuesta es 422 INVALID_CURSOR.
  • Caduca a las 24 horas. Un cursor más antiguo responde 422 CURSOR_EXPIRED: vuelve a pedir la primera página con los mismos filtros.
  • Lo que se cree o se modifique después de marca_superior no entra en el recorrido en curso. No se pierde: lo trae la sincronización siguiente.

Sincronizar solo lo que cambió

marca_superior y actualizado_desde están pensados para usarse juntos:

  1. Carga inicial. Recorre el listado completo, sin actualizado_desde, hasta que siguiente_cursor sea nulo. Guarda los elementos por id y, al terminar, guarda la marca_superior.
  2. Cada sincronización siguiente. Recorre el listado con actualizado_desde igual a la marca guardada. Guarda lo que llegue por id (si ya lo tenías, sustitúyelo) y, al terminar, guarda la nueva marca_superior.

Dos detalles que evitan perder o duplicar datos:

  • Guarda la marca solo cuando el recorrido termina. Si se corta a mitad, repítelo desde la marca anterior.
  • Deduplica por id. El filtro incluye el propio instante de la marca, así que un elemento modificado justo en ese instante puede llegar en dos sincronizaciones seguidas.
curl -G "https://api.vintu.io/v1/comprobantes" \
  --data-urlencode "limite=100" \
  --data-urlencode "actualizado_desde=2026-11-12T09:15:41.004000+00:00" \
  -H "Authorization: Bearer $VINTU_API_KEY"

La zona horaria es obligatoria

actualizado_desde sin zona responde 422 VALIDATION_ERROR. Y en una URL el + de +00:00 se interpreta como un espacio si no se codifica: usa %2B, la forma Z (2026-11-12T09:15:41Z) o deja que tu cliente HTTP codifique la consulta, como en los ejemplos.

La guía Sincronizar comprobantes tiene el recorrido completo en JavaScript y Python.