API του OmniStay

Έκδοση 1 · Τελευταία ενημέρωση: 22 Οκτωβρίου 2026

Συνδέστε τα άλλα λογισμικά σας με το OmniStay: λογιστικό πρόγραμμα, πίνακα ελέγχου, εργαλείο συντήρησης, Zapier ή Make. Το API δίνει πρόσβαση στα καταλύματα, τις κρατήσεις, τις εργασίες, τους ιδιοκτήτες και την ομάδα σας, και σας επιτρέπει να κάνετε ενέργειες: εργασίες, προσφορές, τιμολόγια, ημερολόγιο, τιμές… Τα webhooks ειδοποιούν τα λογισμικά σας μόλις φτάσει μια κράτηση, ένα μήνυμα ή μια εργασία. Η AI σας (ChatGPT, Claude, Gemini) συνδέεται κι αυτή, μέσω του διακομιστή MCP.

Με μια ματιά

• Βασική διεύθυνση URL: https://escale-roan.vercel.app/api/v1
• Μορφή: JSON σε UTF-8. Οι ημερομηνίες έχουν τη μορφή AAAA-MM-JJ (έτος-μήνας-ημέρα), οι ώρες HH:MM (ώρα Παρισιού) και τα ποσά είναι σε ευρώ.
• Έλεγχος ταυτότητας: ένα κλειδί API της επιχείρησής σας στην κεφαλίδα Authorization: Bearer esk_….
• Δικαιώματα: κάθε κλειδί είναι μόνο για ανάγνωση ή για ανάγνωση και εγγραφή (για να κάνει αλλαγές: δημιουργία εργασιών και οι 91 ενέργειες).
• Σύνδεση με AI: διακομιστής MCP στη διεύθυνση https://app.omnistay.ai/mcp, σύνδεση μέσω OAuth ή με κλειδί API (λεπτομέρειες).
• Όριο: 120 κλήσεις ανά λεπτό ανά κλειδί.

Δημιουργία κλειδιού

1. Στο OmniStay, ανοίξτε τις Ρυθμίσεις › Κλειδιά API. Πρόσβαση έχουν μόνο ο κάτοχος και οι διαχειριστές του λογαριασμού.
2. Δώστε στο κλειδί το όνομα του λογισμικού που θα συνδέσετε και επιτρέψτε την εγγραφή μόνο αν αυτό το λογισμικό πρέπει να κάνει αλλαγές στο OmniStay.
3. Αντιγράψτε το κλειδί αμέσως: ξεκινά με esk_ και εμφανίζεται μόνο μία φορά. Το OmniStay κρατά μόνο ένα αποτύπωμά του (hash).
4. Ένα κλειδί που δεν χρησιμοποιείτε πια ή που μπορεί να είδε κάποιος άλλος: ανακαλέστε το. Σταματά αμέσως να λειτουργεί.

Έλεγχος ταυτότητας

Κάθε κλήση περιέχει το κλειδί. Για να ελέγξετε ότι λειτουργεί:

curl https://escale-roan.vercel.app/api/v1/me \
  -H "Authorization: Bearer esk_VOTRE_CLE"

{
  "data": {
    "organization": { "id": "11111111-1111-4111-8111-111111111111", "name": "Les Clés du Canal" },
    "key": { "name": "Comptabilité", "prefix": "esk_Ab12Cd", "scopes": ["read"] }
  }
}

Γίνεται επίσης δεκτή η κεφαλίδα X-Api-Key: esk_….

Πόροι

Καταλύματα

GET /properties

{
  "data": [{
    "id": "p1", "name": "Loft Canal Saint-Martin", "internal_name": "Valmy 3e G", "type": "appartement", "status": "active",
    "address": { "street": "42 quai de Valmy", "zip": "75010", "city": "Paris" },
    "surface_m2": 58,
    "capacity": { "guests": 4, "double_beds": 1, "single_beds": 0, "sofa_beds_double": 1, "sofa_beds_single": 0 },
    "check_in": { "from": "16:00", "until": "23:00", "mode": "lockbox" }, "check_out": "11:00",
    "platforms": ["airbnb", "booking"], "base_price": 145, "cleaning_fee": 70,
    "owner_id": "c1", "created_at": "2026-10-17", "updated_at": "2026-10-17T09:12:44.512Z"
  }],
  "total": 6, "limit": 100, "offset": 0
}

Οι κωδικοί πρόσβασης (κλειδοθήκη, κλειδαριά) και το Wi-Fi δεν επιστρέφονται ποτέ από το API.

Κρατήσεις

GET /bookings?from=2026-10-01&to=2026-11-01&property_id=p1

