Como automatizar la facturacion con la API de CleverInvo

Si envias mas de unas pocas facturas al mes, probablemente has deseado poder automatizar el proceso. La API de CleverInvo lo hace posible. Esta guia cubre los fundamentos: autenticacion, creacion de clientes, generacion de facturas y configuracion de webhooks.

---

Requisitos previos

La API esta disponible en el plan Business. Necesitaras:

1. Una cuenta CleverInvo en el plan Business
2. Una clave API (generala desde Panel > Claves API)
3. Familiaridad basica con APIs REST y JSON

URL base:

https://cleverinvo.com/api/v1

Autenticacion

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients

---

Gestion de clientes

Crear un cliente

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporacion Acme",
    "email": "[email protected]",
    "address": "Calle Negocios 123\nMadrid, 28001",
    "taxId": "ES-B12345678",
    "phone": "+34-91-123-4567"
  }'

Listar clientes

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

---

Creacion de facturas

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "EUR",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "Rediseno de sitio web - Fase 1",
        "quantity": 1,
        "unitPrice": 5000.00
      },
      {
        "description": "Desarrollo frontend",
        "quantity": 40,
        "unitPrice": 150.00
      }
    ],
    "notes": "Gracias por su confianza.",
    "terms": "Pago a 30 dias. Interes del 1.5% mensual en pagos atrasados."
  }'

El sistema automaticamente:

• Asigna el siguiente numero secuencial
• Calcula totales de linea, subtotal y total
• Genera el PDF y devuelve la URL
• Establece el estado en DRAFT

Factura con impuestos

{
  "lineItems": [
    {
      "description": "Servicios de consultoria",
      "quantity": 20,
      "unitPrice": 200.00,
      "taxRate": 21
    }
  ]
}

---

Gestion del estado de facturas

# Marcar como enviada
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# Marcar como pagada
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

---

Patrones de integracion comunes

Patron 1: CRM a factura

async function onDealClosed(deal) {
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
    });
  }

  await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });
}

Patron 2: Facturacion mensual de retencion

async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "EUR",
        lineItems: [
          {
            description: `Retencion mensual - ${format(today, "MMMM yyyy")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
      });
    }
  }
}

---

Limites de tasa

Plan	Limite
Business	100 solicitudes por minuto

---

Manejo de errores

Codigo	HTTP	Significado
UNAUTHORIZED	401	Clave API invalida o faltante
FORBIDDEN	403	API no disponible en tu plan
NOT_FOUND	404	Recurso no existe
VALIDATION_ERROR	422	Datos de solicitud invalidos
RATE_LIMITED	429	Demasiadas solicitudes
INTERNAL_ERROR	500	Error del servidor

---

Siguientes pasos

La documentacion completa esta disponible en /docs/api.

Obtiene tu clave API ->