API-Dokumentation

GET /api/v1/status

Prüft den Schlüssel und zeigt Paket, Rechte und Verbrauch im laufenden Monat.

Beispiel

curl "https://hops24.de/api/v1/status" \
  -H "Authorization: Bearer hk_test_…"

GET /api/v1/categories

Alle Kategorien mit Übersetzungen (de, en, es, fr, nl, it, pt).

Recht: listings:read

Beispiel

curl "https://hops24.de/api/v1/categories" \
  -H "Authorization: Bearer hk_test_…"

GET /api/v1/changes

Öffentliche Änderungen und Rücknahmen seit einem Cursor. Abruf etwa alle 60 Sekunden; Details erneut laden. Ereignisse werden 90 Tage aufbewahrt – liegt dein Cursor davor, meldet meta.resync_required einen vollständigen Neuabgleich.

Recht: listings:read

Beispiel

curl "https://hops24.de/api/v1/changes" \
  -H "Authorization: Bearer hk_test_…"

GET /api/v1/listings

Suche nach öffentlichen Angeboten. Gleiche Logik wie die Suche auf hops24.de.

Recht: listings:read

Beispiel

curl "https://hops24.de/api/v1/listings?category=huepfburgen&postal_code=33100&sort=price" \
  -H "Authorization: Bearer hk_test_…"

GET /api/v1/listings/{id}

Details eines Angebots inkl. Beschreibung, aller Bilder und technischer Angaben.

Recht: listings:read

Beispiel

curl "https://hops24.de/api/v1/listings/900001" \
  -H "Authorization: Bearer hk_test_…"

GET /api/v1/listings/{id}/availability

Nicht verfügbare Tage eines Angebots ab heute. Hat der Anbieter mehrere gleiche Geräte für das Angebot, ist ein Tag erst belegt, wenn kein Gerät mehr frei ist.

Recht: availability:read

Beispiel

curl "https://hops24.de/api/v1/listings/900001/availability?months=3" \
  -H "Authorization: Bearer hk_test_…"

POST /api/v1/inquiries

Kundenanfrage an den Anbieter übermitteln. Landet im HOPS24-Posteingang des Anbieters; der Kunde erhält eine Bestätigung. Antwort 201. Header Idempotency-Key ist Pflicht (auch in der Sandbox): Wiederholungen mit demselben Schlüssel liefern 30 Tage lang dieselbe Antwort.

Recht: inquiries:create

Beispiel

curl -X POST "https://hops24.de/api/v1/inquiries" \
  -H "Authorization: Bearer hk_test_…" \
  -H "Idempotency-Key: example-request-001" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":900001,"name":"Erika Muster","email":"erika@example.de","event_date":"2026-11-08","message":"Kindergeburtstag, 15 Kinder","consent":true}'

GET /api/v1/webhooks

Eigene Webhooks mit Zustellstatus.

Recht: webhooks

Beispiel

curl "https://hops24.de/api/v1/webhooks" \
  -H "Authorization: Bearer hk_live_…"

POST /api/v1/webhooks

Webhook anlegen. Das Secret zur Signaturprüfung wird nur in dieser Antwort angezeigt.

Recht: webhooks

Beispiel

curl -X POST "https://hops24.de/api/v1/webhooks" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://partner.de/hops24-webhook","events":["inquiry.created","listing.updated"]}'

POST /api/v1/webhooks/{id}/test

Testereignis webhook.test senden.

Recht: webhooks

Beispiel

curl -X POST "https://hops24.de/api/v1/webhooks/7/test" \
  -H "Authorization: Bearer hk_live_…"

DELETE /api/v1/webhooks/{id}

Webhook löschen.

Recht: webhooks

Beispiel

curl -X DELETE "https://hops24.de/api/v1/webhooks/7" \
  -H "Authorization: Bearer hk_live_…"

GET /api/v1/me/listings

Anbieter-Integration: eigene Angebote inkl. inaktiver, mit external_ref (Schlüssel muss mit einem Anbieterkonto verknüpft sein).

Recht: own:listings:write | own:inquiries:read | own:listings:sync

Beispiel

curl "https://hops24.de/api/v1/me/listings" \
  -H "Authorization: Bearer hk_live_…"

POST /api/v1/me/listings/sync

