Saltar al contenido principal

Casos de Uso

Lummy está diseñado para adaptarse a diferentes industrias y flujos de facturación. Aquí te mostramos los casos de uso más comunes y cómo implementarlos.

🛒 E-Commerce y Ventas Online​

Escenario​

Tienda online que vende productos a consumidores finales y empresas. Necesita generar facturas automáticamente después de cada compra.

Solución con Lummy​

  1. Cliente completa compra en tu sitio web
  2. Webhook de pago confirmado dispara integración con Lummy
  3. Tu backend llama a POST /invoices con datos del pedido
  4. Cliente recibe email con XML y PDF adjuntos

Ejemplo de Flujo​

// En tu webhook de confirmación de pago
app.post('/webhooks/payment-confirmed', async (req, res) => {
  const order = req.body;

  // Mapear pedido a estructura CFDI
  const invoice = {
    tipoDeComprobante: 'I',
    receptor: {
      rfc: order.customer.rfc,
      nombre: order.customer.name,
      regimenFiscal: order.customer.taxRegime,
      domicilioFiscal: order.customer.zipCode,
    },
    conceptos: order.items.map(item => ({
      descripcion: item.name,
      cantidad: item.quantity,
      valorUnitario: item.price,
      claveProdServ: item.satProductCode,
      // ... más campos
    })),
    // ... resto del CFDI
  };

  // Timbrar con Lummy
  const cfdi = await lummyClient.createInvoice(invoice);

  // Enviar email al cliente
  await sendInvoiceEmail(order.customer.email, cfdi.xmlS3Url, cfdi.pdfS3Url);
});

💼 SaaS y Subscripciones​

Escenario​

Plataforma SaaS con modelo de suscripciones mensuales. Necesita facturar automáticamente a cientos de clientes cada mes.

Solución con Lummy​

  • Facturas recurrentes: Cron job mensual genera facturas para todos los suscriptores activos
  • Pago diferido (PPD): Emite factura con método de pago PPD, luego emite Complemento de Pago 2.0 cuando se cobra

Ejemplo de Implementación​

# Job programado que corre el día 1 de cada mes
def facturar_suscripciones_mensuales():
    suscripciones_activas = db.get_active_subscriptions()

    for sub in suscripciones_activas:
        invoice_data = {
            "tipoDeComprobante": "I",
            "metodoPago": "PPD",  # Pago en Parcialidades o Diferido
            "formaPago": "99",    # Por definir (se especifica en Complemento)
            "receptor": {
                "rfc": sub.customer.rfc,
                "nombre": sub.customer.business_name,
                # ...
            },
            "conceptos": [{
                "descripcion": f"Suscripción {sub.plan_name} - {current_month}",
                "cantidad": 1,
                "valorUnitario": sub.plan_price,
                # ...
            }],
        }

        # Crear factura
        cfdi = lummy_client.create_invoice(invoice_data)

        # Guardar UUID para futura referencia en Complemento de Pago
        db.save_cfdi_uuid(sub.id, cfdi['cfdiUuid'])

🚚 Logística y Transporte​

Escenario​

Empresa de transporte que mueve mercancías entre estados. Debe emitir CFDIs de Traslado con Complemento Carta Porte 3.1.

Solución con Lummy​

Genera facturas tipo "T" (Traslado) con complemento de Carta Porte que incluye:

  • Origen y destino del transporte
  • Información del vehículo y remolques
  • Descripción de mercancías
  • Datos del operador y figuras de transporte

Ejemplo​

{
  "tipoDeComprobante": "T",
  "lugarExpedicion": "64000",
  "complementoCartaPorte": {
    "version": "3.1",
    "transporte": {
      "tipoTransporte": "Autotransporte",
      "vehiculoPrincipal": {
        "placaVM": "ABC1234",
        "anioModeloVM": 2020
      }
    },
    "ubicaciones": [
      {
        "tipoUbicacion": "Origen",
        "codigoPostal": "64000",
        "estado": "NLE"
      },
      {
        "tipoUbicacion": "Destino",
        "codigoPostal": "06500",
        "estado": "CMX"
      }
    ],
    "mercancias": {
      "mercancia": [{
        "descripcion": "Electrodomésticos",
        "cantidad": 50,
        "claveUnidad": "H87",
        "pesoEnKg": 500.00
      }]
    }
  }
}

🏪 Punto de Venta (POS)​

Escenario​

Retail físico que factura a público general y clientes registrados directamente en caja.

Solución con Lummy​

  1. Público General: Facturación global diaria/semanal/mensual
  2. Clientes Registrados: Factura individual inmediata

Facturación Global​

{
  "tipoDeComprobante": "I",
  "receptor": {
    "rfc": "XAXX010101000",  // Público en General
    "nombre": "PUBLICO EN GENERAL",
    "regimenFiscal": "616",
    "domicilioFiscal": "06500"
  },
  "informacionGlobal": {
    "periodicidad": "04",    // Mensual
    "meses": "01",           // Enero
    "anio": "2025"
  },
  "conceptos": [{
    "descripcion": "Venta",
    "cantidad": 1,
    "valorUnitario": 150000.00,  // Total agregado del mes
    // ...
  }]
}

🏢 ERP Empresarial​

Escenario​

Gran empresa con ERP (SAP, Oracle, Odoo) que necesita integrar facturación electrónica manteniendo su sistema actual.

Solución con Lummy​

  • Integración mediante API: Conecta tu ERP con Lummy sin modificar procesos internos
  • Webhooks: Recibe notificaciones de cancelaciones, ACK del SAT, etc.
  • Sellado Externo: Si tu empresa requiere sellar con HSM corporativo, usa endpoints de sellado externo

Arquitectura Sugerida​

┌─────────────┐
│   ERP SAP   │
│  (Sistema   │
│  Principal) │
└──────┬──────┘
       │
       │ (Eventos de factura)
       ▼
┌─────────────────┐
│  Microservicio  │ ←─── Lee datos del ERP
│  Integración    │
│  Lummy          │
└────────┬────────┘
         │
         │ API REST
         ▼
    ┌─────────┐
    │  Lummy  │ ←─── Timbrado y validación
    │   API   │
    └─────────┘

🔄 Marketplace Multi-Vendedor​

Escenario​

Plataforma que conecta múltiples vendedores con compradores. Cada vendedor necesita emitir sus propias facturas.

Solución con Lummy​

  • Multi-tenancy: Cada vendedor usa su propio organizationId y CSD
  • Facturación a cuenta de terceros: Soporte para nodo ACuentaTerceros
// Endpoint de tu plataforma
app.post('/api/sellers/:sellerId/invoices', async (req, res) => {
  const seller = await db.getSeller(req.params.sellerId);

  const invoice = await lummyClient.createInvoice({
    ...req.body,
    // Headers específicos del vendedor
  }, {
    headers: {
      'x-organization-id': seller.lummyOrgId,
      'x-api-key': seller.lummyApiKey,
      'x-idempotency': generateUUID(),
    },
  });

  res.json(invoice);
});

💳 Pasarelas de Pago​

Escenario​

Pasarela de pago que procesa miles de transacciones diarias y ofrece facturación como valor agregado.

Solución con Lummy​

  • Alto volumen: API diseñada para escalar horizontalmente
  • Idempotencia: Previene duplicados en reintentos de red
  • Webhooks: Notifica a tu sistema cuando el CFDI es cancelado

Próximos Pasos​