SDK Python pour MONCRENEAU

Le SDK Python officiel pour intégrer MONCRENEAU dans vos applications Django, Flask, FastAPI ou Python standard.

Installation

pip install moncreneau

Ou avec Poetry :

poetry add moncreneau

Configuration

Python Standard

from moncreneau import MoncreneauClient

client = MoncreneauClient('YOUR_API_KEY')

Avec configuration avancée

from moncreneau import MoncreneauClient, Configuration

config = Configuration(
  api_key='YOUR_API_KEY',
  base_url='https://mc-prd.duckdns.org/api/v1',
  timeout=30,
  max_retries=3
)

client = MoncreneauClient(config)

Avec variables d'environnement

import os
from moncreneau import MoncreneauClient

client = MoncreneauClient(os.getenv('MONCRENEAU_API_KEY'))

Fichier .env :

MONCRENEAU_API_KEY=YOUR_API_KEY
MONCRENEAU_BASE_URL=https://mc-prd.duckdns.org/api/v1

Exemples d'utilisation

Lister les départements

from moncreneau import MoncreneauClient

client = MoncreneauClient('YOUR_API_KEY')

try:
  departments = client.departments.list()
  
  for dept in departments:
      print(f"ID: {dept.id} - {dept.name} ({dept.address})")
      
except Exception as e:
  print(f"Erreur: {e}")

Créer un rendez-vous

from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsError

client = MoncreneauClient('YOUR_API_KEY')

try:
  appointment = client.appointments.create(
      department_id=5,
      date_time='2026-02-15T10:00:00',
      name='Amadou Diallo'
  )
  
  print('✅ Rendez-vous créé!')
  print(f'ID: {appointment.id}')
  print(f'QR Code: {appointment.qr_code}')
  print(f'Statut: {appointment.status}')
  
except InsufficientCreditsError as e:
  print(f'❌ Crédits insuffisants: {e}')
except Exception as e:
  print(f'❌ Erreur: {e}')

Vérifier la disponibilité

from moncreneau import MoncreneauClient

client = MoncreneauClient('YOUR_API_KEY')

try:
  availability = client.departments.check_availability(
      department_id=5,
      date_time='2026-02-15T10:00:00'
  )
  
  if availability.available:
      print('✅ Créneau disponible!')
      print(f'Places restantes: {availability.remaining_slots}')
  else:
      print('❌ Créneau indisponible')
      print(f'Raison: {availability.unavailability_reason}')
      
except Exception as e:
  print(f'Erreur: {e}')

Annuler un rendez-vous

from moncreneau import MoncreneauClient

client = MoncreneauClient('YOUR_API_KEY')

try:
  cancelled = client.appointments.cancel(123)
  
  print('✅ Rendez-vous annulé')
  print(f'Statut: {cancelled.status}')
  print('1 crédit remboursé')
  
except Exception as e:
  print(f'❌ Erreur: {e}')

Intégration Django

Configuration settings.py

# settings.py

MONCRENEAU = {
  'API_KEY': os.getenv('MONCRENEAU_API_KEY'),
  'BASE_URL': os.getenv('MONCRENEAU_BASE_URL', 'https://mc-prd.duckdns.org/api/v1'),
  'TIMEOUT': 30,
}

Service Django

Créez myapp/services/moncreneau_service.py :

from django.conf import settings
from moncreneau import MoncreneauClient, Configuration

class MoncreneauService:
  def __init__(self):
      config = Configuration(
          api_key=settings.MONCRENEAU['API_KEY'],
          base_url=settings.MONCRENEAU['BASE_URL'],
          timeout=settings.MONCRENEAU['TIMEOUT']
      )
      self.client = MoncreneauClient(config)
  
  def create_appointment(self, department_id: int, date_time: str, name: str):
      return self.client.appointments.create(
          department_id=department_id,
          date_time=date_time,
          name=name
      )
  
  def list_departments(self):
      return self.client.departments.list()

# Singleton
moncreneau_service = MoncreneauService()

