Deine Software, deine Buchungen.

Die CocoBook-API gibt einem Channel-Manager, einem Buchungs-Widget, einem Buchhaltungsexport oder deinem eigenen Skript Zugriff auf die Buchungen, die Verfügbarkeit und die Preise einer Unterkunft. JSON rein und raus, API-Schlüssel mit Berechtigungen, sichere Wiederholungen und eine OpenAPI-Beschreibung.

REST · JSONSchlüssel pro Unterkunft100 Anfr./Min.

Schnellstart

Öffne in CocoBook Einstellungen → Entwickler und erstelle einen Schlüssel für die Unterkunft, die du anbinden willst. Wähle die Berechtigungen, die er braucht; der Schlüssel wird nur einmal angezeigt. Prüfe danach, ob er funktioniert:

Anfrage

curl https://api.cocobook.app/v1/me \
  -H "Authorization: Bearer cb_live_3fK9aBxQ7mNp2vLw8rTz4hJd6kYs1eCgU5oWnR0i"

Antwort · 200

{
  "key": {
    "id": "a1c3e5f7-9b2d-4e6f-8a0c-2d4f6b8a0c1e",
    "name": "Channel manager",
    "prefix": "cb_live_3fK9aB",
    "scopes": ["bookings:read", "bookings:write"],
    "created_at": "2026-10-14T09:12:00Z",
    "expires_at": "2027-10-14T09:12:00Z"
  },
  "property": {
    "id": "7d2f8a1c-9e4b-4d6a-8c3f-1b5e7a9d2c60",
    "name": "Sea House",
    "currency": "EUR",
    "location": {
      "country": "BG",
      "country_name": "Bulgaria",
      "region": "Burgas",
      "town": "Sozopol",
      "label": "Sozopol, Bulgaria"
    },
    "image_url": "https://cocobook.app/static/uploads/properties/7d2f8a1c.jpg",
    "created_at": "2026-03-02T15:40:11Z"
  }
}

expires_at erscheint nur, wenn der Schlüssel ein Ablaufdatum hat, und image_url nur, wenn die Unterkunft ein Bild hat. Dasselbe property-Objekt liefert auch GET /property.

Basis-URL: https://api.cocobook.app/v1. Die maschinenlesbare Beschreibung liegt unter /v1/openapi.json – lade sie in Postman, Insomnia oder einen SDK-Generator.

Authentifizierung & Berechtigungen

Jede Anfrage trägt den Schlüssel im Authorization-Header als Bearer-Token (X-API-Key: cb_live_… geht auch). Ein Schlüssel gehört zu genau einer Unterkunft: Es gibt keinen Unterkunftsparameter, und alles aus einer anderen Unterkunft liefert einfach 404. Nur Eigentümer und Administratoren können Schlüssel erstellen und widerrufen; ein Widerruf wirkt sofort.

BerechtigungErlaubt
bookings:readBuchungen, Verfügbarkeit und Preisangebote auflisten und lesen
bookings:writeBuchungen anlegen, ändern und stornieren; Sperren anlegen
property:readDas Profil der Unterkunft und ihre Einheiten lesen
property:writeDas Profil der Unterkunft ändern (Name, Währung, Standort)

Das bekommst du zurück, wenn die Zugangsdaten fehlen, falsch sind oder die Berechtigung fehlt:

Kein Schlüssel · 401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="cocobook-api"

{"error": {"code": "missing_api_key", "message": "Send the API key as 'Authorization: Bearer cb_live_…'."}}

Unbekannter, widerrufener oder abgelaufener Schlüssel · 401

{"error": {"code": "invalid_api_key", "message": "The API key is not valid."}}

Schlüssel ohne Berechtigung · 403

{"error": {"code": "insufficient_scope", "message": "This key does not have the 'bookings:write' scope."}}

Der 401 ist bewusst identisch für einen widerrufenen Schlüssel und einen, den es nie gab. GET /me braucht keine Berechtigung und ist damit der richtige Aufruf für eine „Verbindung testen“-Schaltfläche.

Behandle einen Schlüssel wie ein Passwort: Nutze ihn von deinem Server aus, nie aus einer Webseite oder einer mobilen App, und gib jeder Integration einen eigenen Schlüssel mit den minimal nötigen Berechtigungen.

