Documentación del API

Inicio

El SDK oficial de Factuplan (factuplan en npm, v0.8.0) te permite emitir facturas electrónicas, notas de crédito, guías de remisión y comprobantes de retención autorizados por el SRI del Ecuador desde tu backend, en JavaScript o TypeScript.

• Node.js 18+ · ESM & CJS · cero dependencias.
• Tipado completo en TypeScript.
• Dos entornos: pruebas (ak_test_*) y producción (ak_live_*).
• Compatible con Postman: descarga la colección desde tu cuenta.

Importante: los comprobantes creados con una API key de pruebas se eliminan automáticamente cada hora. Usa pruebas solo para desarrollo.

Instalación

Instalá el SDK con el gestor de paquetes que prefieras:

# npm
npm install factuplan

# pnpm
pnpm add factuplan

# yarn
yarn add factuplan

Crear una API key

1. Iniciá sesión en app.factuplan.com.ec.
2. Anda a Developer → Create API key.
3. Copia la clave generada — solo se muestra una vez.
4. Guardala en una variable de entorno (FACTUPLAN_API_KEY), nunca la subas al repositorio.

Las API keys son por workspace. El prefijo indica el entorno:

Autenticación

El SDK adjunta automáticamente la API key y el RUC del contribuyente en cada petición (x-taxpayer-ruc). Solo tienes que inicializar el cliente:

import { Factuplan } from "factuplan"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001",
})

Si vas a usar únicamente operaciones que no requieren contribuyente (por ejemplo, listar tu uso del mes), puedes omitir el ruc:

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!)

Seguridad: nunca expongas tu API key en el frontend. Usala solo desde tu servidor.

Clientes

CRUD de los clientes (receptores) que aparecerán en tus comprobantes.

Crear cliente

const cliente = await factuplan.customers.create({
  identificationType: "RUC", // RUC | CEDULA | PASSPORT | FINAL_CONSUMER
  identification: "0993378150001", // RUC=13 dígitos · CEDULA=10 dígitos
  legalName: "Empresa Demo S.A.",
  email: "facturas@empresademo.ec", // opcional
  address: "Guayaquil, Ecuador", // opcional
  phone: "+593985691039", // opcional
})

Listar clientes

Devuelve resultados paginados con un objeto meta que incluye el total.

const { data: clientes, meta } = await factuplan.customers.list({
  page: 1,
  limit: 20,
  search: "empresa",
})

console.log(meta.total, "clientes encontrados")

Obtener, actualizar y eliminar

const cliente = await factuplan.customers.get("cust_id")

await factuplan.customers.update("cust_id", {
  email: "nuevo@empresademo.ec",
})

await factuplan.customers.delete("cust_id")

Productos

CRUD del catálogo de ítems facturables. Funciona igual para productos tangibles y servicios.

Crear producto

const producto = await factuplan.products.create({
  code: "SERV-001",
  name: "Servicio de consultoría",
  unitPrice: 150.0,
  type: "SERVICE", // PRODUCT | SERVICE
  taxType: "IVA_RATE", // IVA_0 | IVA_RATE | NOT_TAXABLE | EXEMPT
  description: "Hora de consultoría técnica", // opcional
})

Listar, actualizar y eliminar

const { data: productos } = await factuplan.products.list({
  search: "consultoría",
})

await factuplan.products.update("prod_id", { unitPrice: 175.0 })

await factuplan.products.delete("prod_id")

Facturas

Emisión completa de facturas electrónicas: el SDK genera el XML, lo firma con tu certificado, lo envía al SRI, genera el RIDE PDF y, opcionalmente, manda el correo al cliente.

Crear factura

