SDK para Node.js

import { Factuplan } from "factuplan"

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

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

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

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

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

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

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

await factuplan.customers.delete("cust_id")

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
})

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")

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

  // Cliente: sus datos en línea, o { customerId: "cust_id" } si ya lo creaste
  customer: {
    identificationType: "RUC",
    identification: "0993378150001",
    legalName: "Cliente S.A.",
    email: "facturas@cliente.ec",
    saveToContacts: true,
  },
  // Ítems: sus datos en línea, o { productId: "prod_id", quantity: 1 } para
  // usar un producto de tu catálogo (toma su código, nombre, precio e impuesto)
  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. Con false no se envía el correo; la factura igual termina en COMPLETED
  // devReference: "pedido-1001",  // opcional: tu propia referencia (1 a 100 caracteres); hace idempotente la emisión
})

console.log(factura.id) // ID interno
console.log(factura.accessKey) // Clave de acceso SRI (49 dígitos)
console.log(factura.sequential) // Secuencial del comprobante
console.log(factura.duplicate) // Solo si enviaste devReference: true si ya existía un comprobante con esa referencia

// customer, items y payments: los mismos objetos del ejemplo de "Crear factura"
// 1) Por UUID (referencia directa)
factuplan.invoices.create({ emissionPointId: "ep_id", customer, items, payments })

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

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

// 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,
  },
]

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

const estado = await factuplan.invoices.getStatus("factura_id")
// estado.status termina en COMPLETED | ERROR | REJECTED (o VOIDED si lo anulas).
// Mientras tanto pasa por DRAFT | PROCESSING | GENERATING_XML | SIGNING | SENDING_SRI |
// RECEIVED_SRI | AUTHORIZED | GENERATING_PDF | SENDING_EMAIL.
// AUTHORIZED es un estado de paso: el SRI ya autorizó, pero el PDF puede no estar listo.

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

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

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

// 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

const result = await factuplan.invoices.void(
  "factura_id",
  "Error en los datos del cliente",
)

console.log(result.status) // "VOIDED"
console.log(result.voidReason) // Motivo ingresado
console.log(result.message) // Confirmación

const result = await factuplan.invoices.updateSequential(
  "001", // branchCode — código del establecimiento
  "001", // emissionCode — código del punto de emisión
  100, // último secuencial usado: la próxima factura será la 101
)

console.log(result.invoiceSequential) // 100
console.log(result.updatedAt) // ISO 8601

import { Factuplan } from "factuplan"
import { readFileSync } from "fs"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001", // contribuyente con cuyo certificado se firma
})

const xml = readFileSync("./factura-sin-firmar.xml", "utf-8")

const result = await factuplan.invoices.signAndAuthorize({ xml })

console.log(result.authorized)          // true si el SRI autorizó el comprobante
console.log(result.authorizationNumber) // Número de autorización del SRI (o null)
console.log(result.authorizationDate)   // Fecha de autorización (o null)
console.log(result.messages)            // Mensajes del SRI; los motivos si no autorizó
// Si el SRI no lo autorizó, no se descuenta ningún documento de tu plan.

// La respuesta ya es la del SRI: este modo no guarda el comprobante en Factuplan,
// así que no hay id, ni estado que consultar, ni PDF (RIDE) que descargar.
if (result.authorized && result.authorizedXml) {
  // XML autorizado, en base64. Guárdalo en tu sistema.
  const xmlAutorizado = Buffer.from(result.authorizedXml, "base64").toString("utf-8")
  console.log("XML autorizado:", xmlAutorizado)
}

import { Factuplan } from 'factuplan';

const factuplan = new Factuplan('ak_live_...', { ruc: '0950194407001' });

// Emitir nota de crédito
// La factura original debe existir en Factuplan (mismo contribuyente) en estado
// AUTHORIZED o COMPLETED; si no, la API responde 400 con el código CN_5001.
// Si se emitió en otro sistema, impórtala antes con invoices.importByAccessKey.
const creditNote = await factuplan.creditNotes.create({
  invoiceAccessKey: '2312202301179214289100110010020000001231234567811',
  reason: 'Error en datos del cliente',
  items: [
    {
      code: 'SERV-001',
      description: 'Servicio de desarrollo web',
      quantity: 1,
      unitPrice: 100.00,
      taxType: 'IVA_RATE',
    },
  ],
  // devReference: 'nc-1001',  // opcional: tu propia referencia; hace idempotente la emisión
});

console.log(creditNote.id);        // '0199c2f4-7b1e-7c3a-9f2d-5a6b7c8d9e0f'
console.log(creditNote.accessKey); // '0412202404...'
console.log(creditNote.status);    // 'DRAFT'

