API publique v1

API publique v1 — Référence

Toutes les routes sont publiques (sans authentification) sous le préfixe /api/v1/book/{org_slug}.

Le contrat est figé. Toute évolution breaking passe par /api/v2/... et un nouveau SDK.

En-têtes de réponse

Toute réponse de la v1 inclut :

X-Staycore-API-Version: v1
Content-Type: application/json

Utilisé pour observabilité côté backend (combien de clients sur v1 vs legacy).

Enveloppe standard

// Succès
{
  "success": true,
  "data": { /* T */ },
  "message": "Optional"
}
 
// Échec
{
  "success": false,
  "message": "Description courte de l'erreur."
}

Endpoints

GET /api/v1/book/{slug}

Configuration de l’organisation + clé Stripe publique.

Réponse :

{
  "success": true,
  "data": {
    "organization": { "name": "Acme", "slug": "acme", "logo": null },
    "config": {
      "payment_mode": "full" | "deposit" | "request",
      "default_locale": "fr" | "en",
      "branding": {},
      "terms_url": null,
      "min_stay_nights": null,
      "max_stay_nights": null
    },
    "stripe_public_key": "pk_live_..."
  }
}

GET /api/v1/book/{slug}/properties

Liste des biens bookables.

GET /api/v1/book/{slug}/properties/{id}/availability

Calendrier de disponibilités (mois courant + suivants).

GET /api/v1/book/{slug}/properties/{id}/price

Query string :

ParamTypeRequis
check_inYYYY-MM-DD✓
check_outYYYY-MM-DD✓
guests_countinteger—
coupon_codestring—

POST /api/v1/book/{slug}/checkout

Body JSON :

{
  "property_id": 42,
  "guest_name": "Jean Dupont",
  "guest_email": "jean@example.com",
  "guest_phone": "+33...",
  "check_in": "2026-08-01",
  "check_out": "2026-08-05",
  "guests_count": 2,
  "message": "Anniversaire",
  "locale": "fr",
  "coupon_code": "WELCOME10"
}

Réponse 201 :

{
  "success": true,
  "data": {
    "booking_token": "abc123...",
    "payment_mode": "full",
    "total_amount": 500.00,
    "charge_amount": 500.00,
    "client_secret": "pi_..._secret_...",
    "stripe_public_key": "pk_live_..."
  }
}

Rate limit : 10 / minute.

POST /api/v1/book/{slug}/validate-coupon

Valider un code promo avant le checkout. Rate limit : 20 / minute.

GET /api/v1/book/{slug}/booking/{token}

Statut de la réservation par son token (page de suivi).

POST /api/v1/book/{slug}/booking/{token}/confirm

Confirmer la réservation après succès Stripe. Rate limit : 10 / minute.

GET /api/v1/book/{slug}/properties/{id}/options

Options vendues sur la page de réservation (arrivée anticipée, champagne…). Paramètre facultatif check_in pour évaluer le délai de commande : une option hors délai revient avec available: false et son motif.

La sélection se passe ensuite au devis (options[0][id]=42&options[0][quantity]=1) et au checkout ("options": [{ "id": 42, "quantity": 1 }]). Le prix n’est jamais calculé côté client.

Modules du site

Trois modules s’activent par organisation dans le dashboard Stay’Core (Moteur de résa › Site web). GET /api/v1/book/{slug} renvoie un bloc modules qui dit lesquels sont ouverts ; une route d’un module coupé répond 404.

"modules": {
  "chat": { "enabled": true, "welcome_message_fr": "Bonjour, une question ?", "welcome_message_en": null },
  "contact": { "enabled": true },
  "gift_cards": {
    "enabled": true, "amounts": [100, 200, 300], "allow_custom_amount": true,
    "min_amount": 50, "max_amount": 1000, "validity_months": 12, "currency": "EUR"
  },
  "captcha": null
}

Quand captcha est renseigné ({ "provider": "turnstile", "site_key": "…" }), l’ouverture d’un chat et l’envoi du formulaire attendent un captcha_token.

Chat

Le chat est tenu par l’assistant IA que l’hôte a réglé dans Stay’Core. Chaque conversation arrive dans sa messagerie, canal « Site web » ; il peut y répondre lui-même, et l’assistant se met alors en pause sur cette conversation.