const factura = await factuplan.invoices.create({
  // Punto de emisión: elige UNA de las 3 opciones
  // 1) Por UUID:
  emissionPointId: "ep_id",
  // 2) Por códigos SRI:
  // establishment: "001",
  // emissionPoint: "001",
  // 3) Omitir todo: auto-detecta si solo hay un punto de emisión activo

  customer: {
    identificationType: "RUC",
    identification: "0993378150001",
    legalName: "Cliente S.A.",
    email: "facturas@cliente.ec",
    saveToContacts: true,
  },
  items: [
    {
      code: "SERV-001",
      description: "Servicio de consultoría",
      quantity: 1,
      unitPrice: 1.0,
      discount: 0,
      taxType: "IVA_RATE",
      tax: 15, // 0, 5, 8, 12, 14, 15 (default: 15)
    },
  ],
  payments: [
    {
      method: "20",
      amount: 1.15,
      term: 30,
      timeUnit: "dias",
    },
  ],
  additionalInfo: { Vendedor: "Juan Pérez" },
  // sendEmail: false,  // opcional, default: true
})

console.log(factura.id) // ID interno
console.log(factura.accessKey) // Clave de acceso SRI (49 dígitos)
console.log(factura.sequential) // Secuencial del comprobante

Punto de emisión

Tres formas de resolver el punto de emisión, en orden de prioridad:

// 1) Por UUID (referencia directa)
factuplan.invoices.create({ emissionPointId: "ep_id", ... })

// 2) Por códigos SRI del establecimiento + punto de emisión
factuplan.invoices.create({ establishment: "001", emissionPoint: "001", ... })

// 3) Auto-detección: si solo tienes un punto activo, omitilo
factuplan.invoices.create({ customer, items, payments })

Tipos de impuesto (taxType)

Tarifas de IVA (tax)

Usa tax cuando taxType sea IVA_RATE. Default: 15.

// Item con IVA reducido al 5%
items: [
  {
    code: "PROD-001",
    description: "Producto con IVA reducido",
    quantity: 1,
    unitPrice: 100.0,
    taxType: "IVA_RATE",
    tax: 5,
  },
]

Formas de pago (payments)

Cada elemento del arreglo payments lleva el código SRI en method, el amount y, opcionalmente, term + timeUnit. Si omitís payments se aplica '01' (Sin utilización del sistema financiero) por defecto.

La suma de los amount debe ser exactamente igual al total de la factura con impuestos. De lo contrario el SRI rechaza con 400 Bad Request.

Redondeo y precisión

• unitPrice admite hasta 4 decimales — útil para productos con costos unitarios bajos.
• Los totales finales (subtotal, IVA, total) se redondean automáticamente a 2 decimales según el estándar del SRI.

Ejemplos:

Cantidad: 1000  ×  Precio: 0.1234  =  Subtotal: 123.40
Base imponible: 10.05  ×  0.15  =  1.5075  →  IVA: 1.51
Total a pagar (Base + IVA): 11.56

Consultar estado

const estado = await factuplan.invoices.getStatus("factura_id")
// estado.status: PROCESSING | AUTHORIZED | COMPLETED | ERROR | REJECTED

if (estado.status === "COMPLETED") {
  console.log(estado.authorizationNumber)
}

Descargar XML y PDF

URLs pre-firmadas que expiran en 5 minutos.

const { url: xmlUrl } = await factuplan.invoices.downloadXml("id")
const { url: pdfUrl } = await factuplan.invoices.downloadPdf("id")

Importar por clave de acceso

Importa una factura ya autorizada por el SRI usando su clave de 49 dígitos. Útil para sincronizar comprobantes emitidos fuera de Factuplan.

Solo ak_live_*. No disponible con claves de pruebas.

const factura = await factuplan.invoices.importByAccessKey({
  accessKey: "0104202601099337815000110010010000000011234567890",
})

Consultar comprobante externo por clave de acceso

POST /developer/receipts/query — consulta cualquier comprobante autorizado por el SRI (factura, nota de crédito, guía de remisión), sin importar qué sistema lo emitió. Si el contribuyente emisor no existe en tu workspace, se crea automáticamente con firma vacía.

Solo ak_live_*. No disponible con claves de pruebas.

Cómo se descuenta el contador: el crédito se descuenta cuando el comprobante está autorizado, sin importar el valor de save. Si no está autorizado, no se descuenta ningún crédito.

