Sincronizar comprobantes
Esta guía lleva los comprobantes de tu cuenta a un archivo local y, en cada ejecución siguiente, trae solo lo que
cambió. Es el patrón de Paginación y sincronización aplicado de punta a punta. Necesitas una clave
con el permiso comprobantes:leer.
El programa completo
// Sincroniza los comprobantes de Vintu en un archivo local (estado.json).
// Uso: VINTU_API_KEY=... node sincronizar-comprobantes.mjs (Node 18 o superior)
import { readFile, writeFile } from "node:fs/promises";
const BASE = "https://api.vintu.io";
const ESTADO = "estado.json";
async function pedir(url) {
for (let intento = 1; ; intento++) {
const respuesta = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.VINTU_API_KEY}` },
});
if (respuesta.ok) return respuesta.json();
const { error } = await respuesta.json();
// 429 y 503 son pasajeros: se espera lo que indica Retry-After.
if ((respuesta.status === 429 || respuesta.status === 503) && intento < 5) {
const segundos = Number(respuesta.headers.get("Retry-After") ?? 10);
await new Promise((listo) => setTimeout(listo, segundos * 1000));
continue;
}
const fallo = new Error(`${respuesta.status} ${error.codigo}: ${error.mensaje} (${error.id_peticion})`);
fallo.codigo = error.codigo;
throw fallo;
}
}
// Un recorrido completo: todas las páginas, siempre con los mismos filtros.
async function recorrer(desde) {
const cambios = [];
let cursor = null;
let marca = null;
do {
const url = new URL("/v1/comprobantes", BASE);
url.searchParams.set("limite", "100");
if (desde) url.searchParams.set("actualizado_desde", desde);
if (cursor) url.searchParams.set("cursor", cursor);
const pagina = await pedir(url);
cambios.push(...pagina.datos);
marca ??= pagina.marca_superior;
cursor = pagina.siguiente_cursor;
} while (cursor);
return { cambios, marca };
}
const estado = JSON.parse(await readFile(ESTADO, "utf8").catch(() => '{"marca": null, "comprobantes": {}}'));
let resultado;
try {
resultado = await recorrer(estado.marca);
} catch (error) {
// Un cursor caduca a las 24 horas: se repite el recorrido desde la misma marca.
if (error.codigo !== "CURSOR_EXPIRED") throw error;
resultado = await recorrer(estado.marca);
}
for (const comprobante of resultado.cambios) {
// Por id: lo que llega dos veces se sobrescribe. archivo_url vence en una hora,
// así que no se guarda: se pide el comprobante otra vez cuando haga falta.
const { archivo_url, ...datos } = comprobante;
estado.comprobantes[comprobante.id] = datos;
}
// La marca se guarda solo al terminar el recorrido entero.
estado.marca = resultado.marca;
await writeFile(ESTADO, JSON.stringify(estado, null, 2));
console.log(`${resultado.cambios.length} comprobantes nuevos o modificados.`);"""Sincroniza los comprobantes de Vintu en un archivo local (estado.json).
Uso: VINTU_API_KEY=... python sincronizar_comprobantes.py (requiere requests)
"""
import json
import os
import time
import requests
BASE = "https://api.vintu.io"
ESTADO = "estado.json"
class ErrorVintu(Exception):
def __init__(self, estado, error):
super().__init__(f"{estado} {error['codigo']}: {error['mensaje']} ({error['id_peticion']})")
self.codigo = error["codigo"]
def pedir(sesion, ruta, params):
for intento in range(1, 6):
respuesta = sesion.get(BASE + ruta, params=params, timeout=30)
if respuesta.ok:
return respuesta.json()
error = respuesta.json()["error"]
# 429 y 503 son pasajeros: se espera lo que indica Retry-After.
if respuesta.status_code in (429, 503) and intento < 5:
time.sleep(int(respuesta.headers.get("Retry-After", "10")))
continue
raise ErrorVintu(respuesta.status_code, error)
def recorrer(sesion, desde):
"""Un recorrido completo: todas las páginas, siempre con los mismos filtros."""
cambios, cursor, marca = [], None, None
while True:
params = {"limite": 100}
if desde:
params["actualizado_desde"] = desde
if cursor:
params["cursor"] = cursor
pagina = pedir(sesion, "/v1/comprobantes", params)
cambios.extend(pagina["datos"])
marca = marca or pagina["marca_superior"]
cursor = pagina["siguiente_cursor"]
if not cursor:
return cambios, marca
def main():
try:
with open(ESTADO, encoding="utf-8") as archivo:
estado = json.load(archivo)
except FileNotFoundError:
estado = {"marca": None, "comprobantes": {}}
sesion = requests.Session()
sesion.headers["Authorization"] = f"Bearer {os.environ['VINTU_API_KEY']}"
try:
cambios, marca = recorrer(sesion, estado["marca"])
except ErrorVintu as error:
# Un cursor caduca a las 24 horas: se repite el recorrido desde la misma marca.
if error.codigo != "CURSOR_EXPIRED":
raise
cambios, marca = recorrer(sesion, estado["marca"])
for comprobante in cambios:
# Por id: lo que llega dos veces se sobrescribe. archivo_url vence en una hora,
# así que no se guarda: se pide el comprobante otra vez cuando haga falta.
comprobante.pop("archivo_url", None)
estado["comprobantes"][comprobante["id"]] = comprobante
# La marca se guarda solo al terminar el recorrido entero.
estado["marca"] = marca
with open(ESTADO, "w", encoding="utf-8") as archivo:
json.dump(estado, archivo, ensure_ascii=False, indent=2)
print(f"{len(cambios)} comprobantes nuevos o modificados.")
if __name__ == "__main__":
main()Cámbialo para escribir en tu base de datos en vez de estado.json: lo importante es guardar cada comprobante por
id y la marca después de procesar todos.
Qué hace, paso a paso
- Primera ejecución. No hay marca guardada: recorre todos los comprobantes, página a página, hasta que
siguiente_cursores nulo. Al terminar guarda lamarca_superior. - Siguientes ejecuciones. Recorre con
actualizado_desdeigual a la marca: llegan los comprobantes nuevos y los que cambiaron desde entonces (por ejemplo, porque el contador los confirmó o corrigió un importe). - Por
id. Lo que llega se guarda porid, sustituyendo la versión anterior. Así un comprobante que llega dos veces no se duplica. - Reintentos. Ante
429o503espera lo que diceRetry-After. Si el cursor caduca (CURSOR_EXPIRED), repite el recorrido desde la misma marca.
Qué comprobantes importar
El campo estado dice en qué punto está cada comprobante:
estado | Significa |
|---|---|
recibido | Llegó a Vintu y aún no se leyó. |
extraido | Vintu leyó sus datos. |
requiere_revision | Vintu lo leyó con dudas: confianza baja, falta el RUC del emisor o los importes no cuadran. |
confirmado | El contador lo revisó. |
descartado | El contador lo descartó. |
Si tu sistema contable solo debe recibir lo revisado, importa los confirmado y trata los descartado como bajas.
Un comprobante descartado no desaparece de la API: cambia de estado y llega en la siguiente sincronización.
Lo que la API no trae
Los comprobantes que entraron por la conexión con Gmail, o de origen desconocido, no salen por la API. Y
archivo_url vence en una hora: el programa no lo guarda, se pide el comprobante otra vez cuando hace falta el
archivo. Ver Descarga de archivos.
Programarlo
Ejecútalo con la frecuencia que necesites (por ejemplo, cada 15 minutos con cron o el Programador de tareas de
Windows). Cada ejecución cuesta una petición por página; con limite=100, una sincronización con pocos cambios es
una sola petición.