Partner-API · v1

Documentación de la API

Todo lo que necesitas para integrar. Versión 1 · URL base: https://hops24.de/api/v1

Descargar archivo OpenAPI ¿Aún sin clave? Solicitar acceso

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

Autenticación

Envía tu clave en la cabecera en cada llamada. Nunca pongas claves en URLs ni en código público; para llamadas desde el navegador autorizamos tus dominios.

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

Sandbox

Las claves hk_test_ devuelven datos de ejemplo fijos (ofertas 900001–900003) para integrar antes de pasar a producción. Las claves reales empiezan por hk_live_.

Formato de respuesta

Las respuestas correctas contienen data (y meta con paginación en listas); los errores contienen error con code y message. Precios en euros como número; si falta, price_on_request es true.

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

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

Códigos de error

HTTP	Código
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`

Límites y cuotas

Cada llamada cuenta para la cuota mensual. Las cabeceras X-Quota-Limit y X-Quota-Remaining muestran el estado. Si se agota, la API responde 429, sin costes adicionales.

Plan	Solicitudes / mes	Solicitudes / segundo
Free	1.000	2
Starter	25.000	10
Business	250.000	30
Partner	según acuerdo	50

Endpoints

GET `/api/v1/status`

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

Ejemplo

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

Permiso: listings:read

Ejemplo

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.

Permiso: listings:read

Parámetro	Tipo	Descripción
`after`	int	Last processed change ID, initially 0
`limit`	int	Up to 200 changes

Ejemplo

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.

Permiso: listings:read

Parámetro	Tipo	Descripción
`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)

Ejemplo

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.

Permiso: listings:read

Ejemplo

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.

Permiso: availability:read

Parámetro	Tipo	Descripción
`months`	int	Period in months (1–12, default 3)

Ejemplo

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.

Permiso: inquiries:create

Parámetro	Tipo	Descripción
`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

Ejemplo

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.

Permiso: webhooks

Ejemplo

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.

Permiso: webhooks

Parámetro	Tipo	Descripción
`url`	string	Target URL (https only, publicly reachable)
`events`	array	inquiry.created, inquiry.replied

Ejemplo

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.

Permiso: webhooks

Ejemplo

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

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

Delete a webhook.

Permiso: webhooks

Ejemplo

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

Permiso: own:listings:write | own:inquiries:read

Ejemplo

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.

Permiso: own:listings:write

Parámetro	Tipo	Descripción
`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

Ejemplo

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.

Permiso: own:inquiries:read

Parámetro	Tipo	Descripción
`status`	string	Filter by status

Ejemplo

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

GET `/api/v1/me/bookings`

Your orders within a period.

Permiso: own:inquiries:read

Parámetro	Tipo	Descripción
`from, to`	YYYY-MM-DD	Period (default: today to +12 months)

Ejemplo

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.

Permiso: own:calendar:write

Ejemplo

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

Permiso: own:calendar:write

Parámetro	Tipo	Descripción
`dates`	array	List of dates YYYY-MM-DD (max. 366)
`listing_id`	int	Optional; omitted = all listings
`reason`	string	Optional reason

Ejemplo

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.

Permiso: own:calendar:write

Parámetro	Tipo	Descripción
`dates`	array	List of dates YYYY-MM-DD
`listing_id`	int	Optional

Ejemplo

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

Socios de software con muchas cuentas de proveedor: acceso multicuenta bajo consulta en el plan Partner.

Webhooks

Los webhooks avisan a tu servidor al instante (plan Business o superior). Enviamos un POST con JSON a tu URL; responde con un estado 2xx. Los envíos fallidos se repiten tras 1, 5 y 30 minutos y 2, 6 y 24 horas.

Código	Descripción
`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)

Verificar la firma (secreto 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);

Reglas de presentación

Muestra en cada oferta un enlace a la url de la respuesta. En Free y Starter añade «via HOPS24». Guarda los datos como máximo 24 horas y no los cedas. No se facilitan datos de contacto de proveedores: las solicitudes pasan por HOPS24.

Se aplican las condiciones de uso de la API (en alemán).

Documentación de la API

Autenticación

Sandbox

Formato de respuesta

Códigos de error

Límites y cuotas

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

Reglas de presentación

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`