SDK TypeScript para facturación electrónica en Ecuador (SRI)

import { Factuplan } from "factuplan"

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

const factura = await factuplan.invoices.create({
  customer: {
    identificationType: "RUC",
    identification: "0993378150001",
    legalName: "Cliente S.A.",
    email: "facturas@cliente.ec",
  },
  items: [
    {
      code: "SERV-001",
      description: "Servicio de consultoría",
      quantity: 1,
      unitPrice: 150,
      taxType: "IVA_RATE",
      tax: 15,
    },
  ],
  sendEmail: true,
})

console.log(factura.accessKey) // 49 dígitos de clave de acceso SRI

import { Factuplan } from "factuplan"

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

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

const usage = await factuplan.usage.current()
console.log(usage.invoicesUsed, "/", usage.invoicesLimit)

import { Factuplan } from "factuplan"

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

const factura = await factuplan.invoices.create({
  customer: {
    identificationType: "RUC",
    identification: "0993378150001",
    legalName: "Empresa Demo S.A.",
    email: "facturas@empresademo.ec",
    saveToContacts: true,
  },
  items: [
    {
      code: "SERV-001",
      description: "Servicio de consultoría técnica",
      quantity: 1,
      unitPrice: 150,
      taxType: "IVA_RATE",
      tax: 15,
    },
  ],
  sendEmail: true,
})

console.log("Clave de acceso SRI:", factura.accessKey)
console.log("RIDE PDF:", factura.pdfUrl)

factuplan.invoices.create(...)
factuplan.invoices.get(id)
factuplan.invoices.list({ page, limit, search })
factuplan.invoices.void(id, { reason }) // anular

const factura = await factuplan.invoices.create({
  customer: {
    identificationType: "DNI", // ❌ Error TS: Type "DNI" is not assignable
    // El SDK solo acepta "RUC" | "CEDULA" | "PASSPORT" | "FINAL_CONSUMER"
    identification: "0993378150001",
    legalName: "Empresa Demo S.A.",
  },
  // ...
})

const factura = await factuplan.invoices.create({ /* ... */ })

// factura es typed: tiene id, accessKey, pdfUrl, xmlUrl, status, etc.
const status: "PENDING" | "AUTHORIZED" | "REJECTED" = factura.status

// Punto de emisión: 3 formas mutuamente excluyentes
type EmissionPoint =
  | { emissionPointId: string }                          // Por UUID
  | { establishment: string; emissionPoint: string }     // Por códigos SRI
  | {}                                                    // Auto-detect

const factura = await factuplan.invoices.create({
  emissionPointId: "ep_id_123",  // ✓ válido
  // o
  // establishment: "001", emissionPoint: "001", // ✓ válido
  // o
  // (nada) // ✓ auto-detecta si solo hay un punto activo
  // ...
})

// Crear
const cliente = await factuplan.customers.create({
  identificationType: "RUC",
  identification: "0993378150001",
  legalName: "Empresa Demo S.A.",
  email: "facturas@empresademo.ec",
})

// Listar con paginación
const { data: clientes, meta } = await factuplan.customers.list({
  page: 1,
  limit: 20,
  search: "empresa",
})

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

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

// Eliminar
await factuplan.customers.delete("cust_id")

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

const factura = await factuplan.invoices.create({ /* ... */ })

// Anular (emite nota de crédito reversiva)
await factuplan.invoices.void(factura.id, {
  reason: "Error en datos del cliente",
})

const notaCredito = await factuplan.creditNotes.create({
  customer: { /* ... */ },
  items: [ /* ... */ ],
  referenceDocument: {
    accessKey: "1305202401099337815000110010010000056781234567811",
    type: "INVOICE",
    date: "2026-05-13",
  },
  reason: "Devolución parcial de mercadería",
})

const guia = await factuplan.waybills.create({
  carrier: {
    identification: "0950194407001",
    legalName: "Transportes Demo S.A.",
    licensePlate: "ABC-1234",
  },
  // ...
})

import {
  Factuplan,
  FactuplanError,
  FactuplanValidationError,
  FactuplanAuthError,
  FactuplanRateLimitError,
  FactuplanSRIError,
} from "factuplan"

try {
  const factura = await factuplan.invoices.create({ /* ... */ })
} catch (err) {
  if (err instanceof FactuplanValidationError) {
    // 400/422 — datos inválidos
    console.error("Validación:", err.code, err.details)
  } else if (err instanceof FactuplanAuthError) {
    // 401 — API key inválida o expirada
    console.error("Autenticación falló")
  } else if (err instanceof FactuplanRateLimitError) {
    // 429 — cuota mensual o rate limit
    console.error("Reintenta en:", err.retryAfter, "segundos")
  } else if (err instanceof FactuplanSRIError) {
    // 422 con código del SRI — rechazo de la autoridad fiscal
    console.error("SRI rechazó:", err.sriCode, err.sriMessage)
  } else if (err instanceof FactuplanError) {
    // Cualquier otro error de la API
    console.error("Error:", err.statusCode, err.code, err.message)
  } else {
    // Error no relacionado al SDK (red, etc.)
    throw err
  }
}

const factuplan = new Factuplan(apiKey, {
  ruc: "0950194407001",
  retries: 5,                // default 3
  retryDelay: 1000,          // ms base, default 500
  retryMaxDelay: 30000,      // ms tope, default 10000
})

import { Factuplan } from "factuplan"

// Express/Next.js handler
app.post("/webhooks/factuplan", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-factuplan-signature"] as string

  try {
    const event = Factuplan.webhooks.constructEvent(
      req.body,
      signature,
      process.env.FACTUPLAN_WEBHOOK_SECRET!,
    )

    switch (event.type) {
      case "invoice.authorized":
        // event.data es Invoice
        console.log("Factura autorizada:", event.data.accessKey)
        break
      case "invoice.rejected":
        console.log("Rechazada por SRI:", event.data.sriError)
        break
      // ...
    }

    res.json({ received: true })
  } catch (err) {
    res.status(400).send("Webhook signature inválida")
  }
})