CalcPro API

Vollständige REST-API für Rechnungen, Angebote, Kunden und KI-gestützte Automatisierung. Integrieren Sie CalcPro nahtlos in Ihre eigenen Anwendungen und Workflows.

Base URL: https://calcpro.de/ Format: JSON Auth: Session-Cookie REST API
Schnellstart: Alle API-Anfragen erfolgen über POST /api.php mit dem Parameter action. Nach erfolgreichem Login wird eine Session erstellt, die für alle weiteren Requests automatisch verwendet wird.

Grundlagen

Die CalcPro API ist eine RESTful API, die alle Funktionen der Web-Anwendung programmatisch zugänglich macht. Die API verwendet JSON für Request- und Response-Daten und ist session-basiert authentifiziert.

Basis-Endpunkte

Endpunkt Beschreibung
POST /api.php Haupt-API für alle CRUD-Operationen (Kunden, Rechnungen, Angebote, etc.)
GET/POST /ai_chat.php KI-Support-Chat mit n8n-Integration (ab Professional-Plan)
Response-Format: Alle API-Antworten enthalten mindestens die Felder success (Boolean) und message (String). Bei Erfolg werden zusätzliche Daten im jeweiligen Kontext zurückgegeben.

Authentifizierung

CalcPro verwendet Session-basierte Authentifizierung. Nach erfolgreichem Login wird eine PHP-Session erstellt, die über ein Cookie im Browser gespeichert wird. Alle nachfolgenden API-Requests müssen dieses Cookie mitsenden. Die Session bleibt aktiv, bis der Benutzer sich ausloggt oder die Session abläuft.

POST /api.php?action=register

Neuen Benutzer registrieren

Erstellt einen neuen Benutzer-Account mit automatischer Zuweisung des gewählten Plans. Neue Benutzer erhalten automatisch eine 14-tägige Trial-Phase für Professional/Enterprise-Pläne.

Request Body: 
{
  "action": "register",
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "max@example.com",
  "company": "Beispiel GmbH",
  "password": "Passwort123",
  "terms": true,
  "plan": "starter"  // starter, professional, enterprise
}
Response: 
{
  "success": true,
  "message": "Registrierung erfolgreich",
  "user": {
    "id": 123,
    "email": "max@example.com",
    "plan": "starter",
    "subscription_status": "trial"
  }
}
POST /api.php?action=login

Benutzer anmelden

Authentifiziert einen Benutzer und erstellt eine neue Session. Das Session-Cookie wird automatisch im Browser gespeichert und für alle weiteren Requests verwendet.

Request Body: 
{
  "action": "login",
  "email": "max@example.com",
  "password": "Passwort123"
}
Response: 
{
  "success": true,
  "message": "Login erfolgreich",
  "user": {
    "id": 123,
    "email": "max@example.com",
    "name": "Max Mustermann",
    "plan": "professional"
  }
}
Rate Limiting: Login-Versuche sind auf 5 pro Minute limitiert, um Brute-Force-Angriffe zu verhindern.
POST /api.php?action=check_session

Session-Status prüfen

Überprüft, ob die aktuelle Session noch gültig ist und gibt Benutzerinformationen zurück.

Request Body: 
{
  "action": "check_session"
}
POST /api.php?action=logout

Benutzer abmelden

Beendet die aktuelle Session und löscht das Session-Cookie.

Core API: /api.php

Die Core-API bietet Zugriff auf alle Hauptfunktionen von CalcPro. Alle Requests erfolgen über POST /api.php mit dem Parameter action, der die gewünschte Operation definiert.

Kunden (Clients)

Verwalten Sie Ihre Kundendaten programmatisch. Kunden können erstellt, bearbeitet, gelöscht und abgerufen werden. Jeder Kunde wird automatisch dem angemeldeten Benutzer zugeordnet.

Action Beschreibung Pflichtfelder
get_clients Ruft alle Kunden des angemeldeten Benutzers ab -
get_client Ruft einen einzelnen Kunden ab client_id
create_client Erstellt einen neuen Kunden name, email
update_client Aktualisiert Kundendaten client_id
delete_client Löscht einen Kunden (inkl. zugehöriger Dokumente) client_id
get_client_statistics Statistiken für einen Kunden (Umsatz, Rechnungen, etc.) client_id
Beispiel - Kunde erstellen: 
{
  "action": "create_client",
  "name": "Max Mustermann",
  "email": "max@example.com",
  "company": "Mustermann GmbH",
  "phone": "+49 123 456789",
  "street": "Hauptstraße 1",
  "zip": "12345",
  "location": "Berlin"
}

Angebote (Quotes)

Erstellen und verwalten Sie Kostenvoranschläge. Angebote können in Rechnungen umgewandelt, per E-Mail versendet und als PDF heruntergeladen werden. Jedes Angebot erhält automatisch eine fortlaufende Nummer im Format KV-2025-1XXX.