// Consultar y guardar (default)
const comp = await factuplan.invoices.queryExternalByAccessKey({
  accessKey: "0104202601019999999900110010010000000011234567813",
})
console.log(comp.id, comp.status, comp.xmlBase64)

// Solo verificar sin guardar
const verificado = await factuplan.invoices.queryExternalByAccessKey({
  accessKey: "0104202601019999999900110010010000000011234567813",
  save: false,
})
console.log(verificado.id) // null
console.log(verificado.xmlBase64) // XML autorizado

Ejemplo completo

// ejemplo-factura.ts
import { Factuplan } from "factuplan"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!)

async function crearFactura() {
  // 1. Buscar o crear cliente
  const { data: clientes } = await factuplan.customers.list({
    search: "0993378150001",
  })
  const cliente =
    clientes[0] ??
    (await factuplan.customers.create({
      identificationType: "RUC",
      identification: "0993378150001",
      legalName: "Mi Cliente S.A.",
      email: "facturas@cliente.ec",
    }))

  // 2. Crear factura (auto-detecta el punto de emisión)
  const factura = await factuplan.invoices.create({
    customer: {
      identificationType: cliente.identificationType,
      identification: cliente.identification,
      legalName: cliente.legalName,
      email: cliente.email,
    },
    items: [
      {
        code: "PROD-001",
        description: "Laptop Dell XPS 15",
        quantity: 1,
        unitPrice: 1500.0,
        taxType: "IVA_RATE",
        tax: 15,
      },
    ],
    payments: [
      {
        method: "19",
        amount: 1725.0, // Total con IVA
        term: 6,
        timeUnit: "meses",
      },
    ],
  })

  // 3. Polling hasta que el SRI responda
  let estado
  do {
    await new Promise((r) => setTimeout(r, 3000))
    estado = await factuplan.invoices.getStatus(factura.id)
  } while (!["COMPLETED", "ERROR", "REJECTED"].includes(estado.status))

  if (estado.status === "COMPLETED") {
    const { url } = await factuplan.invoices.downloadPdf(factura.id)
    console.log("PDF:", url)
  }
}

crearFactura()

Firmar XML

Si tu sistema ya genera el XML (sin firmar), puedes enviarlo a Factuplan para que lo firme con tu certificado y lo autorice ante el SRI. El SDK se encarga de firmar, transmitir, generar el PDF y notificar al cliente.

Importante: el XML debe ir como string sin firmar. Factuplan se ocupa de la firma electrónica.

Firmar y autorizar

const result = await factuplan.invoices.signAndAuthorize({
  xml: xmlString, // XML sin firmar como string
})

console.log(result.id) // ID del comprobante
console.log(result.accessKey) // Clave de acceso SRI
console.log(result.status) // Estado inicial

Solo firmar (modo C)

Firma el XML con tu certificado sin enviarlo al SRI. Útil cuando quieres controlar el envío al SRI por tu cuenta.

const { signedXml } = await factuplan.invoices.signOnly({
  xml: xmlString,
})

Validar XML

Valida la estructura de un XML sin procesarlo ni enviarlo al SRI.

const { valid, errors } = await factuplan.invoices.validateXml({
  xml: xmlString,
})

if (!valid) {
  console.log("Errores:", errors)
}

Verificar autorización

Consulta el estado de un comprobante en el SRI usando su clave de acceso.

const result = await factuplan.invoices.verify(
  "0104202601099337815000110010010000000011234567890",
)

console.log(result.authorized) // true | false
console.log(result.authorizationNumber)

Ejemplo completo: firmar XML

// firmar-xml.ts
import { Factuplan } from "factuplan"
import { readFileSync } from "fs"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!)

