Inicio rápido
Crea una clave en Vintu
Entra a
app.vintu.iocon una cuenta de propietario o de administrador con acceso a todas las empresas y abre Configuración → API y webhooks. Pulsa Crear clave, dale un nombre que diga dónde la vas a usar (por ejemplo, «Integración ERP») y deja marcados solo los permisos que necesites; por defecto vienen marcados todos los de lectura.La clave completa se muestra una sola vez, al crearla. Cópiala en ese momento: después la app solo enseña su prefijo.
Guárdala en una variable de entorno
Los ejemplos de esta documentación leen la clave de
VINTU_API_KEY. No la escribas en el código ni la subas a un repositorio.export VINTU_API_KEY="vk_live_…" # pega aquí tu clave$env:VINTU_API_KEY = "vk_live_…" # pega aquí tu claveComprueba la clave
GET /v1/cuentaresponde con cualquier clave válida, tenga los permisos que tenga. Si devuelve200, la clave funciona y la respuesta trae el plan, los límites de tu cuenta y el uso del mes.curl "https://api.vintu.io/v1/cuenta" \ -H "Authorization: Bearer $VINTU_API_KEY"const url = new URL("https://api.vintu.io/v1/cuenta"); 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/cuenta", 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())Lee tus datos
Con la clave comprobada, pide la primera página de comprobantes. Cada elemento trae sus importes como cadenas decimales y un
archivo_urlpara descargar el original durante una hora.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())Si
siguiente_cursorno es nulo, hay más páginas: pásalo encursorpara pedir la siguiente. Ver Paginación y sincronización.
Si algo falla
Toda respuesta de error trae {"error": {"codigo", "mensaje", "id_peticion"}}. Los tres casos más comunes al
empezar:
401 INVALID_API_KEY: la cabecera falta, la clave está mal copiada o fue revocada. Comprueba que el valor seaBearerseguido de la clave completa, sin espacios ni saltos de línea al final.403 API_PLAN_REQUIRED: tu plan no incluye la API. Está en los planes Contador y Estudio.403 SCOPE_REQUIRED: la clave no tiene el permiso de esa operación. Los permisos se eligen al crear la clave; ver Permisos.
La lista completa está en Errores. Si escribes a soporte, cita el id_peticion.
Solo hay claves de producción
Las claves leen los datos reales de tu cuenta. Si una clave queda expuesta, revócala en Configuración → API y webhooks: deja de funcionar en un máximo de 60 segundos.
Siguientes pasos
- Autenticación y claves: quién puede crearlas, cómo rotarlas y revocarlas.
- Sincronizar comprobantes: llevar a tu sistema solo lo nuevo o modificado.
- Referencia: cada operación con sus parámetros y respuestas.