Action Beschreibung
get_quotes Liste aller Angebote mit Filter- und Sortiermöglichkeiten
get_quote Einzelnes Angebot mit allen Positionen abrufen
create_quote Neues Angebot erstellen (mit automatischer Nummerierung)
update_quote Angebot bearbeiten (Status, Positionen, etc.)
delete_quote Angebot löschen
duplicate_quote Angebot duplizieren (neue Nummer wird vergeben)
convert_quote_to_invoice Angebot in Rechnung umwandeln
generate_quote_link Öffentlichen Vorschau-Link generieren
download_quote_pdf PDF-Datei herunterladen
send_quote_email Angebot per E-Mail an Kunden senden
Automatische Felder:
Bei der Erstellung eines Angebots werden folgende Felder automatisch gesetzt:
  • subject: "Vielen Dank für Ihre Anfrage."
  • valid_until: 30 Tage ab heute
  • tax_rate: 19.00% (überschreibbar)

Rechnungen (Invoices)

Erstellen und verwalten Sie Rechnungen mit automatischer Nummerierung im Format RE-2025-1XXX. Rechnungen können als bezahlt markiert, per E-Mail versendet und mit Zahlungserinnerungen versehen werden.

Action Beschreibung
get_invoices Liste aller Rechnungen mit Filteroptionen
get_invoice Einzelne Rechnung mit Positionen abrufen
create_invoice Neue Rechnung erstellen
update_invoice Rechnung bearbeiten
mark_invoice_paid Rechnung als bezahlt markieren
delete_invoice Rechnung löschen
duplicate_invoice Rechnung duplizieren
generate_invoice_link Öffentlichen Vorschau-Link generieren
download_invoice_pdf PDF-Datei herunterladen
send_invoice_email Rechnung per E-Mail versenden
send_payment_reminder Zahlungserinnerung senden
Automatische Felder:
Bei Rechnungserstellung werden automatisch gesetzt:
  • subject: "Vielen Dank für Ihr Vertrauen."
  • issue_date: Heutiges Datum
  • due_date: +14 Tage
  • tax_rate: 19.00%

Dashboard & Statistiken

Abrufen von Geschäftsstatistiken, Umsatzverläufen und Dashboard-Übersichten. Perfekt für die Integration in eigene Reporting-Tools oder Dashboards.

Action Beschreibung
get_dashboard_stats Übersicht: Rechnungen, Umsatz, offene Beträge
get_revenue_chart Monatlicher Umsatzverlauf (letztes Jahr)
get_invoice_status_chart Verteilung: Draft, Sent, Paid, Overdue
get_statistics Detaillierte Finanzstatistiken mit Zeiträumen

Abonnements & Limits

Verwalten Sie Abonnements, prüfen Sie Feature-Zugriffe und überwachen Sie Nutzungslimits. Jeder Plan (Starter, Professional, Enterprise) hat unterschiedliche Limits.

Action Beschreibung
get_subscription Aktueller Plan, Status, Trial-Info
update_subscription Plan wechseln (Upgrade/Downgrade)
get_plan_info Details zu einem Plan (Preise, Features, Limits)
check_feature Prüft, ob Feature verfügbar ist
check_limit Prüft Limit-Status (z.B. max. Rechnungen)
get_usage_stats Nutzungsstatistik (verbrauchte Limits)
Plan-Limits:
Starter: 5 Rechnungen/Monat | Professional: Unbegrenzt | Enterprise: Unbegrenzt + Voice Agent

Produkte

Verwalten Sie Ihren Produktkatalog. Produkte können in Rechnungen und Angeboten als Dropdown-Auswahl verwendet werden und erleichtern die Dokumentenerstellung.

Action Beschreibung
get_products Alle Produkte abrufen
get_product Einzelnes Produkt abrufen
create_product Neues Produkt erstellen
update_product Produkt bearbeiten
delete_product Produkt löschen

E-Mail & SMTP

Konfigurieren Sie eigene SMTP-Einstellungen für den E-Mail-Versand von Rechnungen und Angeboten. Unterstützt werden alle gängigen E-Mail-Provider (Gmail, Outlook, IONOS, etc.).

Action Beschreibung
get_smtp_settings Aktuelle SMTP-Konfiguration laden
save_smtp_settings SMTP-Einstellungen speichern
test_smtp_connection Test-E-Mail senden
get_email_templates E-Mail-Vorlagen abrufen
save_email_template E-Mail-Vorlage speichern

Einstellungen

Verwalten Sie Firmeneinstellungen, Rechnungsvorlagen, Farben, Schriftarten und weitere Konfigurationsoptionen für Ihre Dokumente.

