Το λογισμικό σου, οι κρατήσεις σου.

Το API του CocoBook δίνει σε ένα channel manager, ένα widget κρατήσεων, μια εξαγωγή για το λογιστήριο ή στο δικό σου script πρόσβαση στις κρατήσεις, τη διαθεσιμότητα και τις τιμές ενός ακινήτου. JSON για είσοδο και έξοδο, κλειδιά API με scopes, ασφαλείς επαναλήψεις αιτημάτων, περιγραφή OpenAPI.

REST · JSONΚλειδιά ανά ακίνητο100 αιτήματα/λεπτό

Γρήγορο ξεκίνημα

Στο CocoBook άνοιξε Ρυθμίσεις → Developer και δημιούργησε ένα κλειδί για το ακίνητο που θέλεις να συνδέσεις. Διάλεξε τα δικαιώματα που χρειάζεται· το κλειδί εμφανίζεται μόνο μία φορά. Μετά έλεγξε ότι λειτουργεί:

Αίτημα

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

Απόκριση · 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 υπάρχει μόνο αν το κλειδί έχει λήξη, το image_url μόνο αν το ακίνητο έχει φωτογραφία. Το ίδιο αντικείμενο property επιστρέφεται και από το GET /property.

Βασικό URL: https://api.cocobook.app/v1. Η περιγραφή σε μορφή αναγνώσιμη από μηχανή βρίσκεται στο /v1/openapi.json — φόρτωσέ τη στο Postman, στο Insomnia ή σε έναν γεννήτορα SDK.

Ταυτοποίηση & scopes

Κάθε αίτημα στέλνει το κλειδί στην κεφαλίδα Authorization ως bearer token (λειτουργεί και το X-API-Key: cb_live_…). Ένα κλειδί ανήκει σε ένα ακίνητο: δεν υπάρχει παράμετρος ακινήτου, και ό,τι ανήκει σε άλλο ακίνητο απαντά απλώς 404. Μόνο οι ιδιοκτήτες και οι διαχειριστές μπορούν να δημιουργούν και να ανακαλούν κλειδιά· η ανάκληση ισχύει αμέσως.

ScopeΕπιτρέπει
bookings:readΛίστα και ανάγνωση κρατήσεων, διαθεσιμότητας, προσφορών τιμών
bookings:writeΔημιουργία, αλλαγή και ακύρωση κρατήσεων· δημιουργία μπλοκαρισμάτων
property:readΑνάγνωση του προφίλ του ακινήτου και των μονάδων του
property:writeΑλλαγή του προφίλ του ακινήτου (όνομα, νόμισμα, τοποθεσία)

Τι παίρνεις όταν το διαπιστευτήριο λείπει, είναι λάθος ή δεν έχει το απαιτούμενο scope:

Χωρίς κλειδί · 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_…'."}}

Άγνωστο, ανακληθέν ή ληγμένο κλειδί · 401

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

Κλειδί χωρίς το scope · 403

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

Το 401 είναι σκόπιμα ίδιο για ένα ανακληθέν κλειδί και για ένα που δεν υπήρξε ποτέ. Το GET /me δεν χρειάζεται κανένα scope, οπότε είναι η σωστή κλήση για ένα κουμπί «δοκιμή σύνδεσης».

Αντιμετώπισε ένα κλειδί σαν κωδικό πρόσβασης: χρησιμοποίησέ το από τον server σου, ποτέ από μια ιστοσελίδα ή μια εφαρμογή κινητού, και δώσε σε κάθε ενσωμάτωση το δικό της κλειδί με τα ελάχιστα scopes που χρειάζεται.

