API OmniStay

Version 1 · Dernière mise à jour : 17 octobre 2026

Reliez vos autres logiciels à OmniStay : comptabilité, tableau de bord, outil de maintenance, Zapier ou Make. L’API donne accès à vos logements, réservations, missions, propriétaires et à votre équipe, et permet de créer des missions.

En bref

• Adresse de base : https://escale-roan.vercel.app/api/v1
• Format : JSON en UTF-8. Les dates sont au format AAAA-MM-JJ, les heures HH:MM (heure de Paris), les montants en euros.
• Authentification : une clé API de votre conciergerie dans l’en-tête Authorization: Bearer esk_….
• Droits : chaque clé est en lecture seule, ou en lecture et écriture (pour créer des missions).
• Limite : 120 appels par minute et par clé.

Créer une clé

1. Dans OmniStay, ouvrez Réglages › Clés API (mode Avancé) ou Pilote automatique › Clés API (mode Simple). Seuls la propriétaire et les administrateurs du compte y ont accès.
2. Donnez à la clé le nom du logiciel à relier, et autorisez l’écriture seulement si ce logiciel doit créer des missions.
3. Copiez la clé tout de suite : elle commence par esk_ et n’est affichée qu’une seule fois. OmniStay n’en garde qu’une empreinte.
4. Une clé qui ne sert plus, ou qui a pu être vue par quelqu’un d’autre : révoquez-la. Elle cesse aussitôt de fonctionner.

S’authentifier

Chaque appel porte la clé. Pour vérifier qu’elle fonctionne :

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

L’en-tête X-Api-Key: esk_… est aussi accepté.

Ressources

Logements

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
}

Les codes d’accès (boîte à clés, serrure) et le Wi-Fi ne sont jamais renvoyés par l’API.

Réservations

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
}

Le jour de départ (check_out) n’est pas une nuit réservée. platform vaut airbnb, booking, vrbo, expedia, direct ou manual.

Missions

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

Filtres : from et to (date de la mission, incluses), 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
}

Créer une mission

Avec une clé qui a le droit d’écriture. La mission est proposée à la personne choisie (member_id), sinon à l’équipe du logement ; elle l’accepte dans son appli, et la mission apparaît aussitôt dans 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" }'

Réponse 201 avec la mission créée, dans le même format que GET /missions.

Propriétaires et équipe

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 vaut cleaning, keys, maintenance ou other. Les anciens membres de l’équipe n’apparaissent pas.

Listes et pages

Les listes renvoient data, total, limit et offset. Par défaut, 100 éléments ; limit va jusqu’à 500. Pour la page suivante, augmentez offset : ?limit=100&offset=100. Les réservations sont triées par date d’arrivée, les missions par date et heure.

Erreurs

En cas d’erreur, la réponse contient un code stable pour vos programmes et un message en français :

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

Limites et sécurité

• Une clé donne accès aux données de votre conciergerie : gardez-la comme un mot de passe. Utilisez-la depuis un serveur ou un outil d’automatisation, jamais dans une page web ou une appli publique.
• Une clé ne voit que sa conciergerie. Elle ne donne jamais accès aux codes d’accès, au Wi-Fi, aux cautions ni aux moyens de paiement.
• Les données de vos voyageurs, propriétaires et équipiers restent sous votre responsabilité : ne reliez que des logiciels de confiance, et révoquez une clé dès qu’elle ne sert plus.
• 120 appels par minute et par clé, 20 clés actives au plus par conciergerie.
• Les adresses de la version 1 ne changeront pas. Les nouveautés arriveront sous forme de nouveaux champs ou de nouvelles adresses.

Si vous demandez de l’aide, donnez le nom de la clé utilisée, jamais la clé elle-même.