# Schnellstart

Für den Schnellstart reicht ein kostenloses Konto. Du arbeitest mit einem **Sandbox-Key**: Er legt Testkalender an, die in echten Kalender-Apps funktionieren, aber als Test gekennzeichnet sind.

## 1. Sandbox-Key anlegen

1. Melde dich in der [Kalender Sync App](https://app.kalender-sync.de/) an oder lege ein kostenloses Konto an.
2. Öffne **Einstellungen › Entwickler / API**.
3. Gib dem Key einen Namen und klicke **Sandbox-Key erstellen**.
4. Kopiere den Key. Er wird **genau einmal** angezeigt.

Leg ihn für die folgenden Aufrufe in eine Umgebungsvariable:

```bash
export KS_KEY="ks_test_…"
```

## 2. Key prüfen

```bash
curl https://api.kalender-sync.de/v1/me \
  -H "Authorization: Bearer $KS_KEY"
```

```json
{
  "account_id": "…",
  "key": {
    "id": "…",
    "name": "Meine Website",
    "mode": "test",
    "scopes": ["publisher:read", "publisher:write", "publisher:stats"],
    "calendar_ids": null
  }
}
```

`mode: "test"` heißt: Dieser Key sieht nur Testkalender.

## 3. Kalender anlegen

```bash
curl https://api.kalender-sync.de/v1/publisher/calendars \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Riverside Yoga",
    "description": "Kurse und Workshops im Studio am Fluss.",
    "timezone": "Europe/Berlin",
    "language": "de",
    "site_url": "https://example.org",
    "brand_color": "#0f766e"
  }'
```

Die Antwort (`201 Created`) enthält alles, was du für die nächsten Schritte brauchst:

```json
{
  "id": "cal_XXXXXXXXXXXX",
  "mode": "test",
  "name": "Riverside Yoga",
  "timezone": "Europe/Berlin",
  "default_duration": "PT1H",
  "show_events": true,
  "subscribe_page_url": "https://app.kalender-sync.de/subscribe/cal_XXXXXXXXXXXX",
  "feed_url": "https://feeds.kalender-sync.de/f_….ics",
  "subscribe_links": { "google": "…", "outlook": "…", "office365": "…", "apple": "webcal://…" },
  "event_count": 0,
  "…": "…"
}
```

Merk dir die `id`:

```bash
export KS_CAL="cal_XXXXXXXXXXXX"
```

## 4. Termin schreiben

Termine legst du per `PUT` unter deiner eigenen ID an, hier `wp-101`. Derselbe Aufruf ändert den Termin später.

```bash
curl -X PUT https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/wp-101 \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sunset Yoga",
    "start": "2026-11-12T18:00:00",
    "end": "2026-11-12T19:15:00",
    "location": "Dachterrasse, Hauptstraße 5, Berlin",
    "description": "Bring eine Matte mit.",
    "url": "https://example.org/kurse/sunset-yoga"
  }'
```

Ohne `timezone` im Termin gilt die Zeitzone des Kalenders. Die Antwort ist `201 Created` beim ersten Mal und `200 OK` bei jeder Änderung. Schickst du denselben Termin noch einmal, kommt `"changed": false`.

Eine wöchentliche Serie sieht so aus:

```bash
curl -X PUT https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/wp-102 \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Morning Flow",
    "start": "2026-11-03T07:30:00",
    "end": "2026-11-03T08:30:00",
    "recurrence": { "rules": ["FREQ=WEEKLY;BYDAY=TU;COUNT=8"] }
  }'
```

## 5. Abonnieren

Öffne die `subscribe_page_url` aus Schritt 3 im Browser. Dort siehst du deine Termine, den Hinweis „Testkalender“ und den Button mit der App-Auswahl. Abonniere den Kalender testweise in deiner eigenen Kalender-App.

Für deine Website brauchst du nur noch den Button:

```html
<div class="ks-subscribe" data-calendar="cal_XXXXXXXXXXXX"></div>
<script src="https://app.kalender-sync.de/embed/v1/button.js" async></script>
```

→ [Button und ks:subscribe](https://docs.kalender-sync.de/api/button/)

## Und dann?

- **Live gehen:** Lege unter **Einstellungen › Entwickler / API** einen Live-Key an (ab Basic) und wiederhole Schritt 3 damit. Sandbox- und Live-Kalender sind getrennt; Testkalender werden nicht zu Live-Kalendern. → [Tarife und Limits](https://docs.kalender-sync.de/abo-kalender/tarife/)
- **Viele Termine auf einmal:** [Batch](https://docs.kalender-sync.de/api/batch/)
- **Regelmäßig abgleichen:** [Full Sync](https://docs.kalender-sync.de/api/full-sync/)
- **Logo und Banner:** [Bilder](https://docs.kalender-sync.de/api/images/)