Branchez Node à vos outils

1. Démarrer en 3 minutes

Votre premier appel

Il ne touche à aucune donnée — il vous dit seulement si la clé fonctionne et ce qu'elle a le droit de faire.

curl https://app.nodegroupe.com/api/v1/me \
  -H "Authorization: Bearer node_sk_..."

Faites-le avant d'écrire votre intégration : découvrir une autorisation manquante en pleine boucle de traitement coûte bien plus cher.

2. Les 3 règles à connaître

Elles expliquent la quasi-totalité des intégrations qui coincent.

① Écrire un prix ou une disponibilité répond 202, pas 200

# Suivez l'avancement — toutes les 10 à 30 secondes, pas plus souvent
GET /api/v1/jobs/{job_id}
# status : pending → processing → completed | failed

② Écrivez par lot, jamais date par date

// ✅ UN appel, plusieurs plages — jusqu'à 60
PUT /api/v1/rates
{
  "property_id": "…",
  "ranges": [
    { "from": "2027-07-01", "to": "2027-08-31", "price": "180.00", "min_stay": 5 },
    { "from": "2027-09-01", "to": "2027-10-31", "price": "120.00" }
  ]
}

// ✅ Les mêmes plages sur PLUSIEURS logements — jusqu'à 50 par appel
PUT /api/v1/availability
{
  "property_ids": ["…", "…", "…"],
  "ranges": [ { "from": "2027-12-20", "to": "2027-12-27", "available": false } ]
}
// → 202 + "jobs": [{ "property_id", "job_id" }, …] — un suivi par logement

// ❌ JAMAIS ça : quota épuisé en secondes, envois rejetés
for (const date of dates) PUT /api/v1/rates { ranges: [{ from: date, to: date }] }

③ Faites-vous prévenir, n'interrogez pas en boucle

Pour savoir qu'une réservation est arrivée, déclarez un point de réception : Node vous appelle. Le paramètre updated_since sert au rattrapage après une panne de votre côté, pas à la détection continue.

3. Tous les appels

Le détail de chacun — paramètres, réponse, erreurs, recommandations — est dans la référence complète.

3 bis. Synchroniser en masse

Pour un outil qui tient sa propre copie des données — gestion des revenus, comptabilité, reporting : importer une fois, puis ne relire que ce qui a changé.

Le schéma en trois temps

Gardez la date du début de votre synchronisation précédente comme prochain updated_since (pas celle de la fin) : un enregistrement modifié pendant votre passage serait sinon perdu.

Le calendrier en un appel

GET /v1/calendar réunit disponibilités et tarifs : jusqu'à 50 logements × 400 jours. Par jour : available, booked, blocked, price, currency, min_stay, max_stay, closed_to_arrival, closed_to_departure, stop_sell, updated_at. Les valeurs du jour sont celles du plan tarifaire principal ; include_rate_plans=true ajoute le détail par plan.

Le détail tarifaire d'une réservation

Avec reservations:read, chaque réservation porte un objet pricing : currency, accommodation (séjour seul), ota_commission, tourist_tax, cleaning_fee, net_owner, et fees — les frais détaillés transmis par la plateforme (linge, animaux, personne supplémentaire…, surtout Airbnb). S'y ajoutent booked_at (date de réservation réelle), status_detail (blocked pour un blocage) et is_block.

Les valeurs possibles de channel sont renvoyées par GET /v1/channels : de quoi construire votre table de correspondance une fois pour toutes.

Vos prix ne sont pas écrasés

Un prix écrit par PUT /v1/rates est inscrit comme fixé à la main : le moteur de tarification de Node ne le réécrit pas. La conciergerie le voit dans « Règles enregistrées » et peut le réinitialiser.

Accès et quotas

• Les quotas sont par clé : chaque client a les siens, synchronisez-les en parallèle.
• Chaque réponse porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset ; un 429 porte Retry-After.
• OAuth2 : code d'autorisation + PKCE, jeton d'accès de 2 h, jeton de renouvellement de 90 jours. Pour obtenir une application partenaire, écrivez au support avec votre URL de redirection.
• Une écriture calendrier couvre 60 plages × 50 logements : 10 appels par minute suffisent largement.

4. Être prévenu — les webhooks

Sans eux, savoir qu'une réservation est arrivée impose d'interroger l'API en boucle. Et vous ne serez jamais prévenu plus tôt qu'avec un webhook.

POST /api/v1/webhooks
{
  "url": "https://mon-service.fr/hooks/node",
  "events": ["reservation.created", "reservation.cancelled"]
}

23 événements : réservations, arrivées et départs, messages voyageur, missions de ménage, factures, logements, calendrier et prix, incidents, validations. Le catalogue complet est renvoyé par GET /v1/webhooks : vous pouvez construire votre écran d'abonnement à partir de cette seule réponse.

Calendrier et prix

Pour garder un site de réservation à jour sans interroger l'API en boucle :

• L'événement est un signal : relisez GET /v1/availability et GET /v1/rates sur la plage reçue (dates incluses).
• Regroupé par logement : 30 modifications d'affilée donnent un seul événement, envoyé 30 secondes après la dernière (5 minutes au plus après la première), dont la plage couvre toutes les dates touchées.
• Un changement fait directement dans l'extranet de l'OTA ou dans Channex n'émet rien tant que Node ne l'a pas relu. Gardez une synchronisation quotidienne en filet de sécurité.

Modifier un abonnement

PATCH /api/v1/webhooks/{id}
{
  "events": ["reservation.created", "availability.updated", "rates.updated"]
}

events remplace la liste entière : pour ajouter un événement, renvoyez la liste actuelle plus le nouveau. Le secret ne change pas, rien à redéployer chez vous. enabled: true réactive un point de réception coupé. L'URL et le secret ne se modifient pas : pour en changer, créez un nouveau point de réception. Un jeton ne modifie que les points de réception qu'il a créés.

GET /v1/webhooks/{id} renvoie les 20 dernières livraisons avec code de réponse et message d'erreur. C'est la première chose à regarder avant d'ouvrir un ticket « je ne reçois rien ».

5. Quand ça ne marche pas

6. Ce que l'API ne fait pas

Chaque refus a une raison, et la voici.

7. Support

Ouvrez un ticket depuis Node en citant :

1. le Node-Request-Id de la réponse (ou le Node-Event-Id pour un webhook) ;
2. l'horodatage ;
3. le début de votre clé (node_sk_AbC1…) — jamais le secret complet.

Ces trois éléments suffisent à retrouver votre appel exact dans le journal.