Öffentliche API

Verbinden Sie Ihre Anwendungen mit Corcava über unsere REST-API. Erstellen Sie eigene Integrationen, automatisieren Sie Abläufe und verbinden Sie Corcava mit Ihren bestehenden Tools und Systemen.

Überblick

Die Corcava Public API bietet programmatischen Zugriff auf Ihre zentralen Geschäftsdaten wie Projekte, Aufgaben, Boards, Kunden, Kontakte und Tickets. Nutzen Sie Standard-HTTP-Methoden, um Ressourcen zu erstellen, zu lesen, zu aktualisieren und zu löschen – für leistungsstarke Automatisierung und Integration.

Erste Schritte

API-Schlüssel erzeugen

Zu Einstellungen → Integrationen wechseln
Zum Abschnitt Öffentliche API scrollen
Auf API-Schlüssel erzeugen klicken
Ihren API-Schlüssel sofort kopieren – er wird aus Sicherheitsgründen nur einmal angezeigt
Ihn sicher aufbewahren – Sie benötigen ihn für alle API-Anfragen

API-Schlüssel verwalten

Sie können mehrere API-Schlüssel auf der Integrationsseite verwalten:

Neue Schlüssel anlegen – Zusätzliche Schlüssel für verschiedene Anwendungen oder Umgebungen erzeugen
Aktivieren/Deaktivieren – Schlüssel ein- oder ausschalten, ohne sie zu löschen
Schlüssel löschen – Nicht mehr benötigte Schlüssel dauerhaft entfernen

Best Practice: Legen Sie getrennte API-Schlüssel für verschiedene Anwendungen oder Umgebungen (Entwicklung, Staging, Produktion) an, um Zugriff und Sicherheit besser zu steuern.

Basis-URL

Alle API-Anfragen richten Sie an:

https://corcava.com/api/v1

Für Entwicklungs-/Testumgebungen nutzen Sie Ihre spezifische Domain:

https://your-domain.com/api/v1

Authentifizierung

Fügen Sie Ihren API-Schlüssel in jeder Anfrage im Header Authorization ein:

Authorization: Bearer YOUR_API_KEY_HERE

Beispielanfrage:

curl -X GET "https://corcava.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Verfügbare Endpunkte

Die Public API bietet vollen CRUD-Zugriff (Create, Read, Update, Delete) auf Ihre zentralen Geschäftsressourcen wie Projekte, Aufgaben, Boards, Kunden, Kontakte und Tickets. Jede Ressource unterstützt Standard-REST-Operationen mit Filterung, Suche und Paginierung.

Für vollständige Endpunkt-Dokumentation, Anfrage-/Antwort-Beispiele und detaillierte Parameterspezifikationen nutzen Sie die interaktive API-Dokumentation:

https://corcava.com/api/v1/docs

Die interaktive Dokumentation bietet:

Vollständige Liste aller verfügbaren Endpunkte
Detaillierte Anfrage- und Antwortbeispiele
Parameterbeschreibungen und Validierungsregeln
Authentifizierungsanforderungen
Möglichkeit, API-Aufrufe direkt im Browser zu testen

Anfrageformat

Alle Anfragen sollten enthalten:

Authorization: Bearer YOUR_API_KEY – Erforderlich für die Authentifizierung
Accept: application/json – Gibt das JSON-Antwortformat an
Content-Type: application/json – Erforderlich für POST/PUT-Anfragen mit Body

Abfrageparameter

Die meisten Listen-Endpunkte unterstützen Filterung, Suche und Paginierung:

search – Suche nach Name oder anderen durchsuchbaren Feldern
per_page – Anzahl der Ergebnisse pro Seite (Standard: 30, max: 100)
page – Seitennummer für die Paginierung
sort – Spalte zum Sortieren (z. B. name, created_at)
direction – Sortierrichtung: asc oder desc

Beispiel: GET /api/v1/projects?search=onboarding&per_page=50&sort=created_at&direction=desc

Antwortformat

Erfolgreiche Antworten liefern JSON in folgender Struktur:

{
  "data": [
    {
      "id": 1,
      "name": "Project Name",
      ...
    }
  ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "total": 100
  }
}

Fehlerantworten enthalten Details zum Problem:

{
  "message": "Validation error",
  "errors": {
    "field_name": ["Error message 1", "Error message 2"]
  }
}

Typische Anwendungsfälle

Projektanlage automatisieren

Projekte automatisch anlegen, wenn neue Kunden in Ihr CRM aufgenommen werden:

curl -X POST "https://corcava.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Project",
    "client_id": 5,
    "user_id": 12,
    "billable": true
  }'

Aufgaben aus externen Tools synchronisieren

Aufgaben aus Projektmanagement-Tools importieren oder basierend auf externen Ereignissen anlegen:

curl -X POST "https://corcava.com/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review design mockups",
    "board_id": 3,
    "user_id": 8
  }'

Individuelle Dashboards erstellen

Daten abrufen für eigene Berichts-Dashboards oder Anbindung an Business-Intelligence-Tools:

curl -X GET "https://corcava.com/api/v1/projects?per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook-Integration

Die API nutzen, um Daten zu synchronisieren, wenn Webhooks von externen Systemen ausgelöst werden – Ihre Corcava-Daten bleiben automatisch aktuell.

Ratenbegrenzung

API-Anfragen unterliegen einer Ratenbegrenzung für faire Nutzung und Systemstabilität. Bei Überschreitung erhalten Sie eine Antwort 429 Too Many Requests.

Best Practice: Implementieren Sie in Ihrer Integration exponentielle Backoff- und Wiederholungslogik, um Ratenbegrenzungen sauber zu handhaben.

Fehlerbehandlung

Die API nutzt Standard-HTTP-Statuscodes:

200 OK – Anfrage erfolgreich
201 Created – Ressource erfolgreich erstellt
400 Bad Request – Ungültige Anfrageparameter
401 Unauthorized – Ungültiger oder fehlender API-Schlüssel
403 Forbidden – API-Schlüssel hat keine Berechtigung
404 Not Found – Ressource existiert nicht
422 Unprocessable Entity – Validierungsfehler
429 Too Many Requests – Ratenbegrenzung überschritten
500 Internal Server Error – Serverfehler

Prüfen Sie immer den Antwort-Statuscode und behandeln Sie Fehler in Ihrer Integration angemessen.

Team-Isolation

Alle API-Anfragen sind automatisch auf Ihr Team begrenzt. Sie können nur auf Ressourcen (Projekte, Aufgaben, Kunden usw.) zugreifen, die zu Ihrem Team gehören. Das gewährleistet Datensicherheit und verhindert teamübergreifenden Datenzugriff.

Sicherheits-Best Practices

API-Schlüssel sicher aufbewahren – API-Schlüssel niemals in die Versionskontrolle committen oder im Client-Code exponieren
Umgebungsvariablen nutzen – Schlüssel in Umgebungsvariablen oder sicheren Konfigurationsdateien speichern
Schlüssel regelmäßig rotieren – Periodisch neue Schlüssel erzeugen und alte widerrufen
Getrennte Schlüssel pro Anwendung – Denselben Schlüssel nicht in mehreren Integrationen wiederverwenden
Schlüsselverwendung überwachen – Regelmäßig prüfen, welche Schlüssel aktiv sind, und ungenutzte löschen
Nur HTTPS – API-Anfragen immer über HTTPS stellen, nie über HTTP

Support

Hilfe zur API? Nutzen Sie die interaktive Dokumentation unter /api/v1/docs oder wenden Sie sich an unser Support-Team. Wir unterstützen Sie beim Aufbau leistungsstarker Integrationen für Ihren Workflow.