OmniStay-API

Version 1 · Zuletzt aktualisiert: 22. Oktober 2026

Verbinden Sie Ihre anderen Programme mit OmniStay: Buchhaltung, Dashboard, Wartungstool, Zapier oder Make. Die API gibt Zugriff auf Ihre Unterkünfte, Buchungen, Einsätze, Eigentümer und Ihr Team und ermöglicht Aktionen: Einsätze, Angebote, Rechnungen, Kalender, Preise … Die Webhooks benachrichtigen Ihre Programme, sobald eine Buchung, eine Nachricht oder ein Einsatz eingeht. Auch Ihre KI (ChatGPT, Claude, Gemini) verbindet sich über den MCP-Server.

Kurz gesagt

• Basis-URL: https://escale-roan.vercel.app/api/v1
• Format: JSON in UTF-8. Datumsangaben im Format AAAA-MM-JJ, Uhrzeiten HH:MM (Pariser Zeit), Beträge in Euro.
• Authentifizierung: ein API-Schlüssel Ihrer Agentur im Header Authorization: Bearer esk_….
• Rechte: Jeder Schlüssel ist nur lesend oder lesend und schreibend (zum Handeln: Einsätze anlegen und die 91 Aktionen).
• Verbundene KIs: MCP-Server unter https://app.omnistay.ai/mcp, Verbindung per OAuth oder API-Schlüssel (Details).
• Limit: 120 Aufrufe pro Minute und Schlüssel.

Schlüssel erstellen

1. Öffnen Sie in OmniStay Einstellungen › API-Schlüssel. Nur der Kontoinhaber und die Administratoren haben dort Zugriff.
2. Geben Sie dem Schlüssel den Namen der zu verbindenden Software und erlauben Sie Schreibzugriff nur, wenn diese Software in OmniStay handeln soll.
3. Kopieren Sie den Schlüssel sofort: Er beginnt mit esk_ und wird nur ein einziges Mal angezeigt. OmniStay speichert nur einen Hash davon.
4. Ein Schlüssel, der nicht mehr gebraucht wird oder den jemand anderes gesehen haben könnte: Widerrufen Sie ihn. Er funktioniert sofort nicht mehr.

Authentifizierung

Jeder Aufruf enthält den Schlüssel. So prüfen Sie, ob er funktioniert:

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

Der Header X-Api-Key: esk_… wird ebenfalls akzeptiert.

Ressourcen

Unterkünfte

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
}

Zugangscodes (Schlüsselbox, Schloss) und WLAN werden von der API nie zurückgegeben.

Buchungen

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
}

Der Abreisetag (check_out) ist keine gebuchte Nacht. platform ist airbnb, booking, vrbo, expedia, direct oder manual.

Einsätze

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

Filter: from und to (Datum des Einsatzes, jeweils einschließlich), 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
}

Einsatz anlegen

Mit einem Schlüssel mit Schreibrecht. Der Einsatz wird der gewählten Person (member_id) angeboten, sonst dem Team der Unterkunft; sie nimmt ihn in ihrer App an, und der Einsatz erscheint sofort in 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" }'

Antwort 201 mit dem angelegten Einsatz, im selben Format wie GET /missions.

Aktionen

Alles, was der KI-Assistent in OmniStay kann, geht auch über die API: 91 Aktionen (Angebote, Rechnungen, Buchungen, Kalender, Preise, Einsätze, Team und Abwesenheiten, Eigentümer, Unterkünfte, Nachrichten, Bewertungen, Kautionen, Vorfälle, Schäden und Streitfälle, Interessenten, Einnahmen-Schätzungen, Gästeempfang und geplante Nachrichten, Kurtaxe, Buchungsstatistiken und Prognose …), mit denselben Kontrollen: Rechte der Person, die den Schlüssel erstellt hat, Protokoll, Rückgängigmachen innerhalb von 24 Stunden in der App. Die Liste, mit dem JSON-Schema der Parameter jeder Aktion:

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 }

Um eine Aktion zu starten, senden Sie ihre Parameter als 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": "…" }