Συμβάσεις

  • JSON, UTF-8. Στείλε Content-Type: application/json. Τα άγνωστα πεδία απορρίπτονται, ώστε τα τυπογραφικά λάθη να εμφανίζονται ως 400.
  • Τα id είναι αδιαφανή strings. Οι ημερομηνίες είναι YYYY-MM-DD· το check_out και κάθε to είναι αποκλειστικά (1–4 Ιουνίου είναι τρία βράδια). Οι χρονοσφραγίδες είναι RFC 3339 σε UTC.
  • Οι λίστες έρχονται ως {"data": […], "page", "per_page", "total"}· το per_page φτάνει έως 200.
  • Τα σφάλματα έρχονται ως {"error": {"code", "message", "details"}}. Το details κατονομάζει τα προβληματικά πεδία.
  • Τα προαιρετικά πεδία κειμένου (guest.email, guest.phone, notes, image_url, expires_at) παραλείπονται από τις αποκρίσεις όταν είναι κενά, αντί να στέλνονται ως null.
  • Τίποτα δεν αποθηκεύεται στην cache (Cache-Control: no-store). Η έκδοση είναι στο path· μέσα στο v1 πεδία μόνο προστίθενται.

Κάθε ταυτοποιημένη απόκριση φέρει τις κεφαλίδες ορίου αιτημάτων, ό,τι κι αν είναι το 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

Endpoints

EndpointScopeΤι κάνει
GET/me—Το κλειδί και το ακίνητό του
GET/propertyproperty:readΠροφίλ
PATCH/propertyproperty:writeΑλλαγή ονόματος, νομίσματος, τοποθεσίας
GET/units, /units/{id}property:readΜονάδες με χωρητικότητα, βασική τιμή, πρωινό
GET/availabilitybookings:readΚατειλημμένα διαστήματα ανά μονάδα μέσα σε ένα παράθυρο
GET/quotebookings:readΤιμή μιας διαμονής
GET/bookings, /bookings/{id}bookings:readΛίστα με φίλτρα, ανάγνωση μίας
POST/bookingsbookings:writeΔημιουργία κράτησης ή μπλοκαρίσματος
PATCH/bookings/{id}bookings:writeΑλλαγή οποιουδήποτε πεδίου
DELETE/bookings/{id}bookings:writeΑκύρωση (και με POST …/cancel)

Κρατήσεις

Τα παρακάτω παραδείγματα ακολουθούν μία κράτηση σε όλη της τη ζωή: δημιουργείται για μια διαμονή τον Ιούλιο, διαβάζεται, παρατείνεται κατά ένα βράδυ και μετά ακυρώνεται. Όλα χρησιμοποιούν τη μονάδα «Sea view» από την ενότητα Ακίνητο & μονάδες.

Δημιουργία

Αίτημα

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

Υποχρεωτικά: unit_id, check_in, check_out, guest.name. Το status είναι από προεπιλογή confirmed (ή στείλε pending· οι κρατήσεις που αποδέχεται η ομάδα στο πρόγραμμα διαχείρισης χωρίς προκαταβολή επιστρέφουν ως deposit_pending, που κρατά τις ημερομηνίες όπως το confirmed)· το source είναι από προεπιλογή direct και παίρνει μία από τις τιμές direct, airbnb, booking_com, agoda, referral. Μια διαμονή είναι το πολύ 365 βράδια. Αν παραλείψεις το price, η διαμονή τιμολογείται από τις σεζόν του ακινήτου συν το πρωινό, ακριβώς όπως θα έκανε το /quote. Η απάντηση είναι 201 με την κράτηση:

Απόκριση · 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 είναι το σύνολο της διαμονής μαζί με το πρωινό (εδώ 300 για το δωμάτιο συν 30 για το πρωινό)· το breakfast.price είναι μόνο αυτή η γραμμή. Το code είναι η σύντομη αναφορά που βλέπει το προσωπικό στο CocoBook.

Αν στείλεις πεδίο που το API δεν γνωρίζει ή JSON με λάθος μορφή, ολόκληρο το σώμα απορρίπτεται:

Απόκριση · 400

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

Ένα σώμα σωστής μορφής με λάθος τιμές κατονομάζει όλα τα προβληματικά πεδία μαζί, ώστε ένας γύρος να αρκεί για να διορθωθεί μια φόρμα:

Απόκριση · 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"
    }
  }
}

