Generar y Enviar Facturas con Stripe Billing

Concepto clave

En Stripe, las facturas son documentos que representan una transacción de pago entre tu negocio y un cliente. Piensa en ellas como los recibos digitales que envías después de cada ciclo de facturación, similar a la factura mensual de tu servicio de streaming. Estas facturas se generan automáticamente para suscripciones y se pueden personalizar con detalles como impuestos, descuentos o cargos adicionales.

El proceso de generación y envío se gestiona a través de las Billing APIs, que te permiten crear, modificar y enviar facturas programáticamente. Esto es crucial para automatizar la facturación recurrente, evitando errores manuales y asegurando que los clientes reciban sus documentos a tiempo. Una analogía del mundo real sería un sistema de facturación automatizado en una empresa de servicios, donde cada mes se generan facturas para todos los clientes activos sin intervención humana.

Cómo funciona en la práctica

El flujo básico para generar y enviar una factura con Stripe Billing implica varios pasos. Primero, necesitas un customer (cliente) registrado en Stripe, que puede tener una suscripción activa o ítems de facturación individuales. Luego, Stripe crea una invoice (factura) que agrupa todos los cargos pendientes para ese cliente. Finalmente, puedes enviar la factura al cliente por correo electrónico o a través de tu portal.

Aquí tienes un ejemplo paso a paso:

1. Crear un cliente en Stripe (si no existe).
2. Agregar ítems a la factura, como suscripciones o cargos únicos.
3. Generar la factura usando la API de invoices.
4. Finalizar la factura para que esté lista para el pago.
5. Enviar la factura al cliente mediante el método de envío automático o manual.

Este proceso se puede automatizar completamente usando webhooks para manejar eventos como invoice.created o invoice.payment_succeeded.

Codigo en accion

Veamos cómo generar una factura básica usando la API de Stripe en Node.js. Asegúrate de tener instalado el SDK de Stripe (npm install stripe).

const stripe = require('stripe')('sk_test_tu_clave_secreta');

async function createInvoice(customerId, subscriptionId) {
    try {
        // Crear una factura para el cliente
        const invoice = await stripe.invoices.create({
            customer: customerId,
            subscription: subscriptionId,
            auto_advance: true // Finaliza automáticamente la factura
        });
        
        console.log('Factura creada:', invoice.id);
        return invoice;
    } catch (error) {
        console.error('Error al crear la factura:', error);
        throw error;
    }
}

// Ejemplo de uso
// createInvoice('cus_ABC123', 'sub_XYZ789');

Ahora, mejoremos el código para incluir el envío de la factura y manejo de errores más robusto.

const stripe = require('stripe')('sk_test_tu_clave_secreta');

async function createAndSendInvoice(customerId, subscriptionId) {
    try {
        // Paso 1: Crear la factura
        const invoice = await stripe.invoices.create({
            customer: customerId,
            subscription: subscriptionId,
            auto_advance: false // Control manual para finalizar
        });
        
        // Paso 2: Finalizar la factura
        const finalizedInvoice = await stripe.invoices.finalizeInvoice(invoice.id);
        
        // Paso 3: Enviar la factura por correo
        const sentInvoice = await stripe.invoices.sendInvoice(finalizedInvoice.id);
        
        console.log('Factura enviada:', sentInvoice.id);
        return sentInvoice;
    } catch (error) {
        if (error.type === 'StripeInvalidRequestError') {
            console.error('Error en la solicitud:', error.message);
        } else {
            console.error('Error inesperado:', error);
        }
        throw error;
    }
}

// Ejemplo de uso
// createAndSendInvoice('cus_ABC123', 'sub_XYZ789');

Errores comunes

• No verificar el estado del cliente: Intentar crear una factura para un cliente que no existe o está inactivo resultará en un error. Siempre valida que el customerId sea válido antes de proceder.
• Olvidar finalizar la factura: Una factura creada pero no finalizada no se puede pagar ni enviar. Usa finalizeInvoice o establece auto_advance: true para automatizar este paso.
• Manejo inadecuado de webhooks: No configurar webhooks para eventos como invoice.payment_failed puede llevar a facturas impagas no gestionadas. Implementa lógica para reintentos o notificaciones.
• Errores de formato en los datos: Pasar parámetros incorrectos, como un monto negativo en los ítems de la factura, causará fallos. Revisa la documentación de Stripe para los tipos de datos esperados.
• No probar en modo test: Usar claves de producción durante el desarrollo puede generar facturas reales. Siempre utiliza sk_test_ para pruebas.

Checklist de dominio

• Puedo crear una factura básica usando la API de Stripe con código funcional.
• Sé cómo agregar ítems personalizados (como descuentos o impuestos) a una factura.
• He implementado el envío automático de facturas mediante webhooks o programación directa.
• Puedo manejar errores comunes, como facturas fallidas o clientes no válidos.
• He probado el flujo completo en modo test sin generar cargos reales.
• Sé cómo personalizar el contenido de las facturas (por ejemplo, agregar un logo o detalles de contacto).
• Puedo integrar la generación de facturas con un sistema backend existente.

Implementa un sistema de facturación recurrente con Stripe

En este ejercicio, crearás un endpoint backend que genere y envíe facturas automáticamente para suscripciones mensuales. Sigue estos pasos:

1. Configura un proyecto Node.js con el SDK de Stripe y crea una ruta POST /create-invoice.
2. En la ruta, recibe un customerId y subscriptionId desde el cuerpo de la solicitud.
3. Usa la API de Stripe para crear una factura para ese cliente y suscripción, asegurándote de finalizarla.
4. Envía la factura al cliente utilizando el método sendInvoice.
5. Agrega manejo de errores para casos como IDs inválidos o fallos en la red.
6. Prueba tu endpoint con datos de prueba de Stripe y verifica que la factura llegue al correo del cliente de prueba.

Entrega el código completo de tu endpoint y una captura de pantalla del correo de factura recibido.

• Usa el paquete express para crear el servidor y manejar rutas.
• Recuerda que debes usar claves de prueba (sk_test_) para evitar cargos reales.
• Consulta la documentación de Stripe para los parámetros exactos de invoices.create.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.