Aufgaben API

API-Endpunkte zum Erstellen, Lesen, Aktualisieren und Löschen von Aufgaben.

Pro-Funktion

Die Aufgaben API bietet vollständige CRUD-Operationen (Create, Read, Update, Delete) für die programmgesteuerte Verwaltung von Aufgaben. Sie können Aufgaben aus externen Systemen erstellen, den Status aktualisieren, wenn Arbeit erledigt wird, und Aufgaben löschen, die nicht mehr benötigt werden. Dies macht die Aufgaben API zum vielseitigsten Teil der Kanman API.

Häufige Anwendungsfälle sind das Erstellen von Aufgaben aus Webformularen, das Markieren von Aufgaben als erledigt, wenn Builds abgeschlossen werden, und das Synchronisieren von Aufgaben mit anderen Projektmanagement-Tools.

Aufgabe abrufen

Rufen Sie eine bestimmte Aufgabe mit ihren Unteraufgaben ab.

Endpunkt

GET /tasks/:id

Parameter

Parameter Typ Beschreibung
id string Aufgaben-UUID

Erforderliche Berechtigung

read

Antwort

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "label": "Landingpage gestalten",
    "status": 1,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aaa",
    "description": "Responsive Landingpage-Design erstellen",
    "subtasks": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "label": "Wireframe erstellen",
        "is_completed": true
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440001",
        "label": "Mockup gestalten",
        "is_completed": false
      }
    ],
    "created_at": "2024-01-15T10:40:00Z",
    "updated_at": "2024-01-18T16:30:00Z"
  }
}

Beispiel

curl https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_ihr_api_token"

Aufgabe erstellen

Erstellen Sie eine neue Aufgabe in einem Projekt.

Endpunkt

POST /tasks

Erforderliche Berechtigung

write

Request Body

{
  "projectId": "660e8400-e29b-41d4-a716-446655440000",
  "label": "Neue Aufgabe über API",
  "description": "Optionaler Beschreibungstext",
  "status": 0
}

Body-Parameter

Parameter Typ Erforderlich Beschreibung
projectId string Ja Ziel-Projekt-UUID
label string Ja Aufgabenname
description string Nein Aufgabenbeschreibung
status number Nein Initialer Status (0, 1 oder 2). Standard: 0

Antwort

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440010",
    "label": "Neue Aufgabe über API",
    "status": 0,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aad",
    "description": "Optionaler Beschreibungstext",
    "subtasks": [],
    "created_at": "2024-01-21T10:00:00Z",
    "updated_at": "2024-01-21T10:00:00Z"
  }
}

Beispiel

curl -X POST https://api.kanman.de/v1/tasks \
  -H "Authorization: Bearer km_ihr_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "660e8400-e29b-41d4-a716-446655440000",
    "label": "Neue Aufgabe über API"
  }'

Fehler

Status Fehler Beschreibung
400 invalid_request Fehlende Pflichtfelder
404 project_not_found Projekt existiert nicht
429 quota_exceeded Aufgabenkontingent erreicht

Aufgabe aktualisieren

Aktualisieren Sie eine bestehende Aufgabe.

Endpunkt

PATCH /tasks/:id

Parameter

Parameter Typ Beschreibung
id string Aufgaben-UUID

Erforderliche Berechtigung

write

Request Body

Alle Felder sind optional. Fügen Sie nur Felder hinzu, die Sie aktualisieren möchten.

{
  "label": "Aktualisierter Aufgabenname",
  "status": 1,
  "description": "Aktualisierte Beschreibung",
  "projectId": "660e8400-e29b-41d4-a716-446655440001"
}

Body-Parameter

Parameter Typ Beschreibung
label string Neuer Aufgabenname
status number Neuer Status (0, 1 oder 2)
description string Neue Beschreibung
projectId string In anderes Projekt verschieben

Antwort

{
  "task": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "label": "Aktualisierter Aufgabenname",
    "status": 1,
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "workflow_lane_id": null,
    "position": "aaa",
    "description": "Aktualisierte Beschreibung",
    "subtasks": [],
    "created_at": "2024-01-15T10:40:00Z",
    "updated_at": "2024-01-21T10:30:00Z"
  }
}

Beispiel: Status ändern

curl -X PATCH https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_ihr_api_token" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

Beispiel: In anderes Projekt verschieben

curl -X PATCH https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_ihr_api_token" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "660e8400-e29b-41d4-a716-446655440001"}'

Aufgabe löschen

Soft-Delete einer Aufgabe (verschiebt in den Papierkorb).

Endpunkt

DELETE /tasks/:id

Parameter

Parameter Typ Beschreibung
id string Aufgaben-UUID

Erforderliche Berechtigung

delete

Antwort

{
  "success": true
}

Beispiel

curl -X DELETE https://api.kanman.de/v1/tasks/770e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer km_ihr_api_token"

Hinweise

  • Gelöschte Aufgaben gehen für 40 Tage in den Papierkorb
  • Unteraufgaben werden mit der übergeordneten Aufgabe gelöscht
  • Wiederherstellung ist über die Web-Oberfläche möglich

Aufgaben-Objekt

Vollständige Aufgaben-Objektstruktur:

Feld Typ Beschreibung
id string Eindeutige Kennung (UUID)
label string Aufgabenname
status number 0=offen, 1=in Bearbeitung, 2=erledigt
project_id string Übergeordnete Projekt-UUID
workflow_lane_id string Kanban-Lane-UUID (nullable)
position string Reihenfolge-Position (LexoRank)
description string Aufgabenbeschreibung (nullable)
subtasks array Array von Unteraufgaben-Objekten
created_at string ISO 8601 Zeitstempel
updated_at string ISO 8601 Zeitstempel

Unteraufgaben-Objekt

Feld Typ Beschreibung
id string Eindeutige Kennung (UUID)
label string Unteraufgabenname
is_completed boolean Abschlussstatus

Statuswerte

Wert Name Beschreibung
0 Offen Noch nicht begonnen
1 In Bearbeitung Wird derzeit bearbeitet
2 Erledigt Abgeschlossen

Häufige Anwendungsfälle

Aufgabe aus externem Formular erstellen

async function createTaskFromForm(formData) {
  const response = await fetch('https://api.kanman.de/v1/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projectId: 'ihre-projekt-id',
      label: formData.title,
      description: formData.details
    })
  });
  return response.json();
}

Aufgabe als erledigt markieren

async function completeTask(taskId) {
  const response = await fetch(`https://api.kanman.de/v1/tasks/${taskId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 2 })
  });
  return response.json();
}

Aufgaben mit anderem System synchronisieren

async function syncTasks(projectId) {
  // Alle Aufgaben abrufen
  const response = await fetch(
    `https://api.kanman.de/v1/projects/${projectId}/tasks`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.KANMAN_API_TOKEN}`
      }
    }
  );
  const { tasks } = await response.json();

  // Mit Ihrem System synchronisieren
  for (const task of tasks) {
    await ihrSystem.createOrUpdate({
      externalId: task.id,
      title: task.label,
      status: ['todo', 'doing', 'done'][task.status],
      description: task.description
    });
  }
}

Verwandte Themen

Zuletzt aktualisiert: January 1, 0001

Kanman testen