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

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"

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.