API Dokumentation – Aufgaben

Endpunkte unter /api/tasks/ zur Anlage von Aufgaben („Tasks“) über die öffentliche CATAMA-API. Strukturierte Zusatzdaten wie Aufgaben-Typ, Fahrzeugdaten und Kundendaten können als JSON mitgegeben werden.

Authentifizierung
Alle Endpunkte erfordern den Parameter token mit einem gültigen API-Token.
Bei ungültigem Token wird {"status": 0, "message": "Invalid Token"} zurückgegeben.

Endpunkte

• POST /api/tasks/create — Neue Aufgabe anlegen

Authentifizierung

Akzeptiert werden zwei API-Tokens (in dieser Reihenfolge geprüft):

• Primär: settings.catama_public_api_token – derselbe Token wie für /api/customerscars/* und /api/invoices/create.
• Fallback: settings.public_access_token – wird aus Backwards-Compatibility weiterhin akzeptiert.

Den Token finden Sie in der CATAMA-Verwaltung unter Einstellungen → System → CATAMA API Token.

POST /api/tasks/create

Pflichtparameter

Optionale Parameter – Inhalt & Klassifizierung

Optionale Parameter – Verknüpfungen

Optionale Parameter – Zusatzdaten & Tracking

Beispiel-Aufruf – minimal

cURL

curl -X POST https://catama-instanz.de/api/tasks/create \
  -H "Content-Type: application/json" \
  -d '{
    "token": "DEIN_API_TOKEN",
    "title": "Kunde Müller zurückrufen",
    "user_id": 2
  }'

Beispiel-Aufruf – vollständig

cURL

curl -X POST https://catama-instanz.de/api/tasks/create \
  -H "Content-Type: application/json" \
  -d '{
    "token": "DEIN_API_TOKEN",
    "title": "Ankaufangebot für Golf VII vorbereiten",
    "description": "Kunde möchte Inzahlungnahme. Bewertung anfertigen.",
    "user_id": 2,
    "assigned_user_ids": [2, 11, 12],
    "task_type": "create-purchase",
    "priority": 2,
    "deadline": "2026-12-31",
    "duration": 30,
    "status": 0,
    "kanban_identifier": "_todo",
    "board_id": 1,
    "customer_id": 200,
    "mobile_id": 1085,
    "source": "n8n",
    "external_reference": "CRM-2026-04711",
    "vehicledata": {
      "plate": "B-AB 1234",
      "vin": "WVWZZZ3CZWE123456",
      "model": "Golf VII",
      "mileage": 85000
    },
    "customerdata": {
      "company": "Muster GmbH",
      "forename": "Max",
      "lastname": "Mustermann"
    },
    "extra": {
      "campaign": "frühjahrs-aktion-2026"
    }
  }'

Beispiel-Aufruf – Form-Post mit deutschen Aliassen

cURL

curl -X POST https://catama-instanz.de/api/tasks/create \
  -d "token=DEIN_API_TOKEN" \
  -d "Titel=Angebot prüfen" \
  -d "Beschreibung=Bitte Angebot 2026-04711 freigeben" \
  -d "user_id=2" \
  -d "Typ=create-offer" \
  -d "Prio=3" \
  -d "Deadline=15.09.2026"

Erfolgreiche Antwort

{
  "data": {
    "task_id": 29387,
    "user_id": 2,
    "task_type": "create-purchase",
    "customer_id": 200,
    "mobile_id": 1085,
    "document_id": null,
    "document_type": null,
    "board_id": 1,
    "kanban_identifier": "_todo",
    "priority": 2,
    "status": 0,
    "deadline": 1798761600,
    "assigned_user_ids": [2, 11, 12],
    "source": "n8n",
    "external_reference": "CRM-2026-04711",
    "created_at": 1777555600
  },
  "status": 1,
  "message": "Success",
  "task_id": 29387
}

Fehler – Beispiele

{ "status": 0, "message": "Invalid Token" }              // HTTP 401
{ "status": 0, "message": "title is required" }          // HTTP 400
{ "status": 0, "message": "user_id or externaluid is required" } // HTTP 400
{ "status": 0, "message": "Invalid task_type. Allowed: create-purchase, contact-customer, mixed, create-offer" } // HTTP 400
{ "status": 0, "message": "User not found" }             // HTTP 404
{ "status": 0, "message": "Customer not found" }         // HTTP 404
{ "status": 0, "message": "Car not found" }              // HTTP 404
{ "status": 0, "message": "Failed to create task" }      // HTTP 500

Aufgaben-Typ (task_type)

Strukturierter, semantischer Aufgaben-Typ. Wird zentral in der Tabelle tasks_api_metadata abgelegt und ist später per SQL filterbar. Erlaubt sind ausschließlich:

Deadline-Formate

Der Parameter deadline akzeptiert mehrere Formate:

Wird kein Wert übergeben, speichert das System 2147483647 (= „kein Limit“).

Fahrzeug- und Kundendaten als JSON

Die Parameter vehicledata und customerdata nehmen beliebige strukturierte JSON-Objekte entgegen. Die Inhalte werden in der Tabelle tasks_api_metadata als JSON abgelegt (siehe Datenablage) und sind per SQL auswertbar.

Beide Parameter akzeptieren entweder ein JSON-Objekt (innerhalb eines JSON-Bodys) oder einen serialisierten JSON-String (bei Form-Posts).

Beispiel: Fahrzeugdaten

{
  "plate": "B-AB 1234",
  "vin": "WVWZZZ3CZWE123456",
  "fabricator": "Volkswagen",
  "model": "Golf VII",
  "registration_date": "2019-03-15",
  "mileage": 85000,
  "intern_id": "KFZ-001"
}

Beispiel: Kundendaten

{
  "company": "Muster GmbH",
  "forename": "Max",
  "lastname": "Mustermann",
  "email": "max@muster.de",
  "phone": "+49 30 12345678",
  "street": "Beispielstr. 1",
  "zip": "10115",
  "city": "Berlin"
}

Response-Felder im Detail

Die vollständige Liste aller Response-Felder finden Sie aufklappbar oben unter POST /api/tasks/create → Erfolgreiche Antwort → „Alle Felder im Response-Objekt anzeigen“.

Fehler-Codes

Alle Fehlerantworten haben die Form {"data":[],"status":0,"message":"…"}.

Datenablage

Ein erfolgreicher Request schreibt in mehrere Tabellen: