Partner-API · v1

Documentation de l’API

Tout ce qu’il faut pour l’intégration. Version 1 · URL de base : https://hops24.de/api/v1

Télécharger le fichier OpenAPI Pas encore de clé ? Demander un accès

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

Authentification

Envoyez votre clé dans l’en-tête à chaque requête. Ne placez jamais de clé dans une URL ou du code public – pour les appels navigateur, nous autorisons vos domaines.

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

Sandbox

Les clés hk_test_ renvoient des données d’exemple fixes (offres 900001–900003) pour intégrer avant la mise en production. Les clés réelles commencent par hk_live_.

Format des réponses

Les réponses réussies contiennent data (et meta avec la pagination pour les listes) ; les erreurs contiennent error avec code et message. Prix en euros (nombre) ; sinon price_on_request vaut true.

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

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

Codes d’erreur

HTTP	Code
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`

Limites et quotas

Chaque requête compte dans le quota mensuel. Les en-têtes X-Quota-Limit et X-Quota-Remaining indiquent l’état. Quota épuisé : réponse 429, sans frais supplémentaires.

Offre	Requêtes / mois	Requêtes / seconde
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	sur accord	50

Endpoints

GET `/api/v1/status`

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

Exemple

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

Droit: listings:read

Exemple

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.

Droit: listings:read

Paramètre	Type	Description
`after`	int	Last processed change ID, initially 0
`limit`	int	Up to 200 changes

Exemple

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.

Droit: listings:read

Paramètre	Type	Description
`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)

Exemple

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.

Droit: listings:read

Exemple

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.

Droit: availability:read

Paramètre	Type	Description
`months`	int	Period in months (1–12, default 3)

Exemple

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.

Droit: inquiries:create

Paramètre	Type	Description
`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

Exemple

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.

Droit: webhooks

Exemple

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.

Droit: webhooks

Paramètre	Type	Description
`url`	string	Target URL (https only, publicly reachable)
`events`	array	inquiry.created, inquiry.replied

Exemple

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.

Droit: webhooks

Exemple

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

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

Delete a webhook.

Droit: webhooks

Exemple

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

Droit: own:listings:write | own:inquiries:read

Exemple

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.

Droit: own:listings:write

Paramètre	Type	Description
`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

Exemple

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.

Droit: own:inquiries:read

Paramètre	Type	Description
`status`	string	Filter by status

Exemple

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

GET `/api/v1/me/bookings`

Your orders within a period.

Droit: own:inquiries:read

Paramètre	Type	Description
`from, to`	YYYY-MM-DD	Period (default: today to +12 months)

Exemple

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.

Droit: own:calendar:write

Exemple

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

Droit: own:calendar:write

Paramètre	Type	Description
`dates`	array	List of dates YYYY-MM-DD (max. 366)
`listing_id`	int	Optional; omitted = all listings
`reason`	string	Optional reason

Exemple

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.

Droit: own:calendar:write

Paramètre	Type	Description
`dates`	array	List of dates YYYY-MM-DD
`listing_id`	int	Optional

Exemple

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

Éditeurs avec de nombreux comptes prestataires : accès multi-comptes sur demande dans l’offre Partner.

Webhooks

Les webhooks informent votre serveur en temps réel (offre Business ou supérieure). Nous envoyons un POST JSON à votre URL ; répondez avec un statut 2xx. Les échecs sont relancés après 1, 5 et 30 minutes puis 2, 6 et 24 heures.

Code	Description
`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)

Vérifier la signature (secret de 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);

Règles d’affichage

Affichez pour chaque offre un lien vers l’url de la réponse. En Free et Starter, ajoutez « via HOPS24 ». Conservez les données 24 heures maximum sans les transmettre. Les coordonnées des prestataires ne sont pas fournies – les demandes passent par HOPS24.

Les conditions d’utilisation de l’API s’appliquent (en allemand).

Documentation de l’API

Authentification

Sandbox

Format des réponses

Codes d’erreur

Limites et quotas

Endpoints

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

Webhooks

Règles d’affichage

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`