Η μονάδα πρέπει να είναι ελεύθερη για όλη τη διαμονή. Το περιβάλλον διαχείρισης επιτρέπει στο προσωπικό να δημιουργεί επικαλυπτόμενες κρατήσεις και τις επισημαίνει ως συγκρούσεις· το API αντίθετα τις αρνείται: 409 unit_unavailable όταν επικαλύπτεται άλλη ενεργή κράτηση, 409 unit_blocked όταν επικαλύπτεται μπλοκάρισμα. Το details.conflicting_booking_ids λέει ποιες:

Απόκριση · 409

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

Ασφαλείς επαναλήψεις

Στείλε μια κεφαλίδα Idempotency-Key (οποιοδήποτε string μοναδικό για την προσπάθεια, έως 255 χαρακτήρες) και μια επανάληψη μετά από timeout επιστρέφει την κράτηση που δημιουργήθηκε την πρώτη φορά αντί για διπλότυπο. Τα κλειδιά απομνημονεύονται για 24 ώρες ανά κλειδί API. Η επανάληψη απαντά 200, όχι 201, και σημαίνεται με μια κεφαλίδα:

Το ίδιο αίτημα ξανά · 200

HTTP/1.1 200 OK
Idempotent-Replayed: true

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

Συγκρίνεται μόνο το κλειδί, όχι το σώμα, οπότε μην ξαναχρησιμοποιείς ποτέ ένα κλειδί για άλλη παραγγελία.

Μπλοκαρίσματα

Όρισε το status σε cleaning, owner ή blocked για να κλείσεις ημερομηνίες χωρίς επισκέπτη. Το guest.name γίνεται τότε προαιρετικό και το μπλοκάρισμα δεν τιμολογείται ποτέ, ό,τι κι αν στείλεις:

Αίτημα

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

Απόκριση · 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"
}

Τα μπλοκαρίσματα παίρνουν κωδικό BL- και κενό guest. Η ομάδα σου βλέπει κάθε εγγραφή μέσω API στις ειδοποιήσεις του CocoBook, με το όνομα του κλειδιού.

Ανάγνωση μίας

Αίτημα

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

Απαντά 200 με το ίδιο αντικείμενο κράτησης όπως στη δημιουργία. Ένα id από άλλο ακίνητο, ένα τυπογραφικό λάθος ή μια διαγραμμένη εγγραφή δίνουν όλα την ίδια απάντηση:

Απόκριση · 404

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

Λίστα και συγχρονισμός

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

Απόκριση · 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
}

Ταξινόμηση κατά check-in. Το total μετράει όλα τα αποτελέσματα σε όλες τις σελίδες· το page ξεκινά από 1 και το per_page είναι από προεπιλογή 50. Τα from και to επιλέγουν τις κρατήσεις που επικαλύπτουν το παράθυρο, όχι μόνο όσες ξεκινούν μέσα σε αυτό. Τα μπλοκαρίσματα παραλείπονται, εκτός αν δώσεις include_blocks=true ή αν το status τα κατονομάζει. Οι ακυρωμένες κρατήσεις εξακολουθούν να εμφανίζονται με status: cancelled.

Μια κράτηση που το προσωπικό δημιούργησε πάνω σε άλλη στο CocoBook επιστρέφει με status: conflict· μπορείς να φιλτράρεις με αυτό, αλλά το API δεν δημιουργεί ποτέ τέτοια.

Για συγχρονισμό, θυμήσου πότε έκανες την τελευταία ερώτηση και ζήτα ό,τι άλλαξε από τότε· μια ακύρωση ή μια αλλαγή στο CocoBook ανανεώνει το updated_at, οπότε εμφανίζεται:

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

Αλλαγή

Το PATCH δέχεται τα ίδια πεδία με τη δημιουργία· αλλάζουν μόνο όσα στέλνεις. Η μετακίνηση ημερομηνιών ή μονάδας ελέγχει ξανά τις επικαλύψεις (οι ημερομηνίες της ίδιας της κράτησης δεν μετράνε) και, αν δεν σταλεί price, ξανατιμολογεί τη διαμονή. Παράταση της διαμονής της Ana κατά ένα βράδυ:

Αίτημα

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

Απόκριση · 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"
}