// Consultar estado: espera a que termine (COMPLETED, ERROR o REJECTED).
// Mientras está en proceso, el XML o el PDF pueden no existir todavía (404), y solo se puede anular en AUTHORIZED o COMPLETED (400 en otro estado).
let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = await factuplan.creditNotes.getStatus(creditNote.id);
} while (!['COMPLETED', 'ERROR', 'REJECTED'].includes(status.status));

// Descargar XML y PDF
const xml = await factuplan.creditNotes.downloadXml(creditNote.id);
const pdf = await factuplan.creditNotes.downloadPdf(creditNote.id);

// Anular (solo a nivel del sistema — la anulación ante el SRI es tu responsabilidad)
const voided = await factuplan.creditNotes.void(creditNote.id, 'Error en precio');

import { Factuplan } from "factuplan"
import { readFileSync } from "fs"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001", // contribuyente con cuyo certificado se firma
})

const xml = readFileSync("./nota-credito-sin-firmar.xml", "utf-8")
const result = await factuplan.invoices.signAndAuthorize({ xml })

console.log(result.authorized)          // true si el SRI autorizó la nota de crédito
console.log(result.authorizationNumber) // Número de autorización del SRI (o null)
console.log(result.messages)            // Mensajes del SRI; los motivos si no autorizó

import { Factuplan } from 'factuplan';

const factuplan = new Factuplan('ak_live_...', { ruc: '0950194407001' });

// La factura original debe existir en Factuplan (mismo contribuyente) en estado
// AUTHORIZED o COMPLETED; si no, la API responde 400 con el código DN_5101.
const debitNote = await factuplan.debitNotes.create({
  invoiceAccessKey: '2312202301179214289100110010020000001231234567811',
  reasons: [
    {
      description: 'Ajuste por flete no facturado',
      amount: 25.00,
      taxType: 'IVA_RATE', // IVA_RATE (15%) | IVA_0 | NOT_TAXABLE | EXEMPT
    },
  ],
  // additionalInfo: { Referencia: 'OC-4521' },  // opcional
  // devReference: 'nd-1001',  // opcional: tu propia referencia; hace idempotente la emisión
})

console.log(debitNote.id);        // '0199c2f4-7b1e-7c3a-9f2d-5a6b7c8d9e0f'
console.log(debitNote.accessKey); // '0412202405...'
console.log(debitNote.status);    // 'DRAFT'

const status = await factuplan.debitNotes.getStatus(debitNote.id);
// status.status termina en COMPLETED | ERROR | REJECTED (o VOIDED si la anulas); cualquier otro valor es un estado de paso

const { url: xmlUrl } = await factuplan.debitNotes.downloadXml(debitNote.id);
const { url: pdfUrl } = await factuplan.debitNotes.downloadPdf(debitNote.id);

const { data: debitNotes, meta } = await factuplan.debitNotes.list({
  status: 'COMPLETED',
  page: 1,
  limit: 20,
})

const voided = await factuplan.debitNotes.void(debitNote.id, 'Emitida por error');

import { Factuplan } from "factuplan"
import { readFileSync } from "fs"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001", // contribuyente con cuyo certificado se firma
})

const xml = readFileSync("./nota-debito-sin-firmar.xml", "utf-8")
const result = await factuplan.invoices.signAndAuthorize({ xml })

console.log(result.authorized)          // true si el SRI autorizó la nota de débito
console.log(result.authorizationNumber) // Número de autorización del SRI (o null)
console.log(result.messages)            // Mensajes del SRI; los motivos si no autorizó

import { Factuplan } from "factuplan"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001", // RUC del contribuyente que retiene
})

// Clave de acceso (49 dígitos) de la factura que te emitió tu proveedor
const claveCompra = "0109202601179214673900110020010000000011234567815"

// 1. Registrar la compra.
// Si ya estaba registrada responde 400 (PU_5504): en ese caso salta este paso.
await factuplan.purchases.register(claveCompra)

// 2. Emitir la retención sobre esa compra.
// Si la compra no está registrada, la API responde 404 con el código WH_5304.
const retencion = await factuplan.withholdings.create({
  purchaseAccessKey: claveCompra,
  codSustento: "01", // Código de sustento del SRI (Tabla 5)
  taxes: [
    {
      taxType: "RENTA", // RENTA | IVA | ISD
      taxRateCode: "303", // Código de retención del SRI para ese impuesto
      taxRate: 10, // Porcentaje de retención (0 a 100)
      taxBase: 100.0, // Base imponible, mayor que 0
    },
  ],
  // fiscalPeriod: "09/2026",  // opcional (MM/AAAA); por defecto, el mes de emisión de la compra
  // devReference: "ret-1001",  // opcional: tu propia referencia; hace idempotente la emisión
})

