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

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.`);

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

  1. Primera ejecución. No hay marca guardada: recorre todos los comprobantes, página a página, hasta que siguiente_cursor es nulo. Al terminar guarda la marca_superior.
  2. Siguientes ejecuciones. Recorre con actualizado_desde igual a la marca: llegan los comprobantes nuevos y los que cambiaron desde entonces (por ejemplo, porque el contador los confirmó o corrigió un importe).
  3. Por id. Lo que llega se guarda por id, sustituyendo la versión anterior. Así un comprobante que llega dos veces no se duplica.
  4. Reintentos. Ante 429 o 503 espera lo que dice Retry-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:

estadoSignifica
recibidoLlegó a Vintu y aún no se leyó.
extraidoVintu leyó sus datos.
requiere_revisionVintu lo leyó con dudas: confianza baja, falta el RUC del emisor o los importes no cuadran.
confirmadoEl contador lo revisó.
descartadoEl 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.