Events über die API erstellen und verwalten

Überblick

Mit der Events API können Sie programmatisch Veranstaltungen erstellen, bearbeiten, anzeigen und löschen. Diese Dokumentation erklärt alle erforderlichen und optionalen Felder sowie deren Validierungsregeln.

API-Endpunkte

Authentifizierung: Bearer Token erforderlich für alle Endpunkte

Berechtigung

Um Events zu erstellen oder zu verwalten, müssen Sie:

• Administrator eines Unternehmens sein
• Das Unternehmen muss eine gültige Adresse haben
• Für die Veröffentlichung: Premium-Subscription erforderlich

Event erstellen

POST /api/events

Pflichtfelder

Optionale Felder

Schedule-Objekte

Jedes Schedule-Objekt im schedules Array:

Bild-Objekte

Jedes Bild-Objekt im images Array:

Beispiel-Request

POST /api/events
Authorization: Bearer YOUR_TOKEN_HERE

{
  "title": "Immobilien-Fachmesse 2024",
  "description": "Die führende Veranstaltung für Immobilienprofis mit über 100 Ausstellern und hochkarätigen Vorträgen. Erfahren Sie alles über die neuesten Trends in der Branche.",
  "excerpt": "Die führende Immobilien-Fachmesse mit über 100 Ausstellern",
  "start": "2024-06-15T09:00:00Z",
  "end": "2024-06-15T18:00:00Z",
  "publish_at": "2024-05-01T10:00:00Z",
  "subscription_ends_at": "2024-06-14T23:59:59Z",
  "company_id": 42,
  "address_id": 15,
  "uses_ir_subscription": true,
  "schedules": [
    {
      "title": "Eröffnungskeynote",
      "start": "2024-06-15T09:00:00Z",
      "end": "2024-06-15T10:00:00Z"
    },
    {
      "title": "Panel-Diskussion: Zukunft der Immobilien",
      "start": "2024-06-15T11:00:00Z",
      "end": "2024-06-15T12:30:00Z"
    }
  ],
  "images": [
    {
      "url": "https://example.com/event-banner.jpg",
      "alt": "Immobilien-Fachmesse 2024 Banner"
    },
    {
      "url": "https://example.com/venue-photo.jpg",
      "alt": "Messehalle Eingangsbereich"
    }
  ]
}

Erfolgreiche Antwort (201 Created)

{
  "data": {
    "id": 123,
    "title": "Immobilien-Fachmesse 2024",
    "slug": "immobilien-fachmesse-2024",
    "description": "Die führende Veranstaltung...",
    "excerpt": "Die führende Immobilien-Fachmesse...",
    "start": "2024-06-15T09:00:00.000000Z",
    "end": "2024-06-15T18:00:00.000000Z",
    "publish_at": "2024-05-01T10:00:00.000000Z",
    "subscription_ends_at": "2024-06-14T23:59:59.000000Z",
    "uses_ir_subscription": true,
    "video_embed_code": null,
    "link": "https://example.com/events/immobilien-fachmesse-2024",
    "is_live": false,
    "can_be_published": true,
    "created_at": "2024-04-20T10:00:00.000000Z",
    "updated_at": "2024-04-20T10:00:00.000000Z",
    "company": {
      "id": 42,
      "name": "Example Immobilien GmbH"
    },
    "user": {
      "id": 1,
      "name": "Max Mustermann"
    },
    "address": {
      "id": 15,
      "street": "Messestraße 1",
      "city": "Berlin",
      "zip": "10115",
      "country": "Deutschland"
    },
    "schedules": [
      {
        "id": 1,
        "title": "Eröffnungskeynote",
        "start": "2024-06-15T09:00:00.000000Z",
        "end": "2024-06-15T10:00:00.000000Z"
      }
    ],
    "images": [...]
  },
  "message": "Event created successfully"
}

Event aktualisieren

PUT/PATCH /api/events/{id}

Alle Felder sind optional bei Updates (verwenden Sie sometimes Validierung). Sie müssen nur die Felder senden, die Sie ändern möchten.

Wichtig: Wenn Sie address_id oder company_id senden, müssen diese gültig sein.

Beispiel-Request

PUT /api/events/123
Authorization: Bearer YOUR_TOKEN_HERE

{
  "title": "Immobilien-Fachmesse 2024 - AKTUALISIERT",
  "video_embed_code": "<iframe src='https://vimeo.com/...'></iframe>",
  "schedules": [
    {
      "title": "Erweiterte Eröffnungskeynote",
      "start": "2024-06-15T09:00:00Z",
      "end": "2024-06-15T10:30:00Z"
    }
  ]
}

Hinweis: Beim Update werden bestehende Schedules und Images durch die neuen ersetzt, wenn diese Felder gesendet werden.

Event anzeigen

GET /api/events/{id}

Zeigt Details eines einzelnen Events an. Sie müssen der Ersteller des Events oder Administrator des zugehörigen Unternehmens sein.

GET /api/events/123
Authorization: Bearer YOUR_TOKEN_HERE

Event löschen

DELETE /api/events/{id}

Löscht ein Event (Soft Delete). Sie müssen der Ersteller oder Unternehmens-Administrator sein.

DELETE /api/events/123
Authorization: Bearer YOUR_TOKEN_HERE

Erfolgreiche Antwort (200 OK)

{
  "message": "Event deleted successfully"
}

Events auflisten

GET /api/events

Listet alle Events auf, die Sie erstellt haben.

Query-Parameter:

• per_page (optional): Anzahl der Ergebnisse pro Seite (Standard: 15)

GET /api/events?per_page=20
Authorization: Bearer YOUR_TOKEN_HERE

Antwort

{
  "data": [
    {
      "id": 123,
      "title": "Immobilien-Fachmesse 2024",
      "slug": "immobilien-fachmesse-2024",
      "start": "2024-06-15T09:00:00.000000Z",
      ...
    }
  ],
  "links": {
    "first": "http://example.com/api/events?page=1",
    "last": "http://example.com/api/events?page=5",
    "prev": null,
    "next": "http://example.com/api/events?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 73
  }
}

Fehlerbehandlung

Validierungsfehler (422 Unprocessable Entity)

{
  "message": "The title field is required. (and 2 more errors)",
  "errors": {
    "title": ["The title field is required."],
    "company_id": ["You must be an administrator of this company to create an event for it."],
    "start": ["The start date must be in the future."]
  }
}

Unberechtigt (403 Forbidden)

{
  "message": "Unauthorized"
}

Nicht authentifiziert (401 Unauthorized)

{
  "message": "Unauthenticated."
}

Wichtige Hinweise

1. Venues erforderlich: Jedes Event benötigt eine gültige address_id (Veranstaltungsort)
2. Unternehmenszuordnung: Events sind immer einem Unternehmen zugeordnet
3. Berechtigungen: Nur Unternehmens-Administratoren können Events erstellen/bearbeiten
4. Zeitvalidierung: Start-Datum muss in der Zukunft liegen, End-Datum nach Start
5. Veröffentlichung: Die Veröffentlichung kann zusätzliche Anforderungen haben (z.B. Premium-Subscription)
6. Bilder werden heruntergeladen: Die API lädt Bilder von den angegebenen URLs herunter und speichert sie lokal
7. Schedules sind optional: Aber empfohlen für eine detaillierte Event-Planung

Weitere Informationen

• Venues/Adressen über die API verwalten
• API-Token erstellen
• Unternehmen verwalten