Eigene Angebote aus deiner Software anlegen und abgleichen (in allen Tarifen kostenlos, ein Aufruf zählt einmal). Zuordnung über external_ref (Artikelnummer): neu anlegen, ändern, mit mode full nicht mehr gelieferte offline nehmen – nie löschen. Nur gelieferte Felder werden geändert. Neue Angebote gehen online, sobald die Mindestangaben erfüllt sind (sonst Entwurf, siehe problems), außer mit active: false. Fotos werden per URL geladen (je Adresse einmal, max. 5 je Angebot, 200 neue je Tag). Header Idempotency-Key ist Pflicht. Mehr als 200 Angebote: mode full in Teilen senden, sync_session aus der ersten Antwort mitschicken und im letzten Teil complete: true setzen.

Recht: own:listings:sync

Beispiel

curl -X POST "https://hops24.de/api/v1/me/listings/sync" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Idempotency-Key: example-request-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"full","listings":[{"external_ref":"HB-001","title":"Piraten-Hüpfburg XXL","category":"huepfburgen","city":"Berlin","description":"Große Piraten-Hüpfburg mit Rutsche und Netzen, ideal für Geburtstage und Sommerfeste.","prices":{"from":199,"weekend":299,"delivery":35},"images":["https://www.example.com/bilder/piraten-1.jpg"],"active":true}]}'

PUT /api/v1/me/listings/by-ref/{external_ref}

Ein Angebot über seine Kennung anlegen oder ändern (gleiche Felder wie ein Eintrag von /me/listings/sync). Antwort 201 beim Anlegen, sonst 200, mit ETag. If-Match ist optional; ist er gesetzt und das Angebot inzwischen geändert, folgt 412.

Recht: own:listings:sync

Beispiel

curl -X PUT "https://hops24.de/api/v1/me/listings/by-ref/HB-001" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Piraten-Hüpfburg XXL","prices":{"from":189},"active":true}'

GET /api/v1/me/sync/runs

Die letzten 20 Abgleiche dieser Verbindung mit Zählungen und Hinweisen (Codes je external_ref). Berichte werden 90 Tage aufbewahrt.

Recht: own:listings:sync

Beispiel

curl "https://hops24.de/api/v1/me/sync/runs" \
  -H "Authorization: Bearer hk_live_…"

PATCH /api/v1/me/listings/{id}

Eigenes Angebot mit If-Match ändern (version aus GET /me/listings). Anbieterfreigabe erforderlich. Beim Aktivieren gelten dieselben Mindestanforderungen wie im Dashboard.

Recht: own:listings:write

Beispiel

curl -X PATCH "https://hops24.de/api/v1/me/listings/123" \
  -H "Authorization: Bearer hk_live_…" \
  -H 'If-Match: "VERSION_FROM_GET_ME_LISTINGS"' \
  -H "Content-Type: application/json" \
  -d '{"prices":{"from":99,"weekend":149},"is_active":true}'

GET /api/v1/me/inquiries

Eigene Anfragen mit Status (new, open, booked, closed) und Kundendaten. Seit 05.10.2026 ersetzt open die früheren Werte waiting und answered (als Filter weiter angenommen).

Recht: own:inquiries:read

Beispiel

curl "https://hops24.de/api/v1/me/inquiries" \
  -H "Authorization: Bearer hk_live_…"

GET /api/v1/me/bookings

Eigene Aufträge in einem Zeitraum.

Recht: own:inquiries:read

Beispiel

curl "https://hops24.de/api/v1/me/bookings" \
  -H "Authorization: Bearer hk_live_…"

GET /api/v1/me/blocked-dates

Gesperrte Tage ab heute mit Herkunft (manual, calendar_import, api) und deletable.

Recht: own:calendar:write

Beispiel

curl "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…"

POST /api/v1/me/blocked-dates

Tage sperren (für ein Angebot oder alle).

Recht: own:calendar:write

Beispiel

curl -X POST "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"dates":["2026-10-23"],"listing_id":123,"reason":"Wartung"}'

DELETE /api/v1/me/blocked-dates

Nur die von dieser Verbindung erzeugten API-Sperrtage freigeben; manuelle Sperren und Kalender-Importe bleiben.

Recht: own:calendar:write

Beispiel

curl -X DELETE "https://hops24.de/api/v1/me/blocked-dates" \
  -H "Authorization: Bearer hk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"dates":["2026-10-23"],"listing_id":123}'