API-Referenz

Business-Plan

Integrieren Sie CleverInvo in Ihren Workflow. Verwalten Sie Kunden, erstellen Sie Rechnungen und laden Sie PDFs programmatisch herunter.

Authentifizierung

Alle API-Anfragen erfordern ein Bearer-Token. Erstellen Sie einen API-Schlüssel in Ihrem Dashboard und fügen Sie ihn dann im Authorization-Header ein.

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

Kunden

GET/api/v1/clients

Alle aktiven Kunden auflisten. Unterstützt Paginierung und Suche.

Antwort
{
  "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

Einen neuen Kunden erstellen. Unterliegt dem Kundenlimit Ihres Plans.

Anfragekörper
{
  "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"
}
Antwort
{
  "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

Einen einzelnen Kunden nach ID abrufen.

Antwort
{
  "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

Einen Kunden aktualisieren. Alle Felder können geändert werden.

Anfragekörper
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
Antwort
{
  "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

Einen Kunden soft-löschen. Setzt isActive auf false. Kunden mit bestehenden Rechnungen können nicht endgültig gelöscht werden.

Antwort
204 No Content

Rechnungen

GET/api/v1/invoices

Rechnungen auflisten. Unterstützt Paginierung, Suche und Filterung nach clientId oder Status.

Antwort
{
  "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

Eine Rechnung erstellen und das PDF automatisch generieren. Unterliegt den Plan-Limits.

Anfragekörper
{
  "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"
}
Antwort
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

Vollständige Rechnungsdetails einschließlich Positionen und Kundeninformationen abrufen.

Antwort
{
  "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

Eine Rechnung aktualisieren. Nur Entwurfsrechnungen können geändert werden.

Anfragekörper
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
Antwort
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

Eine Rechnung und das generierte PDF dauerhaft löschen.

Antwort
204 No Content
GET/api/v1/invoices/:id/pdf

Die Rechnung als PDF-Datei herunterladen. Gibt binäres PDF mit Content-Disposition-Header zurück.

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

<binary PDF data>

Paginierung

Listen-Endpunkte akzeptieren die folgenden Abfrageparameter:

ParameterStandardBeschreibung
page1Seitennummer (min: 1)
limit20Einträge pro Seite (1–100)
search—Nach Name, E-Mail oder Rechnungsnummer filtern (max 255 Zeichen)
clientId—Rechnungen nach Kunde filtern (nur Rechnungen)
status—Nach Status filtern: DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

Fehler

Die API gibt Standard-HTTP-Statuscodes zurück. Fehlerantworten enthalten einen JSON-Body mit einem error-Feld.

StatusBeschreibung
400Bad Request — ungültige Parameter oder fehlende Pflichtfelder
401Unauthorized — ungültiger oder fehlender API-Schlüssel
403Forbidden — Plan-Limit erreicht (Kunden, Rechnungen oder Funktion)
404Not Found — Ressource existiert nicht oder ist nicht zugänglich
429Too Many Requests — Ratenbegrenzung überschritten
500Internal Server Error — unerwarteter Fehler, versuchen Sie es später erneut
{
  "error": "Missing required field: name"
}

Ratenbegrenzung

API-Anfragen sind auf 120 Anfragen pro Minute pro API-Schlüssel begrenzt.

Bei Überschreitung des Limits geben Anfragen 429 Too Many Requests zurück. Warten Sie, bevor Sie es erneut versuchen.