View Django

from django.http import JsonResponse
from django.views import View
from moncreneau.exceptions import InsufficientCreditsError
from .services.moncreneau_service import moncreneau_service

class CreateAppointmentView(View):
  def post(self, request):
      try:
          data = json.loads(request.body)
          
          appointment = moncreneau_service.create_appointment(
              department_id=data['department_id'],
              date_time=data['date_time'],
              name=data['name']
          )
          
          return JsonResponse({
              'id': appointment.id,
              'status': appointment.status,
              'qr_code': appointment.qr_code
          }, status=201)
          
      except InsufficientCreditsError as e:
          return JsonResponse({'error': str(e)}, status=402)
      except Exception as e:
          return JsonResponse({'error': str(e)}, status=500)

class CheckAvailabilityView(View):
  def get(self, request, department_id):
      date_time = request.GET.get('dateTime')
      
      availability = moncreneau_service.client.departments.check_availability(
          department_id=department_id,
          date_time=date_time
      )
      
      return JsonResponse({
          'available': availability.available,
          'remaining_slots': availability.remaining_slots,
          'unavailability_reason': availability.unavailability_reason
      })

Intégration Flask

Configuration Flask

from flask import Flask
from moncreneau import MoncreneauClient
import os

app = Flask(__name__)
app.config['MONCRENEAU_API_KEY'] = os.getenv('MONCRENEAU_API_KEY')

client = MoncreneauClient(app.config['MONCRENEAU_API_KEY'])

Routes Flask

from flask import Flask, request, jsonify
from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsError

app = Flask(__name__)
client = MoncreneauClient(os.getenv('MONCRENEAU_API_KEY'))

@app.route('/appointments', methods=['POST'])
def create_appointment():
  try:
      data = request.get_json()
      
      appointment = client.appointments.create(
          department_id=data['department_id'],
          date_time=data['date_time'],
          name=data['name']
      )
      
      return jsonify({
          'id': appointment.id,
          'status': appointment.status,
          'qr_code': appointment.qr_code
      }), 201
      
  except InsufficientCreditsError as e:
      return jsonify({'error': str(e)}), 402
  except Exception as e:
      return jsonify({'error': str(e)}), 500

@app.route('/departments/<int:id>/availability', methods=['GET'])
def check_availability(id):
  date_time = request.args.get('dateTime')
  
  availability = client.departments.check_availability(
      department_id=id,
      date_time=date_time
  )
  
  return jsonify({
      'available': availability.available,
      'remaining_slots': availability.remaining_slots
  })

if __name__ == '__main__':
  app.run(debug=True)

Intégration FastAPI

Application FastAPI

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsError
import os

app = FastAPI()
client = MoncreneauClient(os.getenv('MONCRENEAU_API_KEY'))

class CreateAppointmentRequest(BaseModel):
  department_id: int
  date_time: str
  name: str

@app.post('/appointments')
async def create_appointment(request: CreateAppointmentRequest):
  try:
      appointment = client.appointments.create(
          department_id=request.department_id,
          date_time=request.date_time,
          name=request.name
      )
      
      return {
          'id': appointment.id,
          'status': appointment.status,
          'qr_code': appointment.qr_code
      }
      
  except InsufficientCreditsError as e:
      raise HTTPException(status_code=402, detail=str(e))
  except Exception as e:
      raise HTTPException(status_code=500, detail=str(e))

@app.get('/departments/{department_id}/availability')
async def check_availability(department_id: int, dateTime: str):
  availability = client.departments.check_availability(
      department_id=department_id,
      date_time=dateTime
  )
  
  return {
      'available': availability.available,
      'remaining_slots': availability.remaining_slots,
      'unavailability_reason': availability.unavailability_reason
  }

Support asynchrone

Le SDK supporte les opérations async/await :

from moncreneau import AsyncMoncreneauClient
import asyncio

