Integración · javascript

Consulta un RUC con JavaScript y Bun o Node.js

Integra datos del RUC desde tu backend con fetch, API key privada, timeout y manejo de errores HTTP.

Antes de empezar

Bun o Node.js 18 o superior. Crea una API key activa y revisa el precio del endpoint de RUC antes de hacer consultas reales.

Obtener API key

Puedes explorar primero el playground con datos ficticios. El código de este tutorial consulta datos reales cuando lo ejecutas; revisa su precio y usa únicamente un identificador autorizado.

Configura tu entorno

Variable de entornobash

export ECUADORAPI_KEY="ecu_tu_api_key"

La clave vive en tu servidor. No la incluyas en código del navegador, repositorios ni capturas.

Implementa la consulta

ecuador-api.mjsjavascript

export async function lookupRuc(ruc) {
  if (!/^\d{13}$/.test(ruc)) throw new Error("Invalid RUC format")
  const key = process.env.ECUADORAPI_KEY
  if (!key) throw new Error("Missing ECUADORAPI_KEY")
  const response = await fetch(
    "https://api.ecuadorapi.com/api/v1/rucs/" + ruc,
    { headers: { Authorization: "Bearer " + key, Accept: "application/json" },
      signal: AbortSignal.timeout(60_000) }
  )
  const body = await response.json().catch(() => null)
  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After")
    throw new Error("Rate limited; Retry-After=" + (retryAfter ?? "unknown"))
  }
  if (!response.ok || !body || body.error || !body.data) {
    throw new Error("EcuadorAPI request failed; HTTP " + response.status)
  }
  return body.data
}

Conéctala con tu flujo

Guarda la función en ecuador-api.mjs y configura la clave en el entorno del servidor.
Valida el RUC en tu backend y llama a lookupRuc desde tu flujo autenticado.
Usa business_name y los demás campos documentados según su disponibilidad. Permite valores null y deja que la persona revise la información.

Uso dentro de tu aplicaciónjavascript

import { lookupRuc } from "./ecuador-api.mjs"

// Use an authorized RUC from your validated server-side request.
const taxpayer = await lookupRuc(validatedRuc)
// Use taxpayer in your application; do not log personal response records.

Verifica éxito y errores antes de lanzar

Prueba una respuesta exitosa, campos null, un identificador sin resultados, una clave inválida, saldo insuficiente, 429 y un timeout. Los ejemplos no reintentan automáticamente: ante 429 respeta Retry-After y decide cómo reprogramar la tarea. Una consulta exitosa repetida puede volver a cobrarse.