{
  "data": [{
    "id": "cx_8f2a", "property_id": "p1", "platform": "airbnb", "reference": "HMX4K2P9QA", "status": "confirmed",
    "check_in": "2026-10-17", "check_out": "2026-10-21", "nights": 4, "arrival_time": "16:30", "departure_time": null,
    "guest": { "first_name": "Camille", "last_name": "Laurent", "email": "camille@exemple.fr", "phone": "+33 6 12 34 56 78",
               "language": "fr", "country": "France", "count": 2 },
    "amounts": { "currency": "EUR", "guest_paid": 690.8, "accommodation": 600, "nightly": 150, "cleaning": 70, "linen": 15,
                 "tourist_tax": 20.8, "platform_fees": 103.85, "payout": 566.15, "tax_collected_by_platform": true },
    "created_at": "2026-09-30", "updated_at": "2026-10-16T18:02:11.870Z"
  }],
  "total": 1, "limit": 100, "offset": 0
}

Η ημέρα αναχώρησης (check_out) δεν είναι κρατημένη νύχτα. Το platform παίρνει τις τιμές airbnb, booking, vrbo, expedia, direct ή manual.

Εργασίες

GET /missions?from=2026-10-20&to=2026-10-31&type=cleaning

Φίλτρα: from και to (ημερομηνία της εργασίας, συμπεριλαμβάνονται και οι δύο), property_id, member_id, type, status, updated_since.

{
  "data": [{
    "id": "cl_8f2a", "type": "cleaning", "title": "Ménage de fin de séjour", "description": null,
    "property_id": "p1", "booking_id": "cx_8f2a", "member_id": "t1",
    "date": "2026-10-21", "time": "11:00", "duration": "02:30", "pay": 55, "billed": 70, "status": "accepted",
    "report": null, "created_at": "2026-09-30", "updated_at": "2026-10-16T18:02:12.004Z"
  }],
  "total": 1, "limit": 100, "offset": 0
}

Δημιουργία εργασίας

Με κλειδί που έχει δικαίωμα εγγραφής. Η εργασία προτείνεται στο άτομο που επιλέξατε (member_id), αλλιώς στην ομάδα του καταλύματος. Το άτομο την αποδέχεται στην εφαρμογή του και η εργασία εμφανίζεται αμέσως στο OmniStay.

curl -X POST https://escale-roan.vercel.app/api/v1/missions \
  -H "Authorization: Bearer esk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "type": "plumbing", "property_id": "p1", "date": "2026-10-18", "time": "09:00",
        "member_id": "t2", "description": "Fuite sous l’évier de la cuisine" }'

Απόκριση 201 με την εργασία που δημιουργήθηκε, στην ίδια μορφή με το GET /missions.

Ενέργειες

Ό,τι μπορεί να κάνει ο Βοηθός AI στο OmniStay περνά και από το API: 91 ενέργειες (προσφορές, τιμολόγια, κρατήσεις, ημερολόγιο, τιμές, εργασίες, ομάδα και απουσίες, ιδιοκτήτες, καταλύματα, μηνύματα, κριτικές, εγγυήσεις, βλάβες, ζημιές και διαφορές, υποψήφιοι ιδιοκτήτες, εκτιμήσεις εσόδων, υποδοχή επισκεπτών και προγραμματισμένα μηνύματα, φόρος διαμονής, στατιστικά κρατήσεων και πρόβλεψη…), με τους ίδιους ελέγχους: δικαιώματα του ατόμου που δημιούργησε το κλειδί, αρχείο καταγραφής, αναίρεση για 24 ώρες από την εφαρμογή. Η λίστα, με το σχήμα JSON των παραμέτρων κάθε ενέργειας:

curl https://escale-roan.vercel.app/api/v1/actions \
  -H "Authorization: Bearer esk_VOTRE_CLE"

{ "data": [{ "name": "creer_devis", "title": "Créer un devis", "module": "Facturation", "kind": "write", "confirmation": false,
             "description": "…", "input_schema": { "type": "object", "properties": { … } },
             "method": "POST", "path": "/api/v1/actions/creer_devis" }], "total": 91 }

Για να εκτελέσετε μια ενέργεια, στείλτε τις παραμέτρους της σε JSON:

curl -X POST https://escale-roan.vercel.app/api/v1/actions/creer_devis \
  -H "Authorization: Bearer esk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "client": "Sophie Martin", "objet": "Ménage de printemps",
        "lignes": [{ "designation": "Grand ménage", "prix_unitaire": 120 }] }'