Konventionen

  • JSON, UTF-8. Sende Content-Type: application/json. Unbekannte Felder werden abgelehnt, damit Tippfehler als 400 auffallen.
  • IDs sind undurchsichtige Strings. Datumsangaben sind YYYY-MM-DD; check_out und jedes to sind exklusiv (1. bis 4. Juni sind drei Nächte). Zeitstempel sind RFC 3339 in UTC.
  • Listen kommen als {"data": […], "page", "per_page", "total"}; per_page bis 200.
  • Fehler kommen als {"error": {"code", "message", "details"}}. details nennt die fehlerhaften Felder.
  • Optionale Textfelder (guest.email, guest.phone, notes, image_url, expires_at) werden in Antworten weggelassen, wenn sie leer sind, statt als null gesendet zu werden.
  • Nichts wird gecacht (Cache-Control: no-store). Die Version steht im Pfad; innerhalb von v1 kommen nur Felder hinzu.

Jede authentifizierte Antwort enthält die Rate-Limit-Header, unabhängig vom Status:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 37

Endpunkte

EndpunktBerechtigungFunktion
GET/me—Der Schlüssel und seine Unterkunft
GET/propertyproperty:readProfil
PATCH/propertyproperty:writeName, Währung und Standort ändern
GET/units, /units/{id}property:readEinheiten mit Kapazität, Grundpreis und Frühstück
GET/availabilitybookings:readBelegte Zeiträume pro Einheit in einem Zeitraum
GET/quotebookings:readPreis eines Aufenthalts berechnen
GET/bookings, /bookings/{id}bookings:readMit Filtern auflisten, einzeln lesen
POST/bookingsbookings:writeBuchung oder Sperre anlegen
PATCH/bookings/{id}bookings:writeBeliebige Felder ändern
DELETE/bookings/{id}bookings:writeStornieren (auch POST …/cancel)

Buchungen

Die folgenden Beispiele begleiten eine Buchung durch ihr ganzes Leben: Sie wird für einen Aufenthalt im Juli angelegt, gelesen, um eine Nacht verlängert und dann storniert. Alle nutzen die Einheit „Sea view“ aus Unterkunft & Einheiten.

Anlegen

Anfrage

curl -X POST https://api.cocobook.app/v1/bookings \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8812" \
  -d '{
    "unit_id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47",
    "check_in": "2026-07-03",
    "check_out": "2026-07-06",
    "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
    "source": "booking_com",
    "breakfast_guests": 2,
    "deposit": 100
  }'

Pflichtfelder: unit_id, check_in, check_out, guest.name. status ist standardmäßig confirmed (oder sende pending; Buchungen, die das Team im Verwaltungsbereich ohne Anzahlung annimmt, kommen als deposit_pending zurück, das die Tage genauso blockiert wie confirmed); source ist standardmäßig direct und kann direct, airbnb, booking_com, agoda oder referral sein. Aufenthalte haben höchstens 365 Nächte. Lässt du price weg, wird der Aufenthalt aus den Saisons der Unterkunft plus Frühstück berechnet – genau so, wie es /quote tun würde. Die Antwort ist 201 mit der Buchung:

Antwort · 201

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-06",
  "nights": 3,
  "status": "confirmed",
  "source": "booking_com",
  "price": 330,
  "deposit": 100,
  "currency": "EUR",
  "breakfast": {"guests": 2, "price": 30},
  "created_at": "2026-10-14T09:14:02Z",
  "updated_at": "2026-10-14T09:14:02Z"
}

price ist der Gesamtpreis des Aufenthalts inklusive Frühstück (hier 300 für das Zimmer plus 30 für das Frühstück); breakfast.price ist diese Position einzeln. code ist die kurze Referenz, die das Team in CocoBook sieht.

Sendest du ein Feld, das die API nicht kennt, oder fehlerhaftes JSON, wird der gesamte Body abgelehnt:

Antwort · 400

{"error": {"code": "invalid_json", "message": "json: unknown field \"check_int\""}}

Ein gültiger Body mit falschen Werten nennt alle fehlerhaften Felder auf einmal – ein einziger Durchlauf reicht also, um ein Formular zu korrigieren:

