Paginación y sincronización
Los listados (/v1/empresas, /v1/comprobantes, /v1/avisos y /v1/vencimientos) devuelven una página a la vez:
{
"datos": [ … ],
"siguiente_cursor": "CURSOR_DE_EJEMPLO",
"marca_superior": "2026-11-12T09:15:41.004000+00:00"
}| Campo | Qué es |
|---|---|
datos | Los elementos de esta página. |
siguiente_cursor | Pásalo en cursor para pedir la página siguiente. Nulo en la última. |
marca_superior | El instante en que empezó el recorrido. Es el mismo en todas sus páginas. |
Parámetros
| Parámetro | Qué hace |
|---|---|
limite | Elementos por página, de 1 a 100. Por defecto, 25. Fuera de ese rango, 422 VALIDATION_ERROR. |
cursor | El siguiente_cursor de la página anterior, tal cual. |
actualizado_desde | Solo lo creado o modificado desde ese instante, incluido. ISO 8601 con zona horaria. |
empresa_id | Solo 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_idy mismoactualizado_desde. Si cambian, la respuesta es422 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_superiorno 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:
- Carga inicial. Recorre el listado completo, sin
actualizado_desde, hasta quesiguiente_cursorsea nulo. Guarda los elementos poridy, al terminar, guarda lamarca_superior. - Cada sincronización siguiente. Recorre el listado con
actualizado_desdeigual a la marca guardada. Guarda lo que llegue porid(si ya lo tenías, sustitúyelo) y, al terminar, guarda la nuevamarca_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"const url = new URL("https://api.vintu.io/v1/comprobantes");
url.searchParams.set("limite", "100");
url.searchParams.set("actualizado_desde", "2026-11-12T09:15:41.004000+00:00");
const respuesta = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.VINTU_API_KEY}` },
});
if (!respuesta.ok) {
const { error } = await respuesta.json();
throw new Error(`${respuesta.status} ${error.codigo}: ${error.mensaje} (${error.id_peticion})`);
}
const cuerpo = await respuesta.json();
console.log(cuerpo);import os
import requests
respuesta = requests.get(
"https://api.vintu.io/v1/comprobantes",
params={"limite": "100", "actualizado_desde": "2026-11-12T09:15:41.004000+00:00"},
headers={"Authorization": f"Bearer {os.environ['VINTU_API_KEY']}"},
timeout=30,
)
if not respuesta.ok:
error = respuesta.json()["error"]
raise RuntimeError(f"{respuesta.status_code} {error['codigo']}: {error['mensaje']} ({error['id_peticion']})")
print(respuesta.json())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.