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

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

  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

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

// 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: PROCESSING | AUTHORIZED | COMPLETED | ERROR | REJECTED

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, // nuevo secuencial
)

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

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

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

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

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

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

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

import { Factuplan } from 'factuplan';

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

// Emitir nota de crédito
// Si la factura original no está en el sistema, se importa automáticamente desde el SRI
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',
    },
  ],
});

console.log(creditNote.id);        // 'clx1234...'
console.log(creditNote.accessKey); // '0412202404...'
console.log(creditNote.status);    // 'PROCESSING'

// Consultar estado
const status = await factuplan.creditNotes.getStatus(creditNote.id);

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

{
  "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 }
  }
}

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

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)

const uso = await factuplan.usage()

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

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

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