Antwort · 400

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "check_out": "must be after check_in",
      "guest.email": "must be a valid email address",
      "source": "must be direct, airbnb, booking_com, agoda or referral"
    }
  }
}

Die Einheit muss für den gesamten Aufenthalt frei sein. Die Verwaltungsoberfläche lässt das Team überlappende Buchungen anlegen und markiert sie als Konflikte; die API lehnt sie dagegen ab: 409 unit_unavailable, wenn sich eine andere aktive Buchung überschneidet, und 409 unit_blocked, wenn sich eine Sperre überschneidet. details.conflicting_booking_ids nennt die betroffenen:

Antwort · 409

{
  "error": {
    "code": "unit_unavailable",
    "message": "The unit already has a booking overlapping these dates.",
    "details": {"conflicting_booking_ids": ["0b1c7d9e-5f3a-4b2c-8e6d-7a9f1c3e5b20"]}
  }
}

Sichere Wiederholungen

Sende einen Idempotency-Key-Header (ein beliebiger, für diesen Versuch eindeutiger String mit bis zu 255 Zeichen), und eine Wiederholung nach einem Timeout liefert die beim ersten Mal angelegte Buchung statt eines Duplikats. Die Schlüssel werden pro API-Schlüssel 24 Stunden lang gespeichert. Die Wiederholung liefert 200, nicht 201, und ist mit einem Header gekennzeichnet:

Dieselbe Anfrage noch einmal · 200

HTTP/1.1 200 OK
Idempotent-Replayed: true

{"id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468", "code": "B-4762", …}

Verglichen wird nur der Schlüssel, nicht der Body – verwende einen Schlüssel also nie für eine andere Bestellung wieder.

Sperren

Setze status auf cleaning, owner oder blocked, um Tage ohne Gast zu sperren. Dann ist guest.name optional, und eine Sperre hat nie einen Preis, egal was du sendest:

Anfrage

