Partner-API · v1

Documentazione API

Tutto ciò che ti serve per l’integrazione. Versione 1 · URL di base: https://hops24.de/api/v1

Scarica il file OpenAPI Non hai ancora una chiave? Richiedi l’accesso

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"
} }

Autenticazione

Invia la tua chiave nell’header a ogni richiesta. Non inserire mai le chiavi negli URL o nel codice pubblico – per le chiamate dal browser abilitiamo i tuoi domini.

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

Sandbox

Le chiavi con hk_test_ restituiscono dati di esempio fissi (annunci 900001–900003). Così puoi integrare prima di andare live. Le chiavi live iniziano con hk_live_.

Formato delle risposte

Le risposte positive contengono data (e, per gli elenchi, meta con le informazioni di paginazione); gli errori contengono error con code e message. Prezzi in euro come numero; se manca un prezzo, price_on_request è true.

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

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

Codici di errore

HTTP	Codice
400	`invalid_parameter`
401	`unauthorized`
403	`insufficient_scope · no_provider_account · provider_approval_required · origin_not_allowed · client_suspended`
404	`not_found`
409	`idempotency_conflict`
412	`version_conflict`
428	`precondition_required`
429	`rate_limited · quota_exceeded`
503	`temporarily_unavailable`
500	`server_error`

Limiti e quote

Ogni richiesta conta per la quota mensile. Gli header X-Quota-Limit e X-Quota-Remaining mostrano lo stato. Quando la quota è esaurita, l’API risponde con 429 – senza costi aggiuntivi.

Piano	Richieste / mese	Richieste / secondo
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	da concordare	50

Endpoint

GET `/api/v1/status`

Checks the key and shows plan, scopes and usage for the current month.

Esempio

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

GET `/api/v1/categories`

All categories with translations (de, en, es, fr, nl, it).

Permesso: listings:read

Esempio

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

GET `/api/v1/changes`

Public changes and removals after a cursor. Poll about every 60 seconds; reload details. Events are kept for 90 days – if your cursor is older, meta.resync_required asks for a full resync.

Permesso: listings:read

Parametro	Tipo	Descrizione
`after`	int	Last processed change ID, initially 0
`limit`	int	Up to 200 changes

Esempio

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

GET `/api/v1/listings`

Search public listings. Same logic as the search on hops24.de.

Permesso: listings:read

Parametro	Tipo	Descrizione
`q`	string	Free text (title, city, description)
`country`	string	Country (DE, AT, CH, FR, BE, LU, NL, ES, IT); default DE. Returns listings of providers in or serving this country
`postal_code`	string	Postcode or city; respects delivery areas
`lat, lng`	number	Coordinates; finds providers whose delivery radius covers the point
`category`	string	Category key from /categories
`date`	YYYY-MM-DD	Only listings available on this day
`max_price`	number	Maximum “from” price in euros
`placement`	1	Only listings offering long-term placement
`self_pickup`	1	Only with self pickup
`sort`	string	newest (default), price, distance (requires lat/lng)
`page, per_page`	int	Page (from 1) and results per page (1–50, default 20)

Esempio

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

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

Listing details incl. description, all images and technical details.

Permesso: listings:read

Esempio

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

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

Unavailable days of a listing from today.

Permesso: availability:read

Parametro	Tipo	Descrizione
`months`	int	Period in months (1–12, default 3)

Esempio

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

POST `/api/v1/inquiries`

Submit a customer enquiry to the provider. It arrives in the provider’s HOPS24 inbox; the customer receives a confirmation. Returns 201. The Idempotency-Key header is required (also in the sandbox): retries with the same key return the same response for 30 days.

Permesso: inquiries:create

Parametro	Tipo	Descrizione
`listing_id`	int	Listing (required)
`name, email`	string	Customer name and email (required)
`event_date`	YYYY-MM-DD	Requested date or placement start (required)
`event_end_date`	YYYY-MM-DD	End date for multi-day events
`request_type`	string	event (default) or placement (only if placement_available)
`placement_location`	string	Placement location (required for placement)
`phone, message`	string	Optional
`lang`	string	Language of the confirmation email to the customer: de, en, es, fr, nl, it (default de)
`consent`	bool	Must be true: the customer agreed to the submission

