Listar comprobantes
GET /v1/comprobantes
Comprobantes recibidos por correo, WhatsApp o Drive, del más antiguo al más reciente. Los importes llegan como cadenas decimales; archivo_url permite descargar el original durante una hora.
Permiso
La clave necesita comprobantes:leer. Ver Permisos.
Parámetros
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
limite | consulta | integer | Elementos por página, de 1 a 100. De 1 a 100. Por defecto, 25. |
cursor | consulta | string | null | Valor de siguiente_cursor de la página anterior. Caduca a las 24 horas. |
empresa_id | consulta | string · uuid | null | Solo los de esta empresa (su id). |
actualizado_desde | consulta | string · date-time | null | Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por actualizado_en. |
Petición
La clave se lee de la variable de entorno VINTU_API_KEY. Ver Inicio rápido.
curl -G "https://api.vintu.io/v1/comprobantes" \
--data-urlencode "limite=25" \
-H "Authorization: Bearer $VINTU_API_KEY"const url = new URL("https://api.vintu.io/v1/comprobantes");
url.searchParams.set("limite", "25");
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": "25"},
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())Respuesta
200 · Correcto.
| Cabecera | Descripción |
|---|---|
X-Request-ID | Identificador de la petición; cítalo al pedir soporte. |
X-Vintu-Mode | lectura_degradada cuando la coordinación no responde y los límites se aplican por réplica. |
RateLimit-Limit | Peticiones por minuto admitidas. |
RateLimit-Remaining | Peticiones que quedan en la ventana. |
RateLimit-Reset | Segundos hasta que se recupera el cupo. |
Campos
| Campo | Tipo | Descripción |
|---|---|---|
datos | array de object | Elementos de esta página. |
datos[].id | string · uuid | Identificador público del comprobante. |
datos[].empresa_id | string · uuid | null | Empresa a la que se atribuyó; nulo si aún no tiene. |
datos[].tipo | string | null | factura, boleta, recibo_honorarios, nota_credito, nota_debito, recibo_servicios, boleto_aereo u otro; nulo si no se pudo leer. |
datos[].serie | string | null | Serie del comprobante. |
datos[].numero | string | null | Número correlativo, como texto. |
datos[].ruc_emisor | string | null | RUC de quien emitió el comprobante. |
datos[].fecha_emision | string · date | null | Fecha de emisión. |
datos[].moneda | string | null | Código de moneda, p. ej. PEN. |
datos[].base_imponible | string | null | Importe decimal como cadena, con punto: 1000.00. |
datos[].igv | string | null | Importe decimal como cadena, con punto: 180.00. |
datos[].total | string | null | Importe decimal como cadena, con punto: 1180.00. |
datos[].estado | string | recibido, extraido, requiere_revision, confirmado o descartado. confirmado significa que el contador lo revisó. |
datos[].creado_en | string · date-time | Llegada del comprobante a Vintu. |
datos[].actualizado_en | string · date-time | Último cambio del comprobante. |
datos[].archivo_url | string | null | Enlace de descarga del original, válido 1 hora y ligado a la clave que lo pidió. No lleva la cabecera Authorization. |
siguiente_cursor | string | null | Pásalo en cursor para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta. |
marca_superior | string · date-time | null | Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como actualizado_desde de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por id. |
Ejemplo con datos ficticiosJSON
{
"datos": [
{
"id": "00000000-0000-4000-8000-0000000000d1",
"empresa_id": "00000000-0000-4000-8000-0000000000c1",
"tipo": "factura",
"serie": "F001",
"numero": "1234",
"ruc_emisor": "20000000003",
"fecha_emision": "2026-11-09",
"moneda": "PEN",
"base_imponible": "1000.00",
"igv": "180.00",
"total": "1180.00",
"estado": "extraido",
"creado_en": "2026-11-10T14:32:05.120000+00:00",
"actualizado_en": "2026-11-12T09:15:41.004000+00:00",
"archivo_url": "https://api.vintu.io/v1/archivos/ENLACE_DE_EJEMPLO"
}
],
"siguiente_cursor": "CURSOR_DE_EJEMPLO",
"marca_superior": "2026-11-12T09:15:41.004000+00:00"
}Errores
Todos con el cuerpo {"error": {"codigo", "mensaje", "id_peticion"}}. Compara contra
codigo; el mensaje puede cambiar. Ver Errores.
| Estado | Códigos | Cuándo |
|---|---|---|
| 401 | INVALID_API_KEY | Clave ausente, mal formada, inexistente o revocada (INVALID_API_KEY). |
| 403 | SCOPE_REQUIREDAPI_PLAN_REQUIREDACCESS_DENIED | La clave no tiene el permiso de la operación (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED). |
| 422 | VALIDATION_ERRORINVALID_CURSORCURSOR_EXPIRED | Parámetro inválido (VALIDATION_ERROR), cursor de otra consulta (INVALID_CURSOR) o cursor caducado a las 24 horas (CURSOR_EXPIRED). |
| 429 | RATE_LIMITED | Se superó el límite de peticiones (RATE_LIMITED). Espera lo que indica Retry-After. |
| 503 | DEPENDENCY_UNAVAILABLELOCAL_CAPACITY | Servicio no disponible temporalmente (DEPENDENCY_UNAVAILABLE o LOCAL_CAPACITY). Reintenta tras Retry-After. |