console.log(retencion.id) // ID interno
console.log(retencion.accessKey) // Clave de acceso SRI (49 dígitos)
console.log(retencion.status) // 'DRAFT'
console.log(retencion.totalWithheld) // Total retenido

import { Factuplan } from "factuplan"
import { readFileSync } from "fs"

const factuplan = new Factuplan(process.env.FACTUPLAN_API_KEY!, {
  ruc: "0950194407001", // contribuyente con cuyo certificado se firma
})

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

console.log(result.authorized)          // true si el SRI autorizó la retención
console.log(result.authorizationNumber) // Número de autorización del SRI (o null)
console.log(result.messages)            // Mensajes del SRI; los motivos si no autorizó

const factura = await factuplan.invoices.create({
  customer,
  items,
  payments,
  devReference: "pedido-1001",
})

console.log(factura.devReference) // "pedido-1001"
console.log(factura.duplicate) // false: se emitió ahora · true: ya existía y no se emitió otro

// ¿No sabes si una emisión llegó a registrarse (por ejemplo, tras un timeout)?
// Búscala por su referencia: devuelve cero o un comprobante.
const { data } = await factuplan.invoices.list({ devReference: "pedido-1001" })
console.log(data[0]?.id, data[0]?.status)

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

try {
  await factuplan.invoices.create({ customer, items, payments })
} 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_4014"
    console.error(error.message)
    console.error(error.statusCode) // ej. 400
    console.error(error.details)
  }
}

{
  "data": null,
  "meta": {
    "requestId": "0f8b6c1e-5d2a-4a7e-9c3b-2f1d6e8a4b70",
    "timestamp": "2026-01-15T15:04:05.000Z"
  },
  "error": {
    "code": "GENERAL_0003",
    "message": "Has superado el límite de peticiones. Intenta de nuevo en unos segundos.",
    "statusCode": 429,
    "details": {
      "message": "Has superado el límite de peticiones. Intenta de nuevo en unos segundos."
    }
  }
}

{
  "data": null,
  "meta": {
    "requestId": "0f8b6c1e-5d2a-4a7e-9c3b-2f1d6e8a4b70",
    "timestamp": "2026-01-15T15:04:05.000Z"
  },
  "error": {
    "code": "API_10002",
    "message": "Has alcanzado el límite mensual de 500 documentos.",
    "statusCode": 429,
    "details": {
      "message": "Has alcanzado el límite mensual de 500 documentos.",
      "used": 500,
      "quota": 500
    }
  }
}

import { RateLimitError } from "factuplan"

// `datos` debe incluir tu propio `devReference` (por ejemplo, tu número de pedido):
// si repites la petición con la misma referencia y el mismo contenido, la API
// responde con el comprobante que ya existe (`duplicate: true`) y no emite otro.
// El SDK no reintenta por su cuenta y corta cada petición a los 30 s.
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
      }
    }
  }
}

// rawBody: el cuerpo tal como llegó, sin parsear (string o Buffer).
// signature: el valor del header X-Factuplan-Signature.
function esDeFactuplan(
  rawBody: string | Buffer,
  signature: string | string[] | undefined,
) {
  return factuplan.webhooks.verifySignature(
    rawBody,
    signature,
    process.env.FACTUPLAN_WEBHOOK_SECRET!, // el secreto whsec_... de tu webhook
  )
}

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

// Devuelve null si el comprobante no existe o si la consulta falla
// (por ejemplo, si el cliente del SDK no tiene `ruc` configurado).
if (receipt) {
  console.log(receipt.id)
  console.log(receipt.status) // Mismos estados que invoices.getStatus; COMPLETED al terminar
  console.log(receipt.accessKey) // Clave de acceso SRI (49 dígitos)
}

const uso = await factuplan.usage()

console.log(uso.currentMonth.documents, "operaciones este mes")
console.log("Costo estimado: $" + uso.currentMonth.cost)
console.log(uso.monthlyUsed, "/", uso.monthlyQuota ?? "sin cuota propia")

const cert = await factuplan.certificates.status()

console.log(cert.hasCertificate) // true = hay un certificado cargado
console.log(cert.isExpired) // true = el certificado ya venció
console.log(cert.daysUntilExpiry) // Días que faltan para el vencimiento
console.log(cert.expiresAt) // Fecha de vencimiento (ISO 8601)
console.log(cert.ruc) // RUC del titular
console.log(cert.legalName) // Nombre registrado en el certificado

import { readFileSync } from "fs"

const p12 = readFileSync("./mi-firma.p12")
const result = await factuplan.certificates.upload(p12, "mi-contraseña")

console.log(result.ruc) // RUC extraído del certificado
console.log(result.legalName) // Nombre legal
console.log(result.expiresAt) // Fecha de vencimiento
console.log(result.created) // true si se creó un nuevo contribuyente