{ "status": "done", "message": "Devis en brouillon pour Sophie Martin : « Ménage de printemps »…",
  "data": { "id": "doc_…" }, "url": "https://app.omnistay.ai/app/#/facturation/document/doc_…", "journal_id": "…" }

• Απόκριση 201 όταν η ενέργεια ολοκληρωθεί ("status": "done"), 200 για ανάγνωση ("status": "ok").
• Προσθέστε "dry_run": true για να δείτε τι θα έκανε η ενέργεια, χωρίς να αλλάξει τίποτα: απόκριση "status": "preview" με την προεπισκόπηση.
• Οι ενέργειες με "confirmation": true στέλνουν κάτι ή δεν αναιρούνται (έκδοση τιμολογίου, αποστολή μηνύματος, ημερολόγιο και τιμές που στέλνονται στις πλατφόρμες, χρέωση εγγύησης…). Μέσω του API εκτελούνται αμέσως με την κλήση: δοκιμάστε τις πρώτα με dry_run.
• Οι ενέργειες με "kind": "write" απαιτούν κλειδί με δικαίωμα εγγραφής. Οι αποκρίσεις δεν περιέχουν ποτέ κωδικό πρόσβασης ούτε κωδικό Wi-Fi.

Σύνδεση με AI (MCP)

Το OmniStay είναι διακομιστής MCP (Model Context Protocol): το ChatGPT, το Claude, το Gemini, το Claude Code, το Gemini CLI ή οι δικοί σας agents διαβάζουν δεδομένα και ενεργούν στο OmniStay με τις 91 παραπάνω ενέργειες, ως εργαλεία. Ο χειρισμός του OmniStay από μια AI περιλαμβάνεται στο πρόσθετο Βοηθός AI.

• Διεύθυνση URL: https://app.omnistay.ai/mcp (HTTP «streamable», αποκρίσεις JSON, χωρίς session).
• Εκδόσεις του πρωτοκόλλου: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 και 2026-07-28.
• Σύνδεση OAuth 2.1 (ChatGPT, Claude, Gemini): ανακάλυψη μέσω /.well-known/oauth-protected-resource και /.well-known/oauth-authorization-server, δυναμική εγγραφή πελάτη (/oauth/register) ή έγγραφο μεταδεδομένων πελάτη, υποχρεωτικό PKCE S256, tokens δεσμευμένα στον πόρο, ανανέωση με εναλλαγή (rotation). Ο χρήστης συνδέεται, επιλέγει την επιχείρησή του και μπορεί να επιτρέψει μόνο την ανάγνωση. Αποσυνδέει την AI με ένα κλικ από τις Ρυθμίσεις › Κλειδιά API.
• Σύνδεση με κλειδί API (Claude Code, Gemini CLI, οι agents σας): κεφαλίδα Authorization: Bearer esk_….
• Επιβεβαίωση: τα εργαλεία που στέλνουν κάτι ή δεν αναιρούνται έχουν την παράμετρο confirmer. Χωρίς αυτήν δεν κάνουν τίποτα και επιστρέφουν μια προεπισκόπηση που ξεκινά με «Rien n’est fait» («Δεν έγινε τίποτα»). Η AI τη δείχνει στον χρήστη και, αφού εκείνος συμφωνήσει, καλεί ξανά το εργαλείο με "confirmer": true.
• Αρχείο καταγραφής: κάθε ενέργεια καταγράφεται στις Ρυθμίσεις › Αρχείο καταγραφής AI, στο όνομα του ατόμου που συνέδεσε την AI, και μπορεί να αναιρεθεί για 24 ώρες. 120 κλήσεις ανά λεπτό για κάθε συνδεδεμένη AI.

Στο Claude Code:

claude mcp add --transport http omnistay https://app.omnistay.ai/mcp \
  --header "Authorization: Bearer esk_VOTRE_CLE"

Στο Gemini CLI, στο αρχείο ~/.gemini/settings.json:

{ "mcpServers": { "omnistay": { "httpUrl": "https://app.omnistay.ai/mcp",
                                "headers": { "Authorization": "Bearer esk_VOTRE_CLE" } } } }

ChatGPT, Claude και Gemini: τα ενημερωμένα βήματα βρίσκονται στο OmniStay, στις Ρυθμίσεις › Κλειδιά API.

Webhooks

Το OmniStay ειδοποιεί το λογισμικό σας μόλις συμβεί κάτι: στέλνει ένα POST σε JSON στη διεύθυνση URL που ορίζετε. Εγγραφείτε από την εφαρμογή (Ρυθμίσεις › Ενσωματώσεις, με την «Αποστολή δοκιμής» και τις τελευταίες αποστολές) ή μέσω του API με ένα κλειδί, σύμφωνα με το μοντέλο «REST Hooks».

