Référence API

L’API CampOne permet de connecter des systèmes externes — channel managers, logiciels de comptabilité, outils marketing ou solutions internes — directement à votre camping. L’API reflète le modèle de données visible dans le tableau de bord admin : ce que vous pilotez par l’interface, vous pouvez l’automatiser.

La référence publique complète est actuellement en bêta privée et est ouverte aux partenaires d’intégration sur demande. Les sections ci-dessous décrivent l’architecture, le modèle d’authentification et les schémas d’intégration déjà supportés, afin de planifier une intégration avant la publication de la référence publique.

Architecture

L’API CampOne est une API REST sur HTTPS avec des bodies JSON en requête et en réponse. Les endpoints sont versionnés dans l’URL (/api/v1/…) et tous les horodatages sont en ISO 8601 UTC. L’API est multi-tenant ; chaque requête est cantonnée à un seul tenant identifié par un jeton API ou un jeton OAuth.

Les endpoints publics sont sur https://api.campone.ch. Une sandbox distincte est disponible sur https://sandbox.api.campone.ch avec un jeu de données isolé pour développer sans toucher la production.

Authentification

Deux modèles d’authentification sont pris en charge :

Modèle	Cas d’usage
Jeton d’accès personnel	Scripts internes, exports comptables, intégrations mono-tenant
OAuth 2.0 (authorisation code)	Applications tierces agissant pour plusieurs tenants

Les jetons d’accès personnels se génèrent sous Paramètres → API → Jetons avec une durée de vie configurable (1 à 365 jours). Chaque jeton porte un scope restreignant données et actions accessibles — par ex. lecture seule pour un export comptable, écriture totale pour un outil de dispatch interne.

OAuth 2.0 est le choix standard pour les produits partenaires : l’application est enregistrée chez CampOne, le tenant approuve via un écran de consentement familier, le partenaire reçoit des jetons d’accès courts plus des jetons de rafraîchissement.

Scopes

Le système suit le principe du moindre privilège :

• bookings:read / bookings:write
• guests:read / guests:write
• invoices:read / invoices:write
• pitches:read / pitches:write
• analytics:read
• compliance:read (exports HESTA, piste d’audit)

Un jeton peut combiner librement des scopes ; les scopes manquants donnent 403 Forbidden.

Limites de débit

Limites par tenant :

• 600 requêtes/minute pour les endpoints en lecture
• 120 requêtes/minute pour les endpoints en écriture
• 30 requêtes/minute pour les endpoints analytics (à cause des agrégations)

Chaque réponse porte les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset pour rythmer les requêtes. Au-delà, 429 Too Many Requests avec Retry-After.

Webhooks

Beaucoup d’intégrations n’ont pas besoin de poller — elles s’abonnent à des webhooks. CampOne émet des webhooks aux changements d’état clés :

• booking.created, booking.updated, booking.cancelled
• invoice.issued, invoice.paid
• guest.created, guest.updated, guest.deleted
• payment.received, payment.refunded
• availability.changed (utilisé par les channel managers)

Les payloads webhook sont signés HMAC-SHA256 dans l’en-tête CampOne-Signature, permettant aux destinataires de vérifier l’origine et l’intégrité. Les livraisons en échec sont retentées en backoff exponentiel jusqu’à 24 heures.

Intégrations existantes

Les intégrations suivantes tournent en production sur la même API :

• Channel manager (Booking.com, ACSI, Pincamp, Camping.info, ANWB, Hipcamp)
• TWINT (paiements)
• Swiss QR-Bill (import camt.054 pour le rapprochement)
• HESTA (statistiques mensuelles)
• Exports comptables (Bexio, Abacus, Sage, DATEV)
• Caisses (Sumup, Worldline, Vectron, Lightspeed, Toast, Square)
• Bornes de recharge OCPP (eCarUp, Plugsurfing, EVPass)
• Compteurs intelligents (Landis+Gyr, Iskra)

Si votre outil tombe dans une de ces catégories, parlez à votre interlocuteur CampOne — la connexion existe probablement déjà, ou ne demande qu’un mappage léger.

Schémas d’intégration courants

Objectif	Approche recommandée
Pousser les réservations en compta	Polling REST quotidien ou webhook, mappage vers votre plan de comptes
Remplacer le widget en ligne	pitches:read + bookings:write et funnel maison
Synchroniser un canal personnalisé	Webhook availability.changed + REST bookings:read
Affichage temps réel d’occupation	analytics:read avec cache
CRM hôtes propre	guests:read/write avec champs de consentement et IDs d’audit

Stabilité et versioning

Une fois intégré à /api/v1, on ne fait que des changements non-cassants (champs optionnels, nouveaux endpoints). Les changements cassants vont en /api/v2 avec un déploiement parallèle et au moins 12 mois de chevauchement.

Un journal des changements vit pour l’instant dans la console API (bêta privée) et apparaîtra ici à l’ouverture publique.

Sécurité

• Tout le trafic est en TLS 1.3
• Les jetons sont stockés hachés (Argon2id) — affichés une seule fois à la création
• Les clés tournées propagent en quelques secondes
• Un jeton révoqué cesse de fonctionner immédiatement
• Une entrée d’audit est créée pour chaque appel authentifié, avec IP et user agent

Comment obtenir l’accès

Avant la publication de la référence, les partenaires obtiennent l’accès via un processus guidé :

1. Contact avec votre interlocuteur CampOne et une note d’une page sur le cas d’usage.
2. Mise à disposition d’un tenant sandbox avec données synthétiques.
3. Partage de la spec OpenAPI 3.1 actuelle (importable dans Postman / Insomnia / OpenAPI Generator).
4. Revue conjointe de l’intégration avant la mise en production.

Si vous êtes un tenant souhaitant scripter des automatisations internes (par ex. export comptable nocturne), un jeton d’accès personnel suffit — pas de processus séparé nécessaire.