Αν το μπλοκάρισμα καθαρισμού από πάνω ήταν ακόμη στις 6–7 Ιουλίου, η απάντηση θα ήταν 409 unit_blocked. Στείλε "" για να καθαρίσεις το guest.email, το guest.phone ή το notes· για να κρατήσεις την τιμή που συμφώνησες ενώ μετακινείς ημερομηνίες, στείλ' την μαζί:

Αίτημα

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

Ακύρωση

Αίτημα

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

Απόκριση · 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 και PATCH με {"status": "cancelled"} κάνουν το ίδιο. Η ακύρωση κρατά την κράτηση με status: cancelled και ελευθερώνει τις ημερομηνίες και τη στάθμευσή της· η διπλή ακύρωση δεν είναι πρόβλημα και απαντά ξανά 200.

Διαθεσιμότητα & προσφορές τιμών

Διαθεσιμότητα

Αίτημα

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_…"

Απόκριση · 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)"}
      ]
    }
  ]
}

Ό,τι δεν είναι ελεύθερο μέσα στο παράθυρο, ανά μονάδα: ενεργές κρατήσεις (type: booking, με το id για να τις διαβάσεις), μπλοκαρίσματα και γεγονότα external που εισάγονται από τα iCal feeds που έχει συνδέσει ο ιδιοκτήτης (Airbnb, Booking.com). Παράλειψε το unit_id για να πάρεις όλες τις μονάδες· μια μονάδα χωρίς τίποτα έχει "busy": []. Παράθυρα έως 366 ημερών. Ό,τι δεν αναφέρεται είναι ελεύθερο, μαζί με τις ακυρωμένες κρατήσεις.

Και οι δύο ημερομηνίες είναι υποχρεωτικές και το παράθυρο πρέπει να είναι τουλάχιστον μία ημέρα:

Απόκριση · 400

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

Προσφορά τιμής

Αίτημα

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_…"

Απόκριση · 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}
  ]
}

Ανά βράδυ: η τιμή ανά μονάδα της σεζόν, αν έχει οριστεί (η τιμή Σαββατοκύριακου της στις ημέρες Σαββατοκύριακου του ακινήτου), αλλιώς η βασική τιμή ή η τιμή Σαββατοκύριακου της μονάδας επί τον πολλαπλασιαστή της σεζόν, αλλιώς σκέτη η βασική τιμή ή η τιμή Σαββατοκύριακου. Το season λείπει στα βράδια εκτός σεζόν. Το πρωινό είναι επισκέπτες × βράδια × η τιμή ανά άτομο της μονάδας· μια μονάδα χωρίς πρωινό δίνει πάντα {"guests": 0, "price": 0}. Το total είναι room συν breakfast.price, και μια κράτηση που δημιουργείται χωρίς τιμή παίρνει ακριβώς αυτό το σύνολο.

Μια προσφορά τιμής δεν δεσμεύει τίποτα και δεν ελέγχει διαθεσιμότητα. Η συνήθης ροή για ένα widget κρατήσεων είναι /availability για να δείξεις ελεύθερες ημερομηνίες, /quote για να δείξεις την τιμή, μετά POST /bookings, και ένα 409 σημαίνει «κάποιος πρόλαβε πρώτος».

Ακίνητο & μονάδες

Ακίνητο

Αίτημα

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

Απόκριση · 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"
}

Αλλάζουν μόνο τα πεδία που στέλνεις· και μέσα στο location, οπότε το {"location": {"town": "Chernomorets"}} κρατά τη χώρα και την περιοχή. Το GET /v1/property επιστρέφει το ίδιο αντικείμενο. Νομίσματα: EUR USD GBP TRY BGN RON CHF· το country είναι κωδικός ISO 3166-1 alpha-2· τα country_name και label προκύπτουν αυτόματα και είναι μόνο για ανάγνωση. Μια αλλαγή στο προφίλ ανανεώνει αμέσως τον ιστότοπο για επισκέπτες του ακινήτου και την καταχώρισή του στην Εξερεύνηση καταλυμάτων. Η φωτογραφία δεν αλλάζει μέσω του API.

Απόκριση · 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"}}}

Μονάδες

Αίτημα

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

Απόκριση · 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
    }
  ]
}

