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 : appointments:read, appointments:create)
  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",
    "description": "Délivrance de passeports",
    "organization": {
      "id": 1,
      "name": "Ministère de l'Intérieur"
    }
  },
  {
    "id": 8,
    "name": "Service des Cartes d'Identité",
    "description": "Délivrance de CNI",
    "organization": {
      "id": 1,
      "name": "Ministère de l'Intérieur"
    }
  }
]

É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": "https://moncreneau.gn/qr/12345",
  "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"
Crédits

L'annulation d'un rendez-vous rembourse 1 crédit à votre organisation.

Utiliser un SDK​

Préférez utiliser un SDK ? Voici les mêmes opérations avec les 4 SDKs officiels :

Java​

// Installation : Maven
// <dependency>
//   <groupId>com.moncreneau</groupId>
//   <artifactId>moncreneau-java</artifactId>
//   <version>1.0.0</version>
// </dependency>

import com.moncreneau.Moncreneau;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        Moncreneau client = new Moncreneau("YOUR_API_KEY");
        
        // Créer un rendez-vous
        Map<String, Object> data = new HashMap<>();
        data.put("departmentId", 5);
        data.put("dateTime", "2026-01-25T14:30:00");
        data.put("name", "Jean Dupont");
        data.put("workerId", 42); // Optionnel (requis si showAdminsInBooking=true)
        
        Map<String, Object> appointment = client.appointments.create(data);
        System.out.println("Rendez-vous créé : " + appointment.get("id"));
    }
}

Node.js​

// Installation : npm install @moncreneau/api
const Moncreneau = require('@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);

PHP​

<?php
// Installation : composer require moncreneau/moncreneau-php
require 'vendor/autoload.php';

$client = new \Moncreneau\Moncreneau('YOUR_API_KEY');

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

echo "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',
    user_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