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()
console.log(usage) // la API responde { currentMonth: { documents, cost }, plan, monthlyQuota, monthlyUsed }

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("Estado:", factura.status) // DRAFT: la emisión sigue en segundo plano

// El enlace al RIDE se pide aparte, cuando la factura ya está en COMPLETED:
// const { url } = await factuplan.invoices.downloadPdf(factura.id)

factuplan.invoices.create(...)
factuplan.invoices.get(id)
factuplan.invoices.list({ page, limit, status, devReference })
factuplan.invoices.void(id, reason) // anular (solo en Factuplan, no ante el SRI)

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" | "EXTERIOR"
    identification: "0993378150001",
    legalName: "Empresa Demo S.A.",
    email: "facturas@empresademo.ec",
  },
  // ...
})

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

// factura es typed: tiene id, accessKey, sequential, status, total y, si enviaste devReference, devReference y duplicate
const status: string = factura.status // "DRAFT" al crear; termina en "COMPLETED" (o REJECTED / RETURNED / ERROR)

// Punto de emisión: 3 formas de indicarlo. El SDK no las modela como unión: son tres campos
// opcionales y la combinación la valida la API (400 si falta uno de los dos códigos).
// Conceptualmente:
type EmissionPoint =
  | { emissionPointId: string }                          // Por UUID
  | { establishment: string; emissionPoint: string }     // Por códigos SRI
  | {}                                                    // Auto-detect

const factura = await factuplan.invoices.create({
  emissionPointId: "0199c2d4-5d21-7e0b-a4c8-9b1f3e7d2a60",  // ✓ 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 guardado = await factuplan.customers.get(cliente.id)

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

// Eliminar (lo desactiva: isActive pasa a false)
await factuplan.customers.delete(cliente.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: marca la factura como VOIDED en Factuplan. No emite nota de crédito
// ni la anula ante el SRI: eso lo haces tú (por ejemplo con creditNotes.create).
// Solo se puede anular una factura en AUTHORIZED o COMPLETED.
await factuplan.invoices.void(factura.id, "Error en datos del cliente")

const notaCredito = await factuplan.creditNotes.create({
  invoiceAccessKey: "1305202401099337815000110010010000056781234567811", // clave de acceso de la factura autorizada
  reason: "Devolución parcial de mercadería",
  items: [ /* ... */ ],
  devReference: "nc-pedido-1001", // opcional: hace idempotente la emisión
})

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

try {
  const factura = await factuplan.invoices.create({ /* ... */ })
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401 — API key inválida, revocada o expirada
    console.error("Autenticación falló")
  } else if (err instanceof RateLimitError) {
    // 429 — superaste el límite de peticiones: espera y repite la misma petición
    console.error("Límite alcanzado:", err.message)
  } else if (err instanceof FactuplanError) {
    // Cualquier otro error de la API: 400 validación (GENERAL_0002),
    // 403 plan o cupo, 409 devReference (API_10011 / API_10012), 5xx…
    console.error("Error:", err.statusCode, err.code, err.message, err.details)
  } else {
    // Error no relacionado al SDK (red, timeout a los 30 s, etc.)
    throw err
  }
  // Un rechazo del SRI no llega aquí: la emisión es asíncrona y aparece
  // después como estado REJECTED / RETURNED o en el webhook invoice.rejected.
}

import { Factuplan, FactuplanError, RateLimitError, type CreateInvoiceInput } from "factuplan"

const factuplan = new Factuplan(apiKey, {
  ruc: "0950194407001",
  timeout: 30000, // ms, default 30000
})

async function emitirConReintentos(payload: CreateInvoiceInput, devReference: string) {
  for (let intento = 1; ; intento++) {
    try {
      // El mismo contenido y la MISMA devReference en cada intento
      return await factuplan.invoices.create({ ...payload, devReference })
    } catch (err) {
      const temporal =
        err instanceof RateLimitError || // 429 por límite de peticiones
        !(err instanceof FactuplanError) || // red o timeout: no llegó ninguna respuesta
        err.statusCode >= 500 ||
        err.statusCode === 408
      if (!temporal || intento === 5) throw err // 400, 401, 403, 409… no cambian al repetir
      await new Promise((r) => setTimeout(r, 1000 * 2 ** (intento - 1)))
    }
  }
}

const factura = await emitirConReintentos(payload, "pedido-1001")
if (factura.duplicate) {
  // Un intento anterior sí llegó: no se emitió nada nuevo.
  // Mira factura.status para saber en qué quedó.
}

import { verifyWebhookSignature } from "factuplan"

// Express/Next.js handler
app.post("/webhooks/factuplan", express.raw({ type: "application/json" }), (req, res) => {
  const valida = verifyWebhookSignature(
    req.body, // Buffer crudo
    req.headers["x-factuplan-signature"],
    process.env.FACTUPLAN_WEBHOOK_SECRET!,
  )

  if (!valida) {
    res.status(400).send("Webhook signature inválida")
    return
  }

  const event = JSON.parse(req.body.toString("utf-8"))

  switch (event.event) {
    case "invoice.authorized":
      // event.data: receiptId, type, accessKey, authorizationNumber, documentNumber, total…
      console.log("Factura autorizada:", event.data.accessKey)
      break
    case "invoice.rejected":
      console.log("Rechazada por SRI:", event.data.reason)
      break
    // ...
  }

  res.json({ received: true })
})