async def main():
  client = AsyncMoncreneauClient('YOUR_API_KEY')
  
  # Toutes les opérations sont async
  departments = await client.departments.list()
  
  appointment = await client.appointments.create(
      department_id=5,
      date_time='2026-02-15T10:00:00',
      name='Amadou Diallo'
  )
  
  print(f'Rendez-vous créé: {appointment.id}')

asyncio.run(main())

Gestion des erreurs

Le SDK utilise des exceptions typées :

from moncreneau import MoncreneauClient
from moncreneau.exceptions import (
  InsufficientCreditsError,
  ValidationError,
  NotFoundError,
  UnauthorizedError,
  ApiError
)

client = MoncreneauClient('YOUR_API_KEY')

try:
  appointment = client.appointments.create(data)
  
except InsufficientCreditsError as e:
  # Pas assez de crédits
  print(f'Crédits insuffisants: {e}')
  
except ValidationError as e:
  # Validation échouée
  print(f'Validation: {e.errors}')
  
except NotFoundError as e:
  # Ressource introuvable
  print(f'Non trouvé: {e}')
  
except UnauthorizedError as e:
  # API Key invalide
  print('API Key invalide')
  
except ApiError as e:
  # Erreur API générique
  print(f'Erreur API: {e.message}')
  print(f'Status: {e.status_code}')
  
except Exception as e:
  # Erreur générique
  print(f'Erreur: {e}')

Configuration avancée

Timeout et retry

from moncreneau import MoncreneauClient, Configuration

config = Configuration(
  api_key='YOUR_API_KEY',
  base_url='https://mc-prd.duckdns.org/api/v1',
  timeout=30,  # secondes
  connect_timeout=10,
  max_retries=3,
  retry_delay=1.0  # secondes
)

client = MoncreneauClient(config)

Logging

import logging
from moncreneau import MoncreneauClient, Configuration

# Activer le logging
logging.basicConfig(level=logging.DEBUG)

config = Configuration(
  api_key='YOUR_API_KEY',
  debug=True
)

client = MoncreneauClient(config)

Webhooks

Vérifiez la signature des webhooks :

from moncreneau import Webhook
from flask import Flask, request

app = Flask(__name__)
webhook = Webhook(os.getenv('WEBHOOK_SECRET'))

@app.route('/webhooks/moncreneau', methods=['POST'])
def handle_webhook():
  payload = request.get_data(as_text=True)
  signature = request.headers.get('X-Moncreneau-Signature')
  
  if not webhook.verify_signature(payload, signature):
      return {'error': 'Invalid signature'}, 401
  
  event = request.get_json()
  print(f"Event: {event['type']}")
  
  return {'received': True}, 200

Type hints

Le SDK est entièrement typé (PEP 484) :

from typing import List
from moncreneau import MoncreneauClient
from moncreneau.models import Department, Appointment, SlotAvailability

client = MoncreneauClient('YOUR_API_KEY')

def list_all_departments() -> List[Department]:
  return client.departments.list()

def create_new_appointment(dept_id: int, dt: str, name: str) -> Appointment:
  return client.appointments.create(
      department_id=dept_id,
      date_time=dt,
      name=name
  )

def check_slot(dept_id: int, dt: str) -> SlotAvailability:
  return client.departments.check_availability(
      department_id=dept_id,
      date_time=dt
  )

Tests unitaires avec pytest

import pytest
from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsError
import os

@pytest.fixture
def client():
  return MoncreneauClient(os.getenv('MONCRENEAU_API_KEY'))

def test_create_appointment(client):
  appointment = client.appointments.create(
      department_id=5,
      date_time='2026-02-15T10:00:00',
      name='Test User'
  )
  
  assert isinstance(appointment.id, int)
  assert appointment.status == 'PENDING'
  assert appointment.qr_code is not None

def test_insufficient_credits(client):
  with pytest.raises(InsufficientCreditsError):
      # Créer plusieurs RDV pour épuiser les crédits
      client.appointments.create(...)

Ressources

• Documentation API complète
• Exemples Django/FastAPI
• PyPI Package
• Type hints (PEP 484)