Integración completa de Verifactu en tu e-commerce con Node.js

Desde la instalación del SDK hasta la generación automática de facturas y manejo de errores.

Tutorial 12 Enero 2025 12 min lectura
← Volver al Blog Ver Documentación

Requisitos previos

  • Node.js 18+ y npm/yarn.
  • Cuenta en Verifactu-API y API Key.
  • Entorno de pruebas (sandbox) configurado.

Instalación del SDK

# npm
yarn add @verifactu/sdk

# o npm
npm install @verifactu/sdk

Configuración básica

import { VerifactuAPI } from '@verifactu/sdk';

export const verifactu = new VerifactuAPI(process.env.VERIFACTU_API_KEY, {
  environment: 'sandbox',
  timeout: 10000
});

Creación de factura tras compra

// ejemplo con Express
app.post('/checkout/success', async (req, res) => {
  const { pedido, cliente } = req.body;
  try {
    const factura = await verifactu.facturas.crear({
      emisor: { nif: 'B00000000' },
      receptor: { nif: cliente.nif, nombre: cliente.nombre },
      lineas: pedido.items.map(i => ({ concepto: i.nombre, cantidad: i.qty, precio: i.precio })),
      fecha: new Date().toISOString()
    });
    // guardar factura.id en tu DB
    res.json({ ok: true, facturaId: factura.id, qr: factura.qr });
  } catch (e) {
    console.error(e);
    res.status(500).json({ ok:false });
  }
});

Manejo de errores e idempotencia

import crypto from 'node:crypto';

function idempotencyKey(pedidoId){
  return crypto.createHash('sha1').update('pedido:'+pedidoId).digest('hex');
}

const factura = await verifactu.facturas.crear(payload, {
  idempotencyKey: idempotencyKey(pedido.id)
});

Pruebas en sandbox

  • Utiliza NIFs de prueba y valida respuestas.
  • Activa logs detallados y revisa latencia.
  • Verifica el QR y los estados de presentación.

Recursos

• Probar en Playground
• Documentación
• Precios

¿Por qué usar la Verifactu API en e-commerce?

La Verifactu API se integra directamente en tu checkout y backoffice para generar y presentar facturas sin fricción. Con la API Verifactu reduces errores, automatizas tareas repetitivas y aceleras el cierre contable.

Flujo recomendado

Checkout -> Pedido pagado -> Evento (cola) -> Worker
Worker -> API Verifactu -> Guarda factura y QR -> Notifica al cliente
Webhooks -> Sincronizan estados (aceptada, rechazada, enviada)

Seguridad y cumplimiento

  • Verifica la firma de webhooks (cabecera y cuerpo crudo).
  • RGPD: minimiza datos personales y cifra secretos.
  • Observabilidad: registra id, estado y latencia por factura.
  • Idempotencia: evita duplicados con idempotencyKey.

Errores comunes

  • 422 Validación del receptor: normaliza NIF y nombre.
  • 409 Duplicado: usa claves idempotentes por pedido.
  • 401 Webhook: comprueba la firma antes del parseo.

FAQs

¿Sirve para tiendas multinodo o marketplaces?

Sí. Aísla credenciales por vendedor y controla límites por tenant.

¿Puedo enviar la factura y el QR por email?

Incluye el QR devuelto por la API Verifactu en tu plantilla transaccional.

Enlaces internos recomendados