1 mois gratuit avec le code de réduction BETA !
L'API REST publique Nowistay permet à vos propres outils, scripts et partenaires de lire et de mettre à jour les données de votre compte Nowistay de façon sécurisée. Vous pouvez lister vos propriétés, récupérer vos réservations, modifier vos réservations directes, créer des missions de ménage ou de check-in, gérer des champs personnalisés sur les réservations et lire un fil d'activité. Tout est documenté, explorable et testable depuis une seule page à l'adresse /public/docs.
Ce guide vous montre deux chemins : la façon la plus rapide d'essayer l'API (le playground interactif des docs) et le flux OAuth standard que vous utiliserez pour votre propre intégration.
external_status) et fixez leurs valeurs réservation par réservation.https://api.nowistay.com en production et https://api.nowistay.dev en préproduction./public/v1/* exigent un token OAuth2, envoyé sous la forme Authorization: Bearer ....Ouvrez https://api.nowistay.com/public/docs dans votre navigateur. La page est un Swagger UI complet de l'API, avec un playground OAuth intégré qui enregistre automatiquement un client pour vous. Pas besoin de coder pour tester.
Cmd+Maj+R sur Mac, Ctrl+F5 sur Windows)./public/docs, déjà authentifié.GET /public/v1/properties, cliquez sur Try it out puis sur Execute.[Capture d'ecran necessaire : la page /public/docs avec la banniere verte "OAuth playground ready" en haut et le bouton Authorize a droite]
À partir de là, vous pouvez essayer chaque endpoint en un clic, voir le JSON exact que Nowistay renvoie et copier la commande cURL correspondante. C'est la façon recommandée d'explorer l'API avant d'écrire du code.
Important. Le client du playground vit uniquement dans votre navigateur. C'est très bien pour tester, mais pour une vraie intégration il faut enregistrer votre propre client OAuth (voir plus bas).
L'API utilise OAuth 2.1 standard avec le flux authorization code et PKCE. En une phrase : l'utilisateur ouvre une page Nowistay, donne son accord, vous recevez un code court, vous l'échangez contre un token d'accès, puis vous appelez l'API avec ce token. Les tokens expirent et peuvent être renouvelés sans redéranger l'utilisateur.
Les trois endpoints OAuth que vous allez utiliser :
/public/oauth/register — POST/public/oauth/authorize — GET (redirection navigateur)/public/oauth/token — POSTVous pouvez aussi récupérer les métadonnées OAuth à /.well-known/oauth-authorization-server/public-api, qui liste chaque endpoint et toutes les options supportées.
Demandez uniquement les scopes dont votre app a vraiment besoin. Moins vous demandez de scopes, plus l'écran de consentement reste lisible.
properties.read: Lister les propriétés et leurs infos de base.bookings.read: Lister les réservations et lire le détail d'une réservation (sans les contacts voyageur).bookings.sensitive.read: Ajoute l'email, le téléphone, l'adresse du voyageur et le code de serrure dans le détail.bookings.write: Modifier les réservations directes (dates, montants, infos voyageur).booking_parameters.read: Lister vos champs personnalisés de réservation.booking_parameters.write: Créer des champs personnalisés et fixer leurs valeurs sur les réservations.missions.read: Lister les missions de vos propriétés.missions.write: Créer ou modifier des missions, assigner des membres d'équipe.activity.read: Lire le fil d'activité d'une propriété.team_members.read: Lister les membres d'équipe et leurs propriétés assignées.webhooks.read: Lister vos abonnements webhook et lire leur configuration.webhooks.write: Créer, modifier, mettre en pause et supprimer des abonnements webhook.Appelez POST /public/oauth/register une seule fois. Stockez le client_id (et le client_secret si vous choisissez un token_endpoint_auth_method autre que none).
curl -X POST https://api.nowistay.com/public/oauth/register \
-H "Content-Type: application/json" \
-d '{
"clientName": "Mon integration PMS",
"redirectUris": ["https://mon-app.exemple.com/oauth/callback"],
"grantTypes": ["authorization_code", "refresh_token"],
"responseTypes": ["code"],
"tokenEndpointAuthMethod": "client_secret_post",
"scope": "properties.read bookings.read missions.read"
}'Réponse (extrait) :
{
"client_id": "client_2Yw4Rk9pQp",
"client_secret": "client_secret_example",
"redirect_uris": ["https://mon-app.exemple.com/oauth/callback"],
"scope": "properties.read bookings.read missions.read"
}Astuce : si vous construisez une application monopage ou un outil en ligne de commande sans backend, choisissez "tokenEndpointAuthMethod": "none" et appuyez-vous uniquement sur PKCE (pas de secret client). Le playground des docs Nowistay fait exactement ça.
Générez une paire PKCE (code verifier et code challenge S256) ainsi qu'une valeur aléatoire state. Puis redirigez l'utilisateur vers :
https://api.nowistay.com/public/oauth/authorize
?response_type=code
&client_id=client_2Yw4Rk9pQp
&redirect_uri=https://mon-app.exemple.com/oauth/callback
&scope=properties.read%20bookings.read%20missions.read
&state=STATE_ALEATOIRE
&code_challenge=HASH_S256_BASE64URL
&code_challenge_method=S256L'utilisateur arrive sur la page de consentement Nowistay, se connecte si besoin, voit les scopes demandés et approuve ou refuse. En cas d'approbation, Nowistay le renvoie sur votre redirect_uri avec un code à usage unique et la même valeur state.
https://mon-app.exemple.com/oauth/callback?code=auth_code_123&state=STATE_ALEATOIREVérifiez toujours que la valeur state reçue correspond à celle que vous avez envoyée. Si elle ne correspond pas, interrompez le flux.
curl -X POST https://api.nowistay.com/public/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=auth_code_123" \
-d "redirect_uri=https://mon-app.exemple.com/oauth/callback" \
-d "client_id=client_2Yw4Rk9pQp" \
-d "client_secret=client_secret_example" \
-d "code_verifier=PKCE_VERIFIER_ORIGINAL"Réponse :
{
"access_token": "nis_access_token_example",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "nis_refresh_token_example",
"scope": "properties.read bookings.read missions.read",
"resource": "https://api.nowistay.com/public/v1"
}Stockez access_token et refresh_token de façon sécurisée chez vous (côté serveur, chiffrés au repos). Le token d'accès est valable pendant expires_in secondes (1 heure par défaut).
Envoyez le token d'accès dans l'en-tête Authorization.
curl https://api.nowistay.com/public/v1/properties \
-H "Authorization: Bearer nis_access_token_example"Exemple de réponse :
{
"data": [
{
"id": 101,
"name": "Appartement Lilas",
"propertyType": "apartment",
"capacity": 4,
"checkInTime": "16:00:00",
"checkOutTime": "11:00:00",
"address": {
"city": "Paris",
"country": "France",
"countryCode": "FR",
"timezone": "Europe/Paris"
}
}
],
"pagination": { "page": 1, "limit": 50, "totalItems": 1, "totalPages": 1 }
}Quand l'API renvoie 401 token_expired, rappelez le endpoint de token avec le refresh token. Pas besoin de renvoyer l'utilisateur sur la page de consentement.
curl -X POST https://api.nowistay.com/public/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=nis_refresh_token_example" \
-d "client_id=client_2Yw4Rk9pQp" \
-d "client_secret=client_secret_example"curl "https://api.nowistay.com/public/v1/bookings?propertyId=101&fromDate=2026-07-01&toDate=2026-07-31&status=confirmed" \
-H "Authorization: Bearer nis_access_token_example"Filtres supportés : propertyId, status, channel, fromDate, toDate. Pagination avec limit (max 100) et offset.
Nécessite le scope supplémentaire bookings.sensitive.read. Sans lui, email, phone et le code de serrure ne sont pas inclus.
curl https://api.nowistay.com/public/v1/bookings/9001 \
-H "Authorization: Bearer nis_access_token_example"Seules les réservations directes (canal direct) créées dans Nowistay peuvent être modifiées. Les réservations qui viennent d'Airbnb, Booking.com, VRBO ou Expedia sont en lecture seule ici, parce que c'est l'OTA qui les détient.
curl -X PATCH https://api.nowistay.com/public/v1/bookings/9001 \
-H "Authorization: Bearer nis_access_token_example" \
-H "Content-Type: application/json" \
-d '{
"arrival": "2026-07-14",
"departure": "2026-07-18",
"adults": 2,
"children": 1,
"amount": "620.00",
"currency": "EUR",
"notes": "Le voyageur a demande un lit bebe.",
"silent": true
}'Mettez "silent": false si vous voulez que Nowistay envoie les notifications habituelles (messages voyageur, mise à jour des calendriers) suite à la modification. Par défaut c'est silencieux.
Les paramètres personnalisés de réservation sont utiles pour refléter sur chaque réservation Nowistay une donnée qui vient de votre propre système.
# Crée le champ une seule fois
curl -X POST https://api.nowistay.com/public/v1/booking-parameters \
-H "Authorization: Bearer nis_access_token_example" \
-H "Content-Type: application/json" \
-d '{"key": "external_status", "name": "Statut externe"}'
# Fixe sa valeur sur une reservation
curl -X PATCH https://api.nowistay.com/public/v1/bookings/9001 \
-H "Authorization: Bearer nis_access_token_example" \
-H "Content-Type: application/json" \
-d '{"customParameters": {"external_status": "ready"}}'Envoyez null comme valeur pour effacer un champ personnalisé sur une réservation.
curl -X POST https://api.nowistay.com/public/v1/missions \
-H "Authorization: Bearer nis_access_token_example" \
-H "Content-Type: application/json" \
-d '{
"propertyId": 101,
"bookingId": 9001,
"missionType": "cleaning",
"title": "Menage de sortie",
"scheduledAt": "2026-07-18T11:30:00Z",
"timezone": "Europe/Paris",
"assignedTeamMemberId": 301
}'curl https://api.nowistay.com/public/v1/properties/101/activity?limit=20 \
-H "Authorization: Bearer nis_access_token_example"Les événements sont regroupés en trois catégories : booking, mission et automation (messages voyageur, événements de serrure).
Si vous ne voulez pas interroger l'API en boucle pour détecter les changements, vous pouvez vous abonner à des webhooks. Nowistay appellera alors une URL que vous fournissez chaque fois qu'une réservation est créée ou modifiée sur la propriété, en envoyant les mêmes données que GET /public/v1/bookings/{id}.
Deux événements sont supportés aujourd'hui :
booking.created : une nouvelle réservation a été enregistrée sur la propriété.booking.updated : une réservation existante a changé (dates, statut, infos voyageur, code de serrure, etc.).Chaque webhook est lié à une seule propriété et vous pouvez en enregistrer jusqu'à trois par propriété. Les livraisons sont signées (HMAC-SHA256) pour que vous puissiez vérifier qu'elles viennent bien de Nowistay, réessayées avec un délai croissant en cas d'échec, et le endpoint est désactivé automatiquement s'il continue d'échouer pendant plus de 72 heures. Les payloads webhook ne contiennent pas les champs voyageur sensibles (email, téléphone, adresse, code de serrure). Si vous en avez besoin, appelez l'API avec le scope bookings.sensitive.read.
La procédure complète et la vérification de signature sont dans l'article dédié : API publique : recevoir les webhooks de réservation en temps réel.
Quand vous atteignez la limite, l'API renvoie 429 Rate limit exceeded. Attendez quelques secondes avant de réessayer.
Toutes les erreurs suivent le même format, avec un code stable, un message lisible et un requestId à inclure dans vos demandes au support.
{
"error": {
"code": "validation_error",
"message": "Parameter key must be lowercase snake_case, start with a letter, and be at most 40 characters",
"requestId": "req_01HYZV5R8G3W9Y2M7K4P6Q1N2A"
}
}silent en écriture. Mettez-le à true quand vous synchronisez en masse et que vous ne voulez pas déclencher les notifications voyageur.https://api.nowistay.dev pour valider vos flux avant de passer en production.requestId dans vos logs. Ça accélère beaucoup la résolution côté support./public/openapi.json.