async function firmarYAutorizar() {
  const xml = readFileSync("./factura-sin-firmar.xml", "utf-8")
  const result = await factuplan.invoices.signAndAuthorize({ xml })

  console.log("Clave de acceso:", result.accessKey)

  let estado
  do {
    await new Promise((r) => setTimeout(r, 3000))
    estado = await factuplan.invoices.getStatus(result.id)
  } while (!["COMPLETED", "ERROR", "REJECTED"].includes(estado.status))

  if (estado.status === "COMPLETED") {
    const { url: xmlUrl } = await factuplan.invoices.downloadXml(result.id)
    const { url: pdfUrl } = await factuplan.invoices.downloadPdf(result.id)
    console.log("XML firmado:", xmlUrl)
    console.log("PDF (RIDE):", pdfUrl)
  }
}

firmarYAutorizar()

Errores

El SDK exporta clases tipadas para cada categoría de error. Esto te permite ramificar el manejo según el tipo:

import { FactuplanError, AuthenticationError, RateLimitError } from "factuplan"

try {
  await factuplan.invoices.create({
    /* ... */
  })
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("API key inválida o expirada")
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit alcanzado, reintentar")
  } else if (error instanceof FactuplanError) {
    console.error(error.code) // ej. "INVOICE_4002"
    console.error(error.message)
    console.error(error.statusCode) // ej. 422
    console.error(error.details)
  }
}

Códigos de error frecuentes

Rate Limit

Cada API key tiene dos límites:

• Velocidad: 100 peticiones por segundo por API key.
• Cuota mensual: depende del plan contratado (consulta /precios).

Si superás cualquiera de los dos, recibes HTTP 429. Implementá reintentos con espera exponencial.

Respuesta al superar el límite

{
  "success": false,
  "error": {
    "code": "GENERAL_0003",
    "message": "Has superado el límite de peticiones. Intenta de nuevo en unos segundos."
  }
}

{
  "success": false,
  "error": {
    "code": "API_10002",
    "message": "Has alcanzado el límite mensual de 500 documentos.",
    "details": { "used": 500, "quota": 500 }
  }
}

Manejo recomendado con reintentos

import { RateLimitError } from "factuplan"

async function emitirConReintento(datos: any, intentos = 3) {
  for (let i = 0; i < intentos; i++) {
    try {
      return await factuplan.invoices.create(datos)
    } catch (error) {
      if (error instanceof RateLimitError && i < intentos - 1) {
        const espera = Math.pow(2, i) * 500 // 500ms, 1s, 2s...
        await new Promise((r) => setTimeout(r, espera))
      } else {
        throw error
      }
    }
  }
}

Webhooks

Antes de procesar un evento webhook, verifica que el comprobante exista y consulta su estado actual usando su ID. Esto evita que actualices tu base de datos con eventos manipulados o duplicados.

Verificar comprobante

const receipt = await factuplan.webhooks.verifyReceipt("receipt_id")

console.log(receipt.id)
console.log(receipt.status) // PROCESSING | AUTHORIZED | COMPLETED | ERROR | REJECTED
console.log(receipt.accessKey) // Clave de acceso SRI (49 dígitos)

Tip: llama a este endpoint apenas recibes un evento webhook. Confirmá que el comprobante existe antes de actualizar tu BD o disparar notificaciones a tus usuarios.

Uso & Límites

Consulta el consumo del mes en curso y el límite de tu plan.

const uso = await factuplan.usage()

console.log(uso.requestsUsed, "/", uso.requestsLimit)
console.log("Costo estimado: $" + uso.estimatedCost)

Estructura de respuesta

Certificado

Consulta el estado del certificado P12 cargado en tu cuenta.

const cert = await factuplan.certificateStatus()

console.log(cert.valid) // true = vigente
console.log(cert.expiresAt) // Fecha de vencimiento (ISO 8601)
console.log(cert.taxpayerId) // RUC del titular
console.log(cert.commonName) // Nombre registrado en el certificado

Si valid es false, las facturas no se firmarán hasta que renueves el certificado en Configuración → Certificado desde tu cuenta.

¿Necesitas ayuda integrando el API? Escribinos a soporte@factuplan.com.ec o desde el Centro de ayuda.