• Antwort 201, wenn die Aktion ausgeführt ist ("status": "done"), 200 bei einem Lesezugriff ("status": "ok").
• Fügen Sie "dry_run": true hinzu, um zu sehen, was die Aktion tun würde, ohne etwas zu ändern: Antwort "status": "preview" mit der Vorschau.
• Die Aktionen mit "confirmation": true versenden etwas oder lassen sich nicht rückgängig machen (Rechnung ausstellen, Nachricht senden, Kalender und Preise an die Plattformen übertragen, Kaution abbuchen …). Über die API werden sie sofort beim Aufruf ausgeführt: Testen Sie sie zuerst mit dry_run.
• Die Aktionen mit "kind": "write" erfordern einen Schlüssel mit Schreibrecht. Nie Zugangscodes oder WLAN-Passwörter in den Antworten.

Verbundene KIs (MCP)

OmniStay ist ein MCP-Server (Model Context Protocol): ChatGPT, Claude, Gemini, Claude Code, Gemini CLI oder Ihre eigenen Agenten lesen und handeln in OmniStay mit den 91 obigen Aktionen, in Form von Tools. Die Steuerung von OmniStay aus einer KI gehört zur Option KI-Assistent.

• Adresse: https://app.omnistay.ai/mcp („Streamable HTTP“, JSON-Antworten, ohne Session).
• Protokollversionen: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 und 2026-07-28.
• Verbindung per OAuth 2.1 (ChatGPT, Claude, Gemini): Discovery über /.well-known/oauth-protected-resource und /.well-known/oauth-authorization-server, dynamische Registrierung (/oauth/register) oder Client-Metadaten-Dokument, PKCE S256 verpflichtend, an die Ressource gebundene Tokens, Erneuerung mit Rotation. Die Person meldet sich an, wählt ihre Agentur und kann nur Lesezugriff erlauben; sie trennt die KI mit einem Klick unter Einstellungen › API-Schlüssel.
• Verbindung per API-Schlüssel (Claude Code, Gemini CLI, Ihre Agenten): Header Authorization: Bearer esk_….
• Bestätigung: Tools, die etwas versenden oder sich nicht rückgängig machen lassen, haben einen Parameter confirmer. Ohne ihn tun sie nichts und geben eine Vorschau zurück, die mit „Rien n’est fait“ (Nichts wurde ausgeführt) beginnt; die KI zeigt sie der Person und ruft das Tool nach deren Zustimmung erneut mit "confirmer": true auf.
• Protokoll: Jede Aktion wird unter Einstellungen › KI-Protokoll im Namen der Person festgehalten, die die KI verbunden hat, und lässt sich 24 Stunden lang rückgängig machen. 120 Aufrufe pro Minute und verbundener KI.

Claude Code:

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

Gemini CLI, in ~/.gemini/settings.json:

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

ChatGPT, Claude und Gemini: Die aktuellen Schritte finden Sie in OmniStay unter Einstellungen › API-Schlüssel.

Webhooks

OmniStay benachrichtigt Ihre Software, sobald etwas passiert: Es sendet einen POST mit JSON an die von Ihnen angegebene Adresse. Abonnieren Sie in der App (Einstellungen › Integrationen, mit „Test senden“ und den letzten Zustellungen) oder per API mit einem Schlüssel, nach dem Muster „REST Hooks“.

Vergangene Aufenthalte und Einsätze, ältere Bewertungen und Nachrichten sowie alles, was ein Import aus einer bisherigen Software hinzufügt, lösen nichts aus.

Was Ihre Adresse empfängt

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 übernimmt das Format der API (Buchung, Einsatz …), mit dem Namen der Unterkunft (property), der Person aus dem Team (member) oder des Gastes (guest). Nie Zugangscodes, WLAN, Kaution oder Meldeschein.
• Antworten Sie innerhalb von 8 Sekunden mit einem 2xx-Code; Weiterleitungen werden nicht verfolgt.
• Dasselbe Ereignis kann zweimal ankommen (erneuter Versuch): Mit id lassen sich Duplikate ignorieren. Die Reihenfolge der Zustellung ist nicht garantiert: created_at gibt die Reihenfolge an.
• „Test senden“ in der App verschickt ein Beispiel des gewählten Ereignisses mit "test": true und Beispieldaten: Alle Felder sind enthalten, damit Zapier oder Make die Datenstruktur lernen.