Action Beschreibung
get_settings Alle Benutzereinstellungen laden
update_settings Einstellungen speichern
get_user_settings Profildetails abrufen
update_user_settings Profil aktualisieren

Voice Agent Enterprise only

Der Voice Agent ermöglicht telefonische Auftragsannahme und Dokumentenerstellung via Spracherkennung. Dieses Feature ist exklusiv im Enterprise-Plan verfügbar.

Action Beschreibung
get_voice_numbers Alle Voice-Nummern abrufen
create_voice_number Neue Voice-Nummer anlegen
update_voice_number Voice-Nummer bearbeiten
delete_voice_number Voice-Nummer löschen
get_voice_usage Nutzungsstatistik abrufen
Enterprise Feature: Dieser Endpunkt ist nur für Enterprise-Benutzer verfügbar. Bei Starter/Professional-Plan wird ein 403-Fehler zurückgegeben.

KI-Support: /ai_chat.php

Professional & Enterprise

Der KI-Support-Chat bietet intelligente Assistenz für die Erstellung und Verwaltung von Dokumenten. Die KI kann Rechnungen erstellen, Kunden verwalten, Statistiken abrufen und vieles mehr - alles über natürliche Spracheingaben. Die KI ist über einen n8n-Workflow angebunden und lernt aus dem Kontext.

KI-Fähigkeiten:
  • Dokumente erstellen, bearbeiten, löschen (Rechnungen, Angebote)
  • Kunden und Produkte verwalten
  • Statistiken und Dashboard-Daten abrufen
  • Natürliche Sprachverarbeitung ("Erstelle eine Rechnung für Kunde X über 500€")
  • Kontext-basierte Konversation mit Verlauf
GET /ai_chat.php?action=status

KI-Status prüfen

Überprüft, ob der angemeldete Benutzer Zugriff auf den KI-Chat hat (Professional/Enterprise).

Response: 
{
  "success": true,
  "has_access": true,
  "plan": "professional",
  "remaining_requests": 95
}
POST /ai_chat.php?action=send

Nachricht an KI senden

Sendet eine Nachricht an die KI und erhält eine intelligente Antwort. Die KI kann automatisch Aktionen ausführen (z.B. Rechnung erstellen) basierend auf der Eingabe.

Request Body: 
{
  "message": "Erstelle eine Rechnung für Jenny Maiers über 100 Wasserflaschen à 0,50€",
  "session_id": "optional-uuid-for-conversation-context"
}
Response: 
{
  "success": true,
  "response": "Ich habe die Rechnung für Jenny Maiers erstellt.",
  "session_id": "abc-123-def-456",
  "actions": [
    {
      "type": "create_invoice",
      "data": {...}
    }
  ],
  "action_results": [
    {
      "success": true,
      "message": "Rechnung RE-2025-1042 wurde erstellt"
    }
  ]
}
Rate Limiting: Professional: 100 Anfragen/Stunde | Enterprise: Unbegrenzt
GET /ai_chat.php?action=history&session_id=...

Chat-Verlauf abrufen

Ruft alle Nachrichten einer Chat-Session ab, um den Kontext wiederherzustellen.

Response: 
{
  "success": true,
  "messages": [
    {
      "id": 1,
      "message_type": "user",
      "message": "Erstelle eine Rechnung...",
      "created_at": "2025-11-25 10:30:00"
    },
    {
      "id": 2,
      "message_type": "ai",
      "message": "Rechnung wurde erstellt.",
      "created_at": "2025-11-25 10:30:05"
    }
  ]
}

Fehlercodes & Best Practices

HTTP-Statuscodes

Code Bedeutung Aktion
200 Erfolg Request erfolgreich verarbeitet
400 Bad Request Ungültiger Request-Body oder fehlende Parameter
401 Unauthorized Benutzer ist nicht angemeldet → Login erforderlich
403 Forbidden Kein Zugriff auf Ressource/Feature → Plan-Upgrade nötig
429 Too Many Requests Rate-Limit erreicht → Später erneut versuchen
500 Internal Server Error Serverfehler → Support kontaktieren

Best Practices

  • Immer success prüfen: Alle Responses enthalten dieses Feld
  • Fehlerbehandlung: Bei success: false das message-Feld auswerten
  • Session-Cookie: Automatisch mitsenden für authentifizierte Requests
  • Rate Limits beachten: Besonders bei Login-Versuchen und KI-Requests
  • HTTPS verwenden: Alle API-Calls sollten über HTTPS erfolgen
  • Input-Validierung: Daten vor dem Senden validieren
Beispiel - Fehlerbehandlung: 
fetch('/api.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ action: 'get_invoices' })
})
.then(res => res.json())
.then(data => {
  if (data.success) {
    console.log('Invoices:', data.invoices);
  } else {
    console.error('Error:', data.message);
  }
});