Aller au contenu principal

Guide de démarrage rapide

Créez votre premier rendez-vous avec l'API moncreneau en moins de 5 minutes.

Prérequis​

Étape 1 : Obtenir votre clé API​

  1. Connectez-vous à votre dashboard moncreneau
  2. Naviguez vers Paramètres → API
  3. Cliquez sur Créer une clé API
  4. Choisissez les scopes nécessaires (au minimum : READ_APPOINTMENTS, WRITE_APPOINTMENTS)
  5. Copiez votre clé API (format : mk_...)
Important

Conservez votre clé API en sécurité ! Elle ne sera affichée qu'une seule fois. Ne la commitez jamais dans votre code source.

Étape 2 : Tester la connexion​

Vérifiez que votre clé API fonctionne en listant les départements disponibles :

Terminal
curl -X GET https://mc-prd.duckdns.org/api/v1/departments \
-H "X-API-Key: YOUR_API_KEY"

Réponse attendue :

[
  {
    "id": 5,
    "name": "Service de Passeports",
    "address": "123 Rue de la Santé, Conakry",
    "phoneNumber": "+224 123 456 789",
    "slotInterval": 30,
    "workingHours": "Lundi-Vendredi: 08:00-17:00"
  },
  {
    "id": 8,
    "name": "Service des Cartes d'Identité",
    "address": "456 Avenue de la République",
    "phoneNumber": "+224 987 654 321",
    "slotInterval": 15,
    "workingHours": "Lundi-Vendredi: 08:00-17:00"
  }
]

Étape 3 : Créer un rendez-vous​

Maintenant, créez votre premier rendez-vous :

Terminal
curl -X POST https://mc-prd.duckdns.org/api/v1/appointments \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "departmentId": 5,
  "dateTime": "2026-01-25T14:30:00",
  "name": "Jean Dupont",
  "externalUserId": "customer_789"
}'

Réponse :

{
  "id": 12345,
  "departmentId": 5,
  "dateTime": "2026-01-25T14:30:00",
  "status": "SCHEDULED",
  "name": "Jean Dupont",
  "qrCode": "a1b2c3d4-...",
  "createdAt": "2026-01-21T10:30:00"
}

Félicitations ! Vous avez créé votre premier rendez-vous !

Étape 4 : Récupérer un rendez-vous​

Consultez les détails d'un rendez-vous :

Terminal
curl -X GET https://mc-prd.duckdns.org/api/v1/appointments/12345 \
-H "X-API-Key: YOUR_API_KEY"

Étape 5 : Annuler un rendez-vous​

Si nécessaire, annulez un rendez-vous :

Terminal
curl -X DELETE https://mc-prd.duckdns.org/api/v1/appointments/12345 \
-H "X-API-Key: YOUR_API_KEY"
Comportement réel

Cet appel archive le rendez-vous (son statut ne change pas) et renvoie un 200 sans corps. Il ne rembourse pas automatiquement de crédit aujourd'hui — voir Endpoints Appointments.

Utiliser un SDK​

Préférez utiliser un SDK ? Seuls Node.js et Python sont publiés aujourd'hui (PHP et Java existent en code source mais pas encore publiés — voir SDK PHP et SDK Java).

Node.js​

// Installation : npm install @moncreneau/api
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

// Créer un rendez-vous
const appointment = await client.appointments.create({
  departmentId: 5,
  dateTime: '2026-01-25T14:30:00',
  name: 'Jean Dupont',
  workerId: 42, // Optionnel (requis si showAdminsInBooking=true)
});

console.log('Rendez-vous créé :', appointment.id);

Python​

# Installation : pip install moncreneau
from moncreneau import Moncreneau

client = Moncreneau('YOUR_API_KEY')

# Créer un rendez-vous
appointment = client.appointments.create(
    department_id=5,
    date_time='2026-01-25T14:30:00',
    name='Jean Dupont',
    worker_id=42  # Optionnel (requis si showAdminsInBooking=true)
)

print(f"Rendez-vous créé : {appointment['id']}")

Comprendre les rate limits​

Chaque réponse de l'API inclut des headers de rate limiting :

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1642435200
  • X-RateLimit-Limit : Nombre max de requêtes par heure
  • X-RateLimit-Remaining : Requêtes restantes
  • X-RateLimit-Reset : Timestamp Unix de réinitialisation
Limite atteinte

Si vous dépassez la limite, vous recevrez une erreur 429 Too Many Requests avec un header Retry-After.

Gérer les erreurs​

L'API retourne des codes HTTP standards et des messages d'erreur structurés :

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Votre organisation a 0 crédits restants"
  }
}

Codes d'erreur courants :

  • 401 : Clé API invalide ou manquante
  • 402 : Crédits insuffisants (LIVE uniquement)
  • 404 : Ressource non trouvée
  • 429 : Rate limit dépassé

Prochaines étapes​

Maintenant que vous avez réalisé votre premier appel API, explorez :

Besoin d'aide ?​

Dernière mise à jour le