Qubihome-API

Verwalten Sie Ihre Anzeigen und empfangen Sie Anfragen in Ihrer eigenen Software. Die Referenz unten ist auf Englisch.

OpenAPI-Dokument (JSON)API-Schlüssel erstellen

Die API ist in den Tarifen Agency und Developer für verifizierte Makler und Agenturen verfügbar. Schlüssel erstellen Sie unter Integrationen.

Schnellstart

curl https://qubihome.vercel.app/api/v1/listings \
  -H "Authorization: Bearer qh_live_..."

curl -X POST https://qubihome.vercel.app/api/v1/listings \
  -H "Authorization: Bearer qh_live_..." \
  -H "Content-Type: application/json" \
  -d '{"category":"apartment","transaction":"sale","title":"Bright flat near the park",
       "description":"Two rooms, renovated kitchen, balcony facing south.",
       "price":245000,"currency":"EUR","country":"PL","city":"Krakow",
       "latitude":50.0614,"longitude":19.9366,"area_m2":52,"rooms":2}'

Endpunkte

Methode	Pfad	Funktion	Berechtigung
GET	/api/v1/listings	List your listings	listings:read
POST	/api/v1/listings	Create a draft listing	listings:write
GET	/api/v1/listings/{id}	Get one of your listings	listings:read
PATCH	/api/v1/listings/{id}	Update a draft or rejected listing	listings:write
POST	/api/v1/listings/{id}/submit	Send a draft to moderation	listings:write
POST	/api/v1/listings/{id}/status	Change the status of a live listing	listings:write
GET	/api/v1/listings/{id}/media	List photos and floor plans	listings:read
POST	/api/v1/listings/{id}/media	Import a photo or floor plan from a public https URL	listings:write
DELETE	/api/v1/listings/{id}/media/{mediaId}	Remove a photo or floor plan	listings:write
GET	/api/v1/leads	List contact requests sent to you	leads:read

Regeln

Authentifizieren Sie jede Anfrage mit Authorization: Bearer YOUR_KEY.
Angelegte Anzeigen sind Entwürfe. Beim Einreichen gehen sie in die Moderation und werden erst nach Freigabe veröffentlicht, genau wie in der Web-App.
120 Anfragen pro Minute und Schlüssel. Überschreitung liefert HTTP 429. Das Anzeigenlimit Ihres Tarifs gilt beim Einreichen.
Fehler sind JSON mit einem "error"-Objekt (code, message, details) und passendem HTTP-Status.
Fotos werden von öffentlichen https-Adressen importiert. Weiterleitungen und private Adressen werden abgelehnt.

Webhooks

Jede Zustellung ist ein POST mit JSON-Body und diesen Headern. Prüfen Sie die Signatur, bevor Sie den Daten vertrauen.

X-Qubihome-Event: lead.created | listing.published | listing.status_changed
X-Qubihome-Delivery: <delivery id>
X-Qubihome-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"));
}

Antworten Sie innerhalb von 8 Sekunden mit einem 2xx-Status. Fehlgeschlagene Zustellungen werden bis zu sechsmal mit wachsenden Abständen wiederholt.