Il n’y a pas de WebSocket : le site interroge GET /chat/messages tant que le chat est à l’écran. C’est aussi ce qui dit au serveur que le visiteur est encore là ; s’il est parti et a laissé son e-mail, les réponses partent par e-mail.

MéthodeRouteRôleLimite
POST/chat/sessionsOuvre une conversation. Renvoie token, welcome_message, thread.5 / minute
POST/chat/messagesEnvoie { "content": "…" } (2 000 caractères au plus).12 / minute
GET/chat/messages?after={id}Messages après id, et l’état du fil.90 / minute
POST/chat/contact-detailsEnregistre name, email, phone du visiteur.12 / minute

Le jeton du visiteur se passe dans l’en-tête Authorization: Bearer {token}. Un jeton inconnu répond 401 avec code: "session_invalid" : ouvre une nouvelle conversation.

thread.status dit qui répondra au prochain message :

ValeurSensÀ afficher
assistantL’assistant répond seul.« Assistant »
awaiting_hostL’assistant prépare, l’hôte valide avant envoi.« Nous vous répondons dans un instant », et proposer de laisser un e-mail
hostUn humain a repris la main, ou aucun assistant n’est disponible.Le nom du lieu, et proposer de laisser un e-mail

Chaque message porte un role : visitor, assistant ou host.

Formulaire de contact

POST /api/v1/book/{slug}/contact avec name, email, message (obligatoires), phone, property_id, locale, origin_url. Le message ouvre une conversation dans la messagerie de l’hôte ; sa réponse part par e-mail au visiteur. Limite : 3 messages par heure et par adresse e-mail (429, code: "too_many_messages").

Ajoute un champ caché website à ton formulaire et transmets-le tel quel : un robot qui le remplit est écarté sans le savoir.

Cartes cadeaux

Une carte cadeau est un moyen de paiement à solde, pas une remise : elle se déduit du total après options, frais et taxe de séjour, et ce qu’elle ne dépense pas reste sur la carte.

MéthodeRouteRôleLimite
POST/gift-cards/checkoutCrée la carte en attente et le PaymentIntent. Renvoie gift_card_token, client_secret, stripe_public_key.10 / minute
POST/gift-cards/{token}/confirmÀ appeler après le succès Stripe : le serveur revérifie le paiement et active la carte.10 / minute
GET/gift-cards/{token}Suivi de l’achat. Le code n’y figure qu’une fois la carte payée.—
POST/gift-cards/balanceSolde d’une carte : { "code": "ABCD-EFGH-JKLM" }.6 / minute

Pour payer une réservation avec une carte :

  • passe gift_card_code au devis (GET /properties/{id}/price) : la réponse ajoute gift_card_amount, gift_card (applied_amount, remaining_balance) et amount_due, le montant qui sera réellement débité. total ne change pas. Un code refusé n’empêche pas le devis : le motif arrive dans gift_card_error ;
  • passe le même gift_card_code au POST /checkout. Un code refusé répond 422 avec code: "gift_card_invalid". Si la carte couvre tout, la réponse porte payment_required: false et status: "confirmed" : il n’y a pas d’étape Stripe.

CORS

L’origine appelante doit être autorisée. Deux options :

  1. Custom domain déclaré dans le dashboard Stay’Core (Settings → Custom domains) — *.stay-core.com et *.vercel.app sont autorisés en plus
  2. Allowed origins explicite dans BookingEngineConfig.allowed_origins côté backend

Voir le guide Custom domain.

Statuts d’erreur courants

CodeQuandAction
404Org inexistante, moteur public désactivé, propriété introuvableVérifier le slug, activer le moteur public
422Validation échouée, dispo non garantie, paiement non confirméLire message
429Rate limit dépasséBackoff et réessayer
500Bug serveur (rare)Réessayer, contacter support

Contrat figé

Le contrat de cette API est gardé par un test PHPUnit dans le backend (BookingContractTest.php). Tout changement qui casserait la compatibilité fait échouer le CI : tu peux te baser dessus en production sans risque de surprise.