Οι διαμονές και οι εργασίες που έχουν περάσει, οι παλιές κριτικές και τα παλιά μηνύματα, καθώς και ό,τι προστίθεται με εισαγωγή από προηγούμενο λογισμικό, δεν ενεργοποιούν τίποτα.

Τι λαμβάνει η διεύθυνση URL σας

POST https://votre-outil.exemple.fr/omnistay
Content-Type: application/json; charset=utf-8
User-Agent: OmniStay-Webhooks/1.0
X-OmniStay-Event: booking.created
X-OmniStay-Event-Id: evt_6f1c0b7e2d4a4c1f9b3e8d5a7c2f1e09
X-OmniStay-Delivery: 1842
X-OmniStay-Signature: t=1792656000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_6f1c0b7e2d4a4c1f9b3e8d5a7c2f1e09",
  "type": "booking.created",
  "created_at": "2026-10-22T09:14:03Z",
  "test": false,
  "organization": { "id": "11111111-1111-4111-8111-111111111111", "name": "Les Clés du Canal" },
  "data": {
    "id": "cx_8f2a", "property_id": "p1", "property": { "id": "p1", "name": "Loft Canal Saint-Martin" },
    "platform": "airbnb", "reference": "HMX4K2P9QA", "status": "confirmed",
    "check_in": "2026-10-24", "check_out": "2026-10-28", "nights": 4, "arrival_time": "16:30", "departure_time": null,
    "guest": { "first_name": "Camille", "last_name": "Laurent", "email": "camille@exemple.fr", "phone": "+33 6 12 34 56 78",
               "language": "fr", "country": "France", "count": 2 },
    "amounts": { "currency": "EUR", "guest_paid": 690.8, "payout": 566.15, "…": "…" },
    "created_at": "2026-10-22"
  }
}

• Το data ακολουθεί τη μορφή του API (κράτηση, εργασία…), με το όνομα του καταλύματος (property), του μέλους της ομάδας (member) ή του επισκέπτη (guest). Ποτέ κωδικός πρόσβασης, Wi-Fi, εγγύηση ή δελτίο καταγραφής επισκεπτών.
• Απαντήστε με κωδικό 2xx σε λιγότερο από 8 δευτερόλεπτα. Οι ανακατευθύνσεις δεν ακολουθούνται.
• Το ίδιο συμβάν μπορεί να φτάσει δύο φορές (νέα προσπάθεια): το id σας επιτρέπει να αγνοήσετε ένα διπλότυπο. Η σειρά άφιξης δεν είναι εγγυημένη: τη σειρά τη δίνει το created_at.
• Η «Αποστολή δοκιμής», στην εφαρμογή, στέλνει ένα δείγμα του συμβάντος που επιλέξατε με "test": true και δεδομένα παραδείγματος: υπάρχουν όλα τα πεδία, ώστε το Zapier ή το Make να μάθουν τη δομή των δεδομένων.

Επαλήθευση της υπογραφής

Η κεφαλίδα X-OmniStay-Signature έχει τη μορφή t=<horodatage>,v1=<signature> (horodatage: η χρονοσφραγίδα). Η υπογραφή είναι το HMAC-SHA256 (σε δεκαεξαδική μορφή) του <t>.<corps brut> (corps brut: το ακατέργαστο σώμα), που υπολογίζεται με το μυστικό του webhook (whsec_…, δίνεται κατά τη δημιουργία και εμφανίζεται στην εφαρμογή). Απορρίψτε κάθε χρονοσφραγίδα παλαιότερη των 5 λεπτών.

import crypto from 'node:crypto';