Esempio

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-02","message":"Kindergeburtstag, 15 Kinder","consent":true}'

GET `/api/v1/webhooks`

Your webhooks with delivery status.

Permesso: webhooks

Esempio

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

POST `/api/v1/webhooks`

Create a webhook. The signing secret is only shown in this response.

Permesso: webhooks

Parametro	Tipo	Descrizione
`url`	string	Target URL (https only, publicly reachable)
`events`	array	inquiry.created, inquiry.replied

Esempio

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`

Send a webhook.test event.

Permesso: webhooks

Esempio

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

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

Delete a webhook.

Permesso: webhooks

Esempio

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

GET `/api/v1/me/listings`

Provider integration: your own listings incl. inactive ones (key must be linked to a provider account).

Permesso: own:listings:write | own:inquiries:read

Esempio

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

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

Update your own listing using If-Match (version from GET /me/listings). Provider approval required. Activation requires the same minimum details as in the dashboard.

Permesso: own:listings:write

Parametro	Tipo	Descrizione
`title, description`	string	Title (3–150 chars), description
`prices`	object	from, daily, weekend, delivery, setup, deposit, placement_monthly, hourly (euros, null clears; hourly only for services)
`is_active`	bool	Activate/deactivate the listing

Esempio

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`

Your enquiries with status (new, waiting, answered, booked, closed) and customer details.

Permesso: own:inquiries:read

Parametro	Tipo	Descrizione
`status`	string	Filter by status

Esempio

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

GET `/api/v1/me/bookings`

Your orders within a period.

Permesso: own:inquiries:read

Parametro	Tipo	Descrizione
`from, to`	YYYY-MM-DD	Period (default: today to +12 months)

Esempio

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

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

Blocked days from today with source (manual, calendar_import, api) and deletable.

Permesso: own:calendar:write

Esempio

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

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

Block days (for one listing or all).

Permesso: own:calendar:write

Parametro	Tipo	Descrizione
`dates`	array	List of dates YYYY-MM-DD (max. 366)
`listing_id`	int	Optional; omitted = all listings
`reason`	string	Optional reason

Esempio

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`

Release only API blocks created by this connection; manual and imported blocks stay.

Permesso: own:calendar:write

Parametro	Tipo	Descrizione
`dates`	array	List of dates YYYY-MM-DD
`listing_id`	int	Optional

Esempio

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 con molti account noleggiatore: accesso multi-account su richiesta nel piano Partner.

Webhook

I webhook informano subito il tuo server sugli eventi (piano Business o superiore). Inviamo un POST con JSON al tuo URL; rispondi con uno stato 2xx. Le consegne non riuscite vengono ritentate dopo 1, 5 e 30 minuti e dopo 2, 6 e 24 ore.

Codice	Descrizione
`listing.updated`	Public listing changed
`availability.changed`	Availability changed
`listing.removed`	Remove listing from partner feed
`inquiry.created`	New customer enquiry for the linked provider account
`inquiry.replied`	Provider replied to an enquiry you submitted (without content)
`webhook.test`	Test event (triggered manually)

Verifica la firma (secret da 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);

Regole di visualizzazione

Per ogni annuncio mostra un link all’url della risposta. Nei piani Free e Starter mostra anche la dicitura „via HOPS24“. Conserva i dati in cache al massimo 24 ore e non cederli a terzi. I contatti dei noleggiatori non sono forniti di proposito – le richieste passano da HOPS24.

Si applicano le condizioni d’uso dell’API (in tedesco).

Documentazione API

Autenticazione

Sandbox

Formato delle risposte

Codici di errore

Limiti e quote

Endpoint

GET /api/v1/status

GET /api/v1/categories

GET /api/v1/changes

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

Webhook

Regole di visualizzazione

GET `/api/v1/status`

GET `/api/v1/categories`

GET `/api/v1/changes`

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`