Documentation développeurs · v1

API Zelqia

API REST au format JSON pour connecter un site internet, un logiciel de caisse ou de comptabilité à un institut Zelqia. Spécification complète au format OpenAPI : openapi.json (importable dans Postman, Insomnia, Swagger).

Authentification

La gérante crée une clé dans Espace pro → Réglages → API et intégrations. Chaque appel envoie l'en-tête :

Authorization: Bearer zq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Utilisation côté serveur uniquement : une clé placée dans du code de navigateur serait visible de tous.
Une clé donne accès aux données d'un seul institut. Elle peut être révoquée à tout moment.
Limite : 120 requêtes par minute et par clé (en-têtes x-ratelimit-limit et x-ratelimit-remaining).
L'API n'est disponible que si l'abonnement de l'institut est actif.

Adresse de base

https://zelqia.fr/api/v1

Endpoints

GET	`/prestations` Prestations réservables (ajouter ?toutes=true pour inclure celles en pause).
GET	`/creneaux?prestation_id=…&date=AAAA-MM-JJ` Créneaux libres d’une journée, selon les horaires de l’institut.
GET	`/rendez-vous?du=…&au=…&statut=…` Rendez-vous d’une période (366 jours max.).
POST	`/rendez-vous` Créer un rendez-vous ; la cliente est retrouvée par téléphone ou e-mail, sinon créée.
GET	`/rendez-vous/{id}` Détail d’un rendez-vous.
PATCH	`/rendez-vous/{id}` Déplacer (debut) ou changer le statut (confirme, annule, absent).
DELETE	`/rendez-vous/{id}` Annuler un rendez-vous (l’historique est conservé).
GET	`/clientes?recherche=…&page=1&par_page=50` Fiches clientes paginées.
GET	`/chiffres?du=…&au=…` Chiffre d’affaires, dépenses, bénéfice net, panier moyen, répartition par prestation.

Les dates sont en heure de Paris (AAAA-MM-JJ) ; les instants en ISO 8601 (ex. 2026-11-03T14:30:00+01:00). Les montants sont en euros.

Exemple : réserver depuis un site

1. Lister les prestations

curl https://zelqia.fr/api/v1/prestations \
  -H "Authorization: Bearer $ZELQIA_CLE"

2. Chercher les créneaux libres

curl "https://zelqia.fr/api/v1/creneaux?prestation_id=PRESTATION_ID&date=2026-11-03" \
  -H "Authorization: Bearer $ZELQIA_CLE"

{ "date": "2026-11-03", "creneaux": [ { "heure": "14:30", "debut": "2026-11-03T13:30:00.000Z" } ] }

3. Créer le rendez-vous

curl -X POST https://zelqia.fr/api/v1/rendez-vous \
  -H "Authorization: Bearer $ZELQIA_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "prestation_id": "PRESTATION_ID",
    "debut": "2026-11-03T13:30:00.000Z",
    "cliente": { "prenom": "Inès", "nom": "Benali", "telephone": "0612345648" },
    "notifier": true
  }'

Réponse 201 avec le rendez-vous créé. Si le créneau vient d'être pris : 409 creneau_indisponible. Le rendez-vous apparaît immédiatement dans l'agenda de l'institut, et les rappels automatiques s'appliquent.

Erreurs

{ "erreur": { "code": "parametres_invalides", "message": "…" } }

`400`	parametres_invalides, json_invalide
`401`	non_authentifie
`403`	abonnement_inactif
`404`	introuvable
`409`	creneau_indisponible
`429`	trop_de_requetes (réessayer après 60 s)
`500`	erreur_interne

Flux d'agenda (iCalendar)

Lien d'abonnement en lecture seule, sans clé d'API : https://zelqia.fr/api/v1/agenda.ics?jeton=…. Il se trouve dans API et intégrations et s'ajoute en un clic à Google Agenda, Apple Calendrier ou Outlook.