POST /v1/bookings
{"unit_id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "check_in": "2026-07-06", "check_out": "2026-07-07", "status": "cleaning"}

Antwort · 201

{
  "id": "c58a2f61-0d4e-4b9a-a3c7-6e1f8b2d9a05",
  "code": "BL-2210",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {},
  "check_in": "2026-07-06",
  "check_out": "2026-07-07",
  "nights": 1,
  "status": "cleaning",
  "source": "direct",
  "price": 0,
  "deposit": 0,
  "currency": "EUR",
  "breakfast": {"guests": 0, "price": 0},
  "created_at": "2026-10-14T09:15:30Z",
  "updated_at": "2026-10-14T09:15:30Z"
}

Sperren bekommen einen BL--Code und ein leeres guest. Dein Team sieht jeden Schreibzugriff über die API in den CocoBook-Benachrichtigungen, mit dem Namen des Schlüssels.

Einzeln lesen

Anfrage

curl https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…"

Antwortet mit 200 und demselben Buchungsobjekt wie beim Anlegen. Eine ID aus einer anderen Unterkunft, ein Tippfehler oder ein gelöschter Eintrag führen zur selben Antwort:

Antwort · 404

{"error": {"code": "not_found", "message": "No booking with that id."}}

Auflisten & synchronisieren

GET /v1/bookings?from=2026-07-01&to=2026-08-01            # bookings overlapping July
GET /v1/bookings?status=confirmed,pending&unit_id=b0e5…
GET /v1/bookings?updated_since=2026-10-14T09:00:00Z        # poll this for changes
GET /v1/bookings?include_blocks=true&page=2&per_page=100

Antwort · 200

{
  "data": [
    {
      "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
      "code": "B-4762",
      "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
      "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
      "check_in": "2026-07-03", "check_out": "2026-07-06", "nights": 3,
      "status": "confirmed", "source": "booking_com",
      "price": 330, "deposit": 100, "currency": "EUR",
      "breakfast": {"guests": 2, "price": 30},
      "created_at": "2026-10-14T09:14:02Z", "updated_at": "2026-10-14T09:14:02Z"
    },
    {
      "id": "f7a0c3e2-6b1d-4a8f-9c5e-3d2b7f1a8e94",
      "code": "B-1183",
      "unit": {"id": "4f7a9c21-3b8d-4e6a-a1c5-2d9e8b7f6a10", "name": "Garden studio"},
      "guest": {"name": "Tom Weber", "phone": "+49 170 1234567", "nationality": "DE"},
      "check_in": "2026-07-10", "check_out": "2026-07-17", "nights": 7,
      "status": "pending", "source": "direct",
      "price": 560, "deposit": 0, "currency": "EUR",
      "breakfast": {"guests": 0, "price": 0},
      "notes": "Arrives after 22:00",
      "created_at": "2026-10-02T18:03:44Z", "updated_at": "2026-10-02T18:03:44Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 2
}

Sortiert nach Anreisedatum. total zählt alle Treffer über alle Seiten; page beginnt bei 1, und per_page ist standardmäßig 50. from und to wählen Buchungen, die sich mit dem Zeitraum überschneiden, nicht nur solche, die darin beginnen. Sperren werden weggelassen, außer du setzt include_blocks=true oder status nennt sie. Stornierte Buchungen bleiben mit status: cancelled in der Liste.

Eine Buchung, die das Team in CocoBook über eine andere gelegt hat, kommt mit status: conflict zurück; du kannst nach diesem Status filtern, aber die API legt nie selbst eine an.

Zum Synchronisieren speicherst du den Zeitpunkt deiner letzten Abfrage und fragst alles ab, was sich seitdem geändert hat; eine Stornierung oder Bearbeitung in CocoBook aktualisiert updated_at, taucht also auf:

GET /v1/bookings?updated_since=2026-10-14T09:00:00Z&include_blocks=true&per_page=200

Ändern

PATCH akzeptiert dieselben Felder wie das Anlegen; nur die gesendeten ändern sich. Werden Daten oder Einheit verschoben, werden Überschneidungen erneut geprüft (die eigenen Tage der Buchung zählen nie mit), und sofern du keinen price sendest, wird der Preis des Aufenthalts neu berechnet. Anas Aufenthalt um eine Nacht verlängern:

Anfrage

curl -X PATCH https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"check_out": "2026-07-07", "notes": "late arrival"}'

Antwort · 200

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-07",
  "nights": 4,
  "status": "confirmed",
  "source": "booking_com",
  "price": 430,
  "deposit": 100,
  "currency": "EUR",
  "breakfast": {"guests": 2, "price": 40},
  "notes": "late arrival",
  "created_at": "2026-10-14T09:14:02Z",
  "updated_at": "2026-10-14T11:02:19Z"
}

Würde die Reinigungssperre von vorhin noch den 6.–7. Juli belegen, wäre die Antwort 409 unit_blocked gewesen. Sende "", um guest.email, guest.phone oder notes zu leeren; um beim Verschieben der Daten den ausgehandelten Preis zu behalten, sende ihn mit:

Anfrage

PATCH /v1/bookings/{id}
{"check_in": "2026-07-04", "check_out": "2026-07-08", "price": 400, "guest": {"email": ""}}

Stornieren

Anfrage

curl -X DELETE https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…"

Antwort · 200

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "status": "cancelled",
  "check_in": "2026-07-03",
  "check_out": "2026-07-07",
  "price": 430,
  "updated_at": "2026-10-15T08:30:00Z",
  …
}

POST /v1/bookings/{id}/cancel und PATCH mit {"status": "cancelled"} machen dasselbe. Beim Stornieren bleibt die Buchung mit status: cancelled erhalten, und ihre Tage und ihr Parkplatz werden frei; zweimal stornieren ist kein Problem und liefert wieder 200.

Verfügbarkeit & Preisangebote

Verfügbarkeit

Anfrage

curl "https://api.cocobook.app/v1/availability?from=2026-07-01&to=2026-07-31&unit_id=b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47" \
  -H "Authorization: Bearer cb_live_…"

Antwort · 200

{
  "from": "2026-07-01",
  "to": "2026-07-31",
  "units": [
    {
      "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
      "busy": [
        {"from": "2026-07-03", "to": "2026-07-06", "type": "booking", "status": "confirmed", "booking_id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468"},
        {"from": "2026-07-06", "to": "2026-07-07", "type": "block", "status": "cleaning"},
        {"from": "2026-07-10", "to": "2026-07-14", "type": "external", "summary": "Airbnb (Not available)"}
      ]
    }
  ]
}

