Pour l'IA

Tout ce dont un assistant de codage IA a besoin pour construire une intégration Crisphive — un prompt prêt à coller, des ressources lisibles par machine et les faits essentiels sur l’API, réunis au même endroit.

Installer avec l’IA

Collez ce prompt dans votre assistant de codage IA pour amorcer une intégration :

Read the Crisphive backend integration skill at
https://api.crisphive.com/developers/SKILL.md and the OpenAPI spec at
https://api.crisphive.com/developers/openapi.json.

Then implement a client for my backend that:
1. Authenticates with an API key as a Bearer token (chsk_test_… for sandbox)
2. Creates a customer and a job request
3. Keeps job requests in sync by polling GET /v1/job-requests/changes
   with the next_since cursor

Chaque réponse utilise une même structure d’enveloppe — { error_code, message, errors, data } — de sorte que les clients générés peuvent partager un seul analyseur de réponses.

Ressources lisibles par machine

Ces deux fichiers sont servis par l’API elle-même et correspondent donc toujours à la version déployée — pointez votre assistant directement vers ces URL au lieu de copier des pages de documentation dans son contexte.

Ressource	Contenu
`SKILL.md`	Un guide d’intégration condensé écrit pour les agents : authentification, enveloppe de réponse, principaux flux de réservation et pièges courants.
`openapi.json`	La spécification OpenAPI complète — chaque endpoint, schéma de requête/réponse et code d’erreur. Utilisez-la pour générer des clients typés.

Faits essentiels pour votre assistant

L’URL de base est https://api.crisphive.com/v1 — sandbox et live partagent les mêmes chemins ; l’environnement est déterminé par le préfixe de la clé (chsk_test_… vs chsk_live_…).
Authentifiez chaque requête avec Authorization: Bearer <api key>. Les clés expirent — la durée de vie est choisie à la création (30 jours par défaut, de 1 à 365) et ne peut jamais être prolongée ; renouvelez en créant une clé de remplacement et en révoquant l’ancienne (jusqu’à 50 clés actives par environnement). Une clé expirée renvoie 401 avec API_KEY_EXPIRED, distinct de API_KEY_INVALID. Une clé dispose soit d’un accès complet, soit d’un accès restreint à des portées de permissions spécifiques (p. ex. créer des demandes d’intervention sans accès en lecture à votre liste de clients), et est toujours liée à un seul espace de travail et à un seul environnement (live ou sandbox). Gardez les clés côté serveur.
Un error_code de 0 signifie succès ; toute autre valeur est une erreur, et les échecs de validation détaillent chaque champ dans errors.
Répliquez les données en interrogeant GET /v1/job-requests/changes avec le curseur next_since retourné, plutôt qu’en relistant les ressources.
Préférez les webhooks pour recevoir les événements poussés (réservations, clients, techniciens) dès qu’ils se produisent ; le flux de changements est l’alternative en mode pull lorsque vous ne pouvez pas exposer d’endpoint.

Conseils pour de meilleurs résultats

Faites d’abord lire SKILL.md à l’assistant — le fichier tient dans le contexte et répond à la plupart des questions d’intégration sans la spécification complète.
Générez les types de requête/réponse à partir d’openapi.json plutôt que de laisser le modèle deviner les noms de champs.
Développez avec une clé sandbox (chsk_test_…) et ne passez en live qu’une fois les flux validés de bout en bout.
Au débogage, vérifiez error_code — pas seulement le statut HTTP.