Partner-API · v1

API-Dokumentation

Alles, was du für die Integration brauchst. Version 1 · Basis-URL: https://hops24.de/api/v1

OpenAPI-Datei herunterladen Noch kein Schlüssel? Zugang anfragen

GET /api/v1/listings/900001
Authorization: Bearer hk_test_…

{ "data": {
    "id": 900001,
    "title": "Sandbox: Hüpfburg Ritterburg 4×4 m",
    "category": "huepfburgen",
    "prices": { "from": 89, "delivery": 25 },
    "url": "https://hops24.de/…",
    "attribution": "via HOPS24"
} }

Authentifizierung

Sende deinen Schlüssel bei jedem Abruf im Header. Schlüssel nie in URLs oder öffentlichem Code ablegen – für Browser-Aufrufe schalten wir deine Domains frei.

Authorization: Bearer hk_live_…
# oder
X-API-Key: hk_live_…

Sandbox

Schlüssel mit hk_test_ liefern feste Beispieldaten (Angebote 900001–900003). So kannst du integrieren, bevor du live gehst. Live-Schlüssel beginnen mit hk_live_.

Antwortformat

Erfolgreiche Antworten liefern data (und bei Listen meta mit Seiteninfos), Fehler liefern error mit code und message. Preise in Euro als Zahl; fehlt ein Preis, ist price_on_request true.

{ "data": [ … ], "meta": { "page": 1, "per_page": 20, "total": 14, "pages": 1 } }

{ "error": { "code": "quota_exceeded", "message": "…" } }

Fehlercodes

HTTP	Code
400	`invalid_parameter`
401	`unauthorized`
403	`insufficient_scope · origin_not_allowed · client_suspended`
404	`not_found`
429	`rate_limited · quota_exceeded`
500	`server_error`

Limits & Kontingente

Jeder Abruf zählt zum Monatskontingent. Die Header X-Quota-Limit und X-Quota-Remaining zeigen den Stand. Ist das Kontingent erschöpft, antwortet die API mit 429 – es entstehen keine Zusatzkosten.

Paket	Abrufe / Monat	Abrufe / Sekunde
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	nach Vereinbarung	50

Endpunkte

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).

Recht: listings:read

Beispiel

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

GET `/api/v1/listings`

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

Recht: listings:read

Parameter	Typ	Beschreibung
`q`	string	Freitext (Titel, Ort, Beschreibung)
`postal_code`	string	PLZ oder Ort; berücksichtigt Liefergebiete
`lat, lng`	number	Koordinaten; findet Anbieter, deren Lieferradius den Punkt abdeckt
`category`	string	Kategorie-Schlüssel aus /categories
`date`	YYYY-MM-DD	Nur an diesem Tag verfügbare Angebote
`max_price`	number	Höchstpreis (ab-Preis) in Euro
`placement`	1	Nur Angebote mit fester Aufstellung
`self_pickup`	1	Nur mit Selbstabholung
`sort`	string	newest (Standard), price, distance (nur mit lat/lng)
`page, per_page`	int	Seite (ab 1) und Treffer pro Seite (1–50, Standard 20)

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.

Recht: availability:read

Parameter	Typ	Beschreibung
`months`	int	Zeitraum in Monaten (1–12, Standard 3)

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.

Recht: inquiries:create

Parameter	Typ	Beschreibung
`listing_id`	int	Angebot (Pflicht)
`name, email`	string	Name und E-Mail des Kunden (Pflicht)
`event_date`	YYYY-MM-DD	Wunschtermin bzw. Aufstellungsbeginn (Pflicht)
`event_end_date`	YYYY-MM-DD	Enddatum bei mehrtägigen Events
`request_type`	string	event (Standard) oder placement (feste Aufstellung, nur wenn placement_available)
`placement_location`	string	Aufstellort (Pflicht bei placement)
`phone, message`	string	Optional
`consent`	bool	Muss true sein: Der Kunde hat der Übermittlung zugestimmt

Beispiel

curl -X POST "https://hops24.de/api/v1/inquiries" \
  -H "Authorization: Bearer hk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":900001,"name":"Erika Muster","email":"erika@example.de","event_date":"2026-11-02","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

Parameter	Typ	Beschreibung
`url`	string	Ziel-URL (nur https, öffentlich erreichbar)
`events`	array	inquiry.created, inquiry.replied

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","inquiry.replied"]}'

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 (Schlüssel muss mit einem Anbieterkonto verknüpft sein).

Recht: own:inquiries:read

Beispiel

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

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

Eigenes Angebot ändern. Beim Aktivieren gelten dieselben Mindestanforderungen wie im Dashboard.

