Qubihome API

Zarządzaj ogłoszeniami i odbieraj zapytania we własnym oprogramowaniu. Poniższa dokumentacja jest po angielsku.

API jest dostępne w planach Agency i Developer dla zweryfikowanych agentów i agencji. Klucze utworzysz w sekcji Integracje.

Szybki start

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

Punkty końcowe

Metoda	Ścieżka	Co robi	Zakres
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

Zasady

Uwierzytelniaj każde żądanie nagłówkiem Authorization: Bearer YOUR_KEY.
Tworzone ogłoszenia są szkicami. Zgłoszenie wysyła je do moderacji; stają się aktywne dopiero po zatwierdzeniu, tak jak w aplikacji webowej.
120 żądań na minutę na klucz. Przekroczenie zwraca HTTP 429. Limit ogłoszeń z Twojego planu obowiązuje przy zgłoszeniach.
Błędy mają format JSON z obiektem "error" zawierającym code, message i details oraz odpowiedni status HTTP.
Zdjęcia są importowane z publicznych adresów https. Przekierowania i adresy prywatne są odrzucane.

Webhooki

Każda dostawa to POST z treścią JSON i poniższymi nagłówkami. Zweryfikuj podpis, zanim zaufasz danym.

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

Odpowiedz dowolnym statusem 2xx w ciągu 8 sekund. Nieudane dostawy są ponawiane do sześciu razy z rosnącymi odstępami.