Signatur prüfen

Der Header X-OmniStay-Signature hat den Wert t=<horodatage>,v1=<signature>. Die Signatur ist der HMAC-SHA256 (hexadezimal) von <t>.<corps brut>, berechnet mit dem Secret des Webhooks (whsec_…, bei der Erstellung angezeigt und in der App sichtbar). Lehnen Sie einen Zeitstempel ab, der älter als 5 Minuten ist.

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

Erneute Versuche und Deaktivierung

• Ohne 2xx-Antwort: erneuter Versuch nach 1 Min., 5 Min., 30 Min., 2 Std. und dann 8 Std. (insgesamt 6 Versuche), mit genau demselben Body und derselben id.
• 24 Stunden lang durchgehend Fehler: Der Webhook wird deaktiviert. Er lässt sich in der App wieder aktivieren.
• Eine Antwort 410 Gone deaktiviert ihn sofort (Muster REST Hooks).
• Wird ein Schlüssel widerrufen, werden die damit erstellten Webhooks deaktiviert. Der Zustellverlauf wird 30 Tage aufbewahrt.

Per API abonnieren

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

Ein Schlüssel mit Lesezugriff genügt. Nur Adressen mit https:// (Port 443), nie eine IP-Adresse, lokale oder interne Adresse; höchstens 20 Webhooks pro Agentur.

Zapier und Make

OmniStay hat keine offizielle App in Zapier oder Make: Die Verbindung läuft über die Webhooks (zum Benachrichtigen) und den API-Schlüssel (zum Handeln). Die Schritte finden Sie in der App unter Einstellungen › Integrationen; die Schritt-für-Schritt-Anleitung mit drei Beispielen (Buchungen in Google Sheets, Gästenachrichten in Slack, Einsatz aus einem Formular) steht im Hilfecenter (auf Französisch): „Relier OmniStay à Zapier“ und „Relier OmniStay à Make“.

Eigentümer und Team

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 ist cleaning, keys, maintenance oder other. Ehemalige Teammitglieder erscheinen nicht.

Listen und Paginierung

Listen geben data, total, limit und offset zurück. Standardmäßig 100 Elemente; limit geht bis 500. Für die nächste Seite erhöhen Sie offset: ?limit=100&offset=100. Buchungen sind nach Anreisedatum sortiert, Einsätze nach Datum und Uhrzeit.

Fehler

Bei einem Fehler enthält die Antwort einen stabilen Code für Ihre Programme und eine Meldung auf Französisch:

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

Limits und Sicherheit

• Ein Schlüssel gibt Zugriff auf die Daten Ihrer Agentur: Behandeln Sie ihn wie ein Passwort. Verwenden Sie ihn auf einem Server oder in einem Automatisierungstool, nie in einer Webseite oder einer öffentlichen App.
• Ein Schlüssel sieht nur seine eigene Agentur. Er gibt nie Zugriff auf Zugangscodes, WLAN oder Zahlungsmittel; Kautionen werden nur über die vorgesehenen Aktionen freigegeben oder abgebucht, die im Protokoll festgehalten werden.
• Die Daten Ihrer Gäste, Eigentümer und Teammitglieder bleiben in Ihrer Verantwortung: Verbinden Sie nur vertrauenswürdige Software und widerrufen Sie einen Schlüssel, sobald er nicht mehr gebraucht wird.
• 120 Aufrufe pro Minute und Schlüssel, höchstens 20 aktive Schlüssel pro Agentur.
• Die Endpunkte der Version 1 bleiben unverändert. Neuerungen kommen in Form neuer Felder oder neuer Endpunkte.

Wenn Sie um Hilfe bitten, nennen Sie den Namen des verwendeten Schlüssels, nie den Schlüssel selbst.