Alles, was im Zeitraum nicht frei ist, pro Einheit: aktive Buchungen (type: booking, mit der ID, damit du sie lesen kannst), Sperren und external-Ereignisse aus den iCal-Feeds, die der Eigentümer verbunden hat (Airbnb, Booking.com). Lass unit_id weg, um alle Einheiten zu bekommen; eine Einheit ohne Belegung hat "busy": []. Zeiträume bis 366 Tage. Alles, was nicht aufgeführt ist, ist frei – auch stornierte Buchungen.

Beide Daten sind Pflicht, und der Zeitraum muss mindestens einen Tag lang sein:

Antwort · 400

{"error": {"code": "validation_error", "message": "One or more fields are invalid.", "details": {"to": "range must be at most 366 days"}}}

Preisangebot

Anfrage

curl "https://api.cocobook.app/v1/quote?unit_id=b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47&check_in=2026-07-03&check_out=2026-07-06&breakfast_guests=2" \
  -H "Authorization: Bearer cb_live_…"

Antwort · 200

{
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-06",
  "nights": 3,
  "currency": "EUR",
  "room": 300,
  "breakfast": {"guests": 2, "price": 30},
  "total": 330,
  "per_night": [
    {"date": "2026-07-03T00:00:00Z", "rate": 90,  "season": "Summer", "weekend": false},
    {"date": "2026-07-04T00:00:00Z", "rate": 105, "season": "Summer", "weekend": true},
    {"date": "2026-07-05T00:00:00Z", "rate": 105, "season": "Summer", "weekend": true}
  ]
}

Pro Nacht: der Einheitspreis der Saison, falls festgelegt (an den Wochenendtagen der Unterkunft dessen Wochenendvariante); sonst der Grund- oder Wochenendpreis der Einheit mal dem Multiplikator der Saison; und sonst einfach der Grund- oder Wochenendpreis. season fehlt bei Nächten, die in keine Saison fallen. Frühstück ist Gäste × Nächte × der Preis pro Person der Einheit; eine Einheit ohne Frühstück liefert immer {"guests": 0, "price": 0}. total ist room plus breakfast.price, und eine ohne Preis angelegte Buchung bekommt genau diese Summe.

Ein Preisangebot reserviert nichts und prüft keine Verfügbarkeit. Der übliche Ablauf eines Buchungs-Widgets ist /availability, um freie Tage zu zeigen, /quote, um den Preis zu zeigen, dann POST /bookings – und ein 409 als „jemand war schneller“ zu behandeln.

Unterkunft & Einheiten

Unterkunft

Anfrage

curl -X PATCH https://api.cocobook.app/v1/property \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sea House", "currency": "EUR", "location": {"country": "BG", "region": "Burgas", "town": "Sozopol"}}'

Antwort · 200

{
  "id": "7d2f8a1c-9e4b-4d6a-8c3f-1b5e7a9d2c60",
  "name": "Sea House",
  "currency": "EUR",
  "location": {
    "country": "BG",
    "country_name": "Bulgaria",
    "region": "Burgas",
    "town": "Sozopol",
    "label": "Sozopol, Bulgaria"
  },
  "image_url": "https://cocobook.app/static/uploads/properties/7d2f8a1c.jpg",
  "created_at": "2026-03-02T15:40:11Z"
}

Nur gesendete Felder ändern sich, auch innerhalb von location – {"location": {"town": "Chernomorets"}} behält also Land und Region. GET /v1/property liefert dasselbe Objekt. Währungen: EUR USD GBP TRY BGN RON CHF; country ist ein ISO-3166-1-Alpha-2-Code; country_name und label werden abgeleitet und sind schreibgeschützt. Eine Profiländerung aktualisiert sofort die Gäste-Website der Unterkunft und ihren Eintrag unter „Unterkünfte entdecken“. Das Bild lässt sich über die API nicht bearbeiten.

Antwort · 400

