Ejemplos y buenas prácticas

Patrones probados para integrar la API en un punto de venta, un ERP o un formulario.

Autocompletar un cliente al escribir el RUC

Valida el RUC en el navegador, y sólo cuando tenga 11 dígitos válidos llama a tu servidor, que a su vez llama a la API con tu clave.

// Node.js (Express): tu servidor hace de intermediario
app.get("/clientes/ruc/:ruc", async (req, res) => {
  const r = await fetch("https://api.peru.winkstec.com/v1/ruc/" + req.params.ruc, {
    headers: { Authorization: "Bearer " + process.env.WINKSTEC_API_KEY },
    signal: AbortSignal.timeout(3000),
  });
  if (r.status === 404) return res.status(404).json({ mensaje: "RUC no encontrado" });
  if (!r.ok) return res.status(502).json({ mensaje: "Ingresa los datos a mano" });
  res.json(await r.json());
});

Reintentos con espera

Reintenta sólo errores 5xx y 429 por velocidad, nunca cuota_agotada ni 4xx.

async function consultar(ruc, intentos = 3) {
  for (let i = 0; i < intentos; i++) {
    const r = await fetch("https://api.peru.winkstec.com/v1/ruc/" + ruc, { headers: { Authorization: "Bearer " + KEY } });
    if (r.status === 429) {
      const body = await r.json();
      if (body.error === "cuota_agotada") throw new Error("Sin cuota");
      await new Promise((ok) => setTimeout(ok, Number(r.headers.get("retry-after") ?? 1) * 1000));
      continue;
    }
    if (r.status >= 500) { await new Promise((ok) => setTimeout(ok, 500 * 2 ** i)); continue; }
    return r.status === 404 ? null : r.json();
  }
  throw new Error("La API no respondió");
}

Guarda lo que consultas

El padrón cambia una vez al día. Si consultas el mismo RUC varias veces en el día, guárdalo en tu base o en caché por unas horas: ahorras cuota y tiempo.

No bloquees una venta por la API

Ponle un tiempo máximo corto (2–3 s) y, si falla, deja que el cajero escriba los datos a mano. Así lo hacemos en nuestro propio ERP.