Recht: own:listings:write

Parameter	Typ	Beschreibung
`title, description`	string	Titel (3–150 Zeichen), Beschreibung
`prices`	object	from, daily, weekend, delivery, setup, deposit, placement_monthly (Euro, null = leeren)
`is_active`	bool	Angebot aktivieren/deaktivieren

Beispiel

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

GET `/api/v1/me/inquiries`

Eigene Anfragen mit Status (new, waiting, answered, booked, closed) und Kundendaten.

Recht: own:inquiries:read

Parameter	Typ	Beschreibung
`status`	string	Filter nach Status

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

Parameter	Typ	Beschreibung
`from, to`	YYYY-MM-DD	Zeitraum (Standard: heute bis +12 Monate)

Beispiel

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

GET `/api/v1/me/blocked-dates`

Gesperrte Tage ab heute (manuell und aus Kalender-Import).

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

Parameter	Typ	Beschreibung
`dates`	array	Liste von Daten YYYY-MM-DD (max. 366)
`listing_id`	int	Optional; ohne = alle Angebote
`reason`	string	Optionaler Grund

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-17"],"listing_id":123,"reason":"Wartung"}'

DELETE `/api/v1/me/blocked-dates`

Manuell gesperrte Tage wieder freigeben (Kalender-Importe bleiben).

Recht: own:calendar:write

Parameter	Typ	Beschreibung
`dates`	array	Liste von Daten YYYY-MM-DD
`listing_id`	int	Optional

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-17"],"listing_id":123}'

Software-Partner mit vielen Anbieterkonten: Mehrkonten-Zugang auf Anfrage im Paket Partner.

Webhooks

Webhooks informieren deinen Server sofort über Ereignisse (Paket Business oder höher). Wir senden einen POST mit JSON an deine URL; antworte mit einem 2xx-Status. Fehlgeschlagene Zustellungen wiederholen wir nach 1, 5 und 30 Minuten sowie 2, 6 und 24 Stunden.

Code	Beschreibung
`inquiry.created`	Neue Kundenanfrage an das verknüpfte Anbieterkonto
`inquiry.replied`	Anbieter hat auf eine über dich gesendete Anfrage geantwortet (ohne Inhalt)
`webhook.test`	Testereignis (manuell ausgelöst)

Signatur prüfen (Secret aus POST /webhooks)

POST https://partner.de/hops24-webhook
X-HOPS24-Event: inquiry.created
X-HOPS24-Signature: t=1760000000,v1=5f2c…

{ "id": 812, "event": "inquiry.created", "created_at": "2026-10-02T18:00:00+00:00",
  "data": { "inquiry_id": 4711, "listing_id": 123, "event_date": "2026-11-01", "source": "website" } }

// PHP: Signatur prüfen
[$t, $v1] = sscanf($_SERVER['HTTP_X_HOPS24_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$ok = abs(time() - $t) < 300
   && hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1);

Regeln für die Darstellung

Zeige zu jedem Angebot einen Link auf die url aus der Antwort. In Free und Starter zusätzlich den Hinweis „via HOPS24“. Daten höchstens 24 Stunden zwischenspeichern und nicht weitergeben. Kontaktdaten der Anbieter gibt es bewusst nicht – Anfragen laufen über HOPS24.

Es gelten die API-Nutzungsbedingungen.

API-Dokumentation

Authentifizierung

Sandbox

Antwortformat

Fehlercodes

Limits & Kontingente

Endpunkte

GET /api/v1/status

GET /api/v1/categories

GET /api/v1/listings

GET /api/v1/listings/{id}

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

POST /api/v1/inquiries

GET /api/v1/webhooks

POST /api/v1/webhooks

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

DELETE /api/v1/webhooks/{id}

GET /api/v1/me/listings

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

GET /api/v1/me/inquiries

GET /api/v1/me/bookings

GET /api/v1/me/blocked-dates

POST /api/v1/me/blocked-dates

DELETE /api/v1/me/blocked-dates

Webhooks

Regeln für die Darstellung

GET `/api/v1/status`

GET `/api/v1/categories`

GET `/api/v1/listings`

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

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

POST `/api/v1/inquiries`

GET `/api/v1/webhooks`

POST `/api/v1/webhooks`

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

DELETE `/api/v1/webhooks/{id}`

GET `/api/v1/me/listings`

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

GET `/api/v1/me/inquiries`

GET `/api/v1/me/bookings`

GET `/api/v1/me/blocked-dates`

POST `/api/v1/me/blocked-dates`

DELETE `/api/v1/me/blocked-dates`