// corps : le texte brut reçu, avant tout JSON.parse
function signatureValable(secret, entete, corps) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(entete || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const attendue = crypto.createHmac('sha256', secret).update(`${m[1]}.${corps}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(attendue), Buffer.from(m[2]));
}

Νέες προσπάθειες και απενεργοποίηση

• Χωρίς απόκριση 2xx: νέα προσπάθεια μετά από 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες και τέλος 8 ώρες (6 προσπάθειες συνολικά), με ακριβώς το ίδιο σώμα και το ίδιο id.
• 24 ώρες συνεχόμενων αποτυχιών: το webhook απενεργοποιείται. Μπορείτε να το ενεργοποιήσετε ξανά από την εφαρμογή.
• Μια απόκριση 410 Gone το απενεργοποιεί αμέσως (μοντέλο REST Hooks).
• Η ανάκληση ενός κλειδιού απενεργοποιεί τα webhooks που δημιούργησε. Το ιστορικό αποστολών διατηρείται για 30 ημέρες.

Εγγραφή μέσω του API

curl -X POST https://escale-roan.vercel.app/api/v1/webhooks \
  -H "Authorization: Bearer esk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://votre-outil.exemple.fr/omnistay", "events": ["booking.created", "booking.cancelled"] }'

Αρκεί ένα κλειδί μόνο για ανάγνωση. Μόνο διευθύνσεις https:// (θύρα 443), ποτέ διεύθυνση IP, τοπική ή εσωτερική διεύθυνση. Έως 20 webhooks ανά επιχείρηση.

Zapier και Make

Το OmniStay δεν έχει επίσημη εφαρμογή στο Zapier ούτε στο Make: η σύνδεση γίνεται μέσω των webhooks (για να ειδοποιείστε) και του κλειδιού API (για να κάνετε ενέργειες). Τα βήματα βρίσκονται στην εφαρμογή, στις Ρυθμίσεις › Ενσωματώσεις. Ο αναλυτικός οδηγός βήμα προς βήμα, με τρία παραδείγματα (κρατήσεις στο Google Sheets, μηνύματα επισκεπτών στο Slack, εργασία που δημιουργείται από μια φόρμα), βρίσκεται στο κέντρο βοήθειας: «Relier OmniStay à Zapier» και «Relier OmniStay à Make» (στα γαλλικά).

Ιδιοκτήτες και ομάδα

GET /owners

{ "data": [{ "id": "c1", "civility": "Mme", "first_name": "Sophie", "last_name": "Martin", "email": "sophie@exemple.fr",
             "phone": "06 12 34 56 78", "address": "8 rue Lepic, 75018 Paris", "commission": { "mode": "percent", "value": 20 },
             "since": "2023-04-02", "property_ids": ["p1", "p2"] }], "total": 1, "limit": 100, "offset": 0 }

GET /team

{ "data": [{ "id": "t1", "first_name": "Fatima", "last_name": "B.", "role": "cleaning", "status": "active",
             "property_ids": ["p1", "p2"] }], "total": 1, "limit": 100, "offset": 0 }

Το role παίρνει τις τιμές cleaning, keys, maintenance ή other. Τα πρώην μέλη της ομάδας δεν εμφανίζονται.

Λίστες και σελιδοποίηση

Οι λίστες επιστρέφουν data, total, limit και offset. Από προεπιλογή, 100 στοιχεία. Το limit φτάνει έως 500. Για την επόμενη σελίδα, αυξήστε το offset: ?limit=100&offset=100. Οι κρατήσεις ταξινομούνται κατά ημερομηνία άφιξης, οι εργασίες κατά ημερομηνία και ώρα.

Σφάλματα

Σε περίπτωση σφάλματος, η απόκριση περιέχει έναν σταθερό κωδικό για τα προγράμματά σας και ένα μήνυμα στα γαλλικά:

{ "error": { "code": "read_only_key", "message": "Cette clé est en lecture seule : créez une clé avec le droit d’écriture." } }

Όρια και ασφάλεια

• Ένα κλειδί δίνει πρόσβαση στα δεδομένα της επιχείρησής σας: φυλάξτε το όπως έναν κωδικό πρόσβασης. Χρησιμοποιήστε το από έναν διακομιστή ή ένα εργαλείο αυτοματοποίησης, ποτέ σε μια ιστοσελίδα ή σε μια δημόσια εφαρμογή.
• Ένα κλειδί βλέπει μόνο τη δική του επιχείρηση. Δεν δίνει ποτέ πρόσβαση στους κωδικούς πρόσβασης, στο Wi-Fi ή στα μέσα πληρωμής. Οι εγγυήσεις αποδεσμεύονται ή χρεώνονται μόνο μέσω των ενεργειών που προβλέπονται γι’ αυτό και καταγράφονται στο αρχείο καταγραφής.
• Τα δεδομένα των επισκεπτών, των ιδιοκτητών και των μελών της ομάδας σας παραμένουν δική σας ευθύνη: συνδέετε μόνο λογισμικό που εμπιστεύεστε και ανακαλείτε ένα κλειδί μόλις δεν το χρειάζεστε πια.
• 120 κλήσεις ανά λεπτό ανά κλειδί, έως 20 ενεργά κλειδιά ανά επιχείρηση.
• Τα endpoints της έκδοσης 1 δεν θα αλλάξουν. Οι νέες δυνατότητες θα προστίθενται ως νέα πεδία ή νέα endpoints.

Αν ζητήσετε βοήθεια, δώστε το όνομα του κλειδιού που χρησιμοποιήσατε, ποτέ το ίδιο το κλειδί.