{"error": {"code": "validation_error", "message": "One or more fields are invalid.", "details": {"currency": "must be one of EUR, USD, GBP, TRY, BGN, RON, CHF", "location.country": "must be an ISO 3166-1 alpha-2 code"}}}

Einheiten

Anfrage

curl https://api.cocobook.app/v1/units \
  -H "Authorization: Bearer cb_live_…"

Antwort · 200

{
  "data": [
    {
      "id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47",
      "name": "Sea view",
      "type": "apartment",
      "capacity": 2,
      "floor": "2",
      "base_price": 75,
      "weekend_price": 90,
      "breakfast": true,
      "breakfast_price": 5
    },
    {
      "id": "4f7a9c21-3b8d-4e6a-a1c5-2d9e8b7f6a10",
      "name": "Garden studio",
      "type": "studio",
      "capacity": 3,
      "floor": "",
      "base_price": 80,
      "weekend_price": 0,
      "breakfast": false,
      "breakfast_price": 0
    }
  ]
}

Einheiten sind in der API schreibgeschützt, und die Liste ist nicht paginiert. base_price ist der Preis unter der Woche außerhalb der Saison und weekend_price der Preis an den Wochenendtagen der Unterkunft; 0 bedeutet dasselbe wie base_price. breakfast_price gilt pro Person und Nacht; 0 bedeutet inklusive. Saisons ändern, was eine Nacht tatsächlich kostet – nutze also /quote für einen echten Preis. GET /v1/units/{id} liefert ein einzelnes Einheitsobjekt; type kann studio, apartment, villa, room oder loft sein.

Fehler & Limits

CodeHTTPBedeutung
missing_api_key401Keine Zugangsdaten gesendet
invalid_api_key401Unbekannter, widerrufener oder abgelaufener Schlüssel
insufficient_scope403Dem Schlüssel fehlt die Berechtigung
validation_error400Ein Feld ist ungültig – siehe details
invalid_json400Kein JSON, leer, größer als 64 KB oder mit unbekannten Feldern
not_found404Die Ressource existiert in dieser Unterkunft nicht
unit_unavailable409Eine andere aktive Buchung überschneidet sich
unit_blocked409Eine Sperre überschneidet sich
rate_limited429Mehr als 100 Anfragen in einer Minute – warte Retry-After ab
internal_error500Unser Fehler – versuch es später noch einmal

details erscheint bei validation_error (eine Meldung pro Feld, verschachtelte Felder wie guest.email oder location.country und Abfrageparameter unter ihrem Namen) und bei den beiden 409 (conflicting_booking_ids). Jeder andere Fehler enthält nur code und message.

Rate-Limit

Jeder Schlüssel darf 100 Anfragen pro Minute stellen. Das Zeitfenster ist die Uhrminute, geteilt über alle unsere Server, und setzt sich zu Beginn der nächsten Minute zurück – nicht 60 Sekunden nach deinem ersten Aufruf. Jede authentifizierte Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Sekunden bis zum Zurücksetzen des Fensters); es zählen nur Anfragen mit gültigem Schlüssel. Die 101. Anfrage in einem Fenster bekommt:

Antwort · 429

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{"error": {"code": "rate_limited", "message": "Too many requests; at most 100 per minute per key."}}

Drossle einen Massenimport anhand von X-RateLimit-Remaining und warte bei einem 429 Retry-After Sekunden, statt sofort erneut zu senden.

Bewährte Praktiken

  • Ein Schlüssel pro Integration, benannt und nur mit den Berechtigungen, die sie braucht. Widerrufe Schlüssel, die du nicht mehr nutzt; gib temporären Schlüsseln ein Ablaufdatum.
  • Frag updated_since ab, statt alles neu herunterzuladen.
  • Behandle ein 409 als normales Ergebnis: Lies /availability erneut und biete andere Daten an.
  • Wiederhole 429 nach Retry-After und 5xx mit zunehmender Wartezeit – beim Anlegen immer mit einem Idempotency-Key.
  • Lies nur die Felder, die du brauchst, und toleriere neue: Innerhalb von v1 bekommen Antworten Felder dazu, verlieren aber nie welche.

Fragen oder ein Anwendungsfall, den die API noch nicht abdeckt? Schreib uns an hello@cocobook.app.