Referencia de API

Plan Business

Integre CleverInvo en su flujo de trabajo. Gestione clientes, cree facturas y descargue PDFs de forma programática.

Autenticación

Todas las solicitudes de API requieren un token Bearer. Cree una clave API desde su panel de control, luego inclúyala en el encabezado Authorization.

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

Clientes

GET/api/v1/clients

Listar todos los clientes activos. Soporta paginación y búsqueda.

Respuesta

{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/clients

Crear un nuevo cliente. Sujeto al límite de clientes de su plan.

Cuerpo de solicitud

{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}

Respuesta

{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

GET/api/v1/clients/:id

Obtener un solo cliente por ID.

Respuesta

{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

PUT/api/v1/clients/:id

Actualizar un cliente. Todos los campos pueden ser modificados.

Cuerpo de solicitud

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}

Respuesta

{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}

DELETE/api/v1/clients/:id

Eliminar suavemente un cliente. Establece isActive en false. Los clientes con facturas existentes no pueden ser eliminados definitivamente.

Respuesta

204 No Content

Facturas

GET/api/v1/invoices

Listar facturas. Soporta paginación, búsqueda y filtrado por clientId o estado.

Respuesta

{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/invoices

Crear una factura y generar automáticamente el PDF. Sujeto a los límites del plan.

Cuerpo de solicitud

{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}

Respuesta

{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}

GET/api/v1/invoices/:id

Obtener detalles completos de la factura incluyendo elementos de línea e información del cliente.

Respuesta

{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}

PUT/api/v1/invoices/:id

Actualizar una factura. Solo las facturas en borrador pueden ser modificadas.

Cuerpo de solicitud

{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}

Respuesta

{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}

DELETE/api/v1/invoices/:id

Eliminar permanentemente una factura y su PDF generado.

Respuesta

204 No Content

GET/api/v1/invoices/:id/pdf

Descargar la factura como archivo PDF. Devuelve PDF binario con encabezado Content-Disposition.

Respuesta

Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

Paginación

Los endpoints de lista aceptan los siguientes parámetros de consulta:

Parámetro	Predeterminado	Descripción
page	1	Número de página (mín: 1)
limit	20	Elementos por página (1–100)
search	—	Filtrar por nombre, correo electrónico o número de factura (máx 255 caracteres)
clientId	—	Filtrar facturas por cliente (solo facturas)
status	—	Filtrar por estado: DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE

GET /api/v1/clients?page=2&limit=10&search=acme

Errores

La API devuelve códigos de estado HTTP estándar. Las respuestas de error incluyen un cuerpo JSON con un campo error.

Estado	Descripción
400	Bad Request — parámetros inválidos o campos requeridos faltantes
401	Unauthorized — clave API inválida o faltante
403	Forbidden — límite del plan alcanzado (clientes, facturas o función)
404	Not Found — el recurso no existe o no es accesible
429	Too Many Requests — límite de velocidad excedido
500	Internal Server Error — fallo inesperado, intente de nuevo más tarde

{
  "error": "Missing required field: name"
}

Límites de velocidad

Las solicitudes de API están limitadas a 120 solicitudes por minuto por clave API.

Cuando se excede el límite, las solicitudes devuelven 429 Too Many Requests. Espere antes de reintentar.