Οι μονάδες είναι μόνο για ανάγνωση μέσω του API και η λίστα δεν σελιδοποιείται. Το base_price είναι η τιμή καθημερινής εκτός σεζόν και το weekend_price η τιμή στις ημέρες Σαββατοκύριακου του ακινήτου, με το 0 να σημαίνει ίδια με το base_price. Το breakfast_price είναι ανά άτομο ανά βράδυ, με το 0 να σημαίνει ότι περιλαμβάνεται. Οι σεζόν αλλάζουν το πραγματικό κόστος ενός βραδιού, οπότε χρησιμοποίησε το /quote για πραγματική τιμή. Το GET /v1/units/{id} επιστρέφει ένα μόνο αντικείμενο μονάδας· το type είναι ένα από studio, apartment, villa, room, loft.

Σφάλματα & όρια

ΚωδικόςHTTPΣημασία
missing_api_key401Δεν στάλθηκε διαπιστευτήριο
invalid_api_key401Άγνωστο, ανακληθέν ή ληγμένο κλειδί
insufficient_scope403Το κλειδί δεν έχει το scope
validation_error400Κάποιο πεδίο είναι λάθος — δες το details
invalid_json400Όχι JSON, κενό, πάνω από 64 KB ή άγνωστα πεδία
not_found404Δεν υπάρχει τέτοιος πόρος σε αυτό το ακίνητο
unit_unavailable409Επικαλύπτεται άλλη ενεργή κράτηση
unit_blocked409Επικαλύπτεται μπλοκάρισμα
rate_limited429Πάνω από 100 αιτήματα σε ένα λεπτό· περίμενε όσο λέει το Retry-After
internal_error500Δικό μας λάθος· δοκίμασε ξανά αργότερα

Το details υπάρχει στο validation_error (ένα μήνυμα ανά πεδίο, τα ένθετα πεδία ως guest.email ή location.country, οι παράμετροι query με το όνομά τους) και στα δύο 409 (conflicting_booking_ids). Κάθε άλλο σφάλμα έχει μόνο code και message.

Όριο αιτημάτων

Κάθε κλειδί μπορεί να κάνει 100 αιτήματα ανά λεπτό. Το παράθυρο είναι το λεπτό του ρολογιού, κοινό για όλους τους servers μας, και μηδενίζεται στην αρχή του επόμενου λεπτού, όχι 60 δευτερόλεπτα μετά την πρώτη σου κλήση. Κάθε ταυτοποιημένη απόκριση φέρει X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset (δευτερόλεπτα μέχρι να μηδενιστεί το παράθυρο)· μετράνε μόνο τα αιτήματα με έγκυρο κλειδί. Το αίτημα 101 μέσα σε ένα παράθυρο παίρνει:

Απόκριση · 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."}}

Κράτα σταθερό τον ρυθμό μιας μαζικής εισαγωγής παρακολουθώντας το X-RateLimit-Remaining, και σε ένα 429 περίμενε Retry-After δευτερόλεπτα αντί να ξαναδοκιμάσεις αμέσως.

Καλές πρακτικές

  • Ένα κλειδί ανά ενσωμάτωση, με το όνομά της, και μόνο με τα scopes που χρειάζεται. Ανακάλεσε τα κλειδιά που δεν χρησιμοποιείς πια· δώσε λήξη στα βραχύβια κλειδιά.
  • Ρώτα με updated_since αντί να ξαναφέρνεις τα πάντα.
  • Αντιμετώπισε το 409 ως κανονικό αποτέλεσμα: διάβασε ξανά το /availability και πρότεινε άλλες ημερομηνίες.
  • Ξαναδοκίμασε ένα 429 μετά το Retry-After και τα 5xx με backoff, πάντα με Idempotency-Key στις δημιουργίες.
  • Διάβαζε μόνο τα πεδία που χρειάζεσαι και αγνόησε όσα νέα εμφανιστούν: οι αποκρίσεις αποκτούν πεδία μέσα στο v1, δεν χάνουν ποτέ.

Έχεις ερωτήσεις ή μια περίπτωση χρήσης που το API δεν καλύπτει ακόμη; Γράψε μας στο hello@cocobook.app.