Endpoints Appointments

Gérer les rendez-vous : création, consultation et annulation.

Crédits

Créer un rendez-vous consomme 1 crédit. Annuler un rendez-vous rembourse 1 crédit.

POST /appointments

Crée un nouveau rendez-vous. Consomme automatiquement 1 crédit de votre organisation.

Champs optionnels

• externalUserId : Identifiant de votre système pour faire la correspondance avec vos utilisateurs
• workerId : ID du professionnel/staff. Requis uniquement si le département a showAdminsInBooking=true

Request

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-02-15T10:00:00",
  "name": "Amadou Diallo",
  "workerId": 42,
  "externalUserId": "customer_12345"
}'

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;
import com.moncreneau.model.CreateAppointmentRequest;
import java.time.LocalDateTime;

ApiClient client = new ApiClient("your_api_key");

CreateAppointmentRequest request = new CreateAppointmentRequest()
    .departmentId(5L)
    .dateTime(LocalDateTime.parse("2026-02-15T10:00:00"))
    .name("Amadou Diallo")
    .workerId(42L)
    .externalUserId("customer_12345");

try {
    Appointment appointment = client.appointments().create(request);
    System.out.println("Rendez-vous créé avec ID: " + appointment.getId());
    System.out.println("QR Code: " + appointment.getQrCode());
} catch (InsufficientCreditsException e) {
    System.err.println("Crédits insuffisants: " + e.getMessage());
}

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');

try {
  const appointment = await client.appointments.create({
    departmentId: 5,
    dateTime: '2026-02-15T10:00:00',
    name: 'Amadou Diallo',
    workerId: 42,
    externalUserId: 'customer_12345'
  });
  
  console.log(`Rendez-vous créé avec ID: ${appointment.id}`);
  console.log(`QR Code: ${appointment.qrCode}`);
} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    console.error('Crédits insuffisants:', error.message);
  }
}

PHP

<?php
use Moncreneau\Client;
use Moncreneau\Exception\InsufficientCreditsException;

$client = new Client('your_api_key');

try {
    $appointment = $client->appointments->create([
        'departmentId' => 5,
        'dateTime' => '2026-02-15T10:00:00',
        'name' => 'Amadou Diallo',
        'externalUserId' => 'customer_12345'
    ]);
    
    echo "Rendez-vous créé avec ID: {$appointment->id}" . PHP_EOL;
    echo "QR Code: {$appointment->qrCode}" . PHP_EOL;
} catch (InsufficientCreditsException $e) {
    echo "Crédits insuffisants: {$e->getMessage()}" . PHP_EOL;
}

Python

from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsException

client = MoncreneauClient('your_api_key')

try:
    appointment = client.appointments.create(
        department_id=5,
        date_time='2026-02-15T10:00:00',
        name='Amadou Diallo',
        worker_id=42,
        external_user_id='customer_12345'
    )
    
    print(f"Rendez-vous créé avec ID: {appointment.id}")
    print(f"QR Code: {appointment.qr_code}")
except InsufficientCreditsException as e:
    print(f"Crédits insuffisants: {e}")

Response 201 - Success

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CONFIRMED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "Consultation générale",
  "externalUserId": "customer_12345",
  "createdAt": "2026-01-21T09:30:00"
}

Response 402 - Insufficient Credits

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to create appointment. Current: 0, Required: 1",
  "timestamp": "2026-01-21T10:00:00"
}

Response 400 - Bad Request

{
  "code": "INVALID_REQUEST",
  "message": "DateTime must be in the future",
  "timestamp": "2026-01-21T10:00:00"
}

---

GET /appointments/{id}

Récupère les détails d'un rendez-vous par son ID.

Request

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

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;

ApiClient client = new ApiClient("your_api_key");
Appointment appointment = client.appointments().get(123L);

System.out.println("Statut: " + appointment.getStatus());
System.out.println("Date: " + appointment.getDateTime());
System.out.println("Bénéficiaire: " + appointment.getName());

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');
const appointment = await client.appointments.get(123);

console.log(`Statut: ${appointment.status}`);
console.log(`Date: ${appointment.dateTime}`);
console.log(`Bénéficiaire: ${appointment.name}`);

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');
$appointment = $client->appointments->get(123);

echo "Statut: {$appointment->status}" . PHP_EOL;
echo "Date: {$appointment->dateTime}" . PHP_EOL;
echo "Bénéficiaire: {$appointment->name}" . PHP_EOL;

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')
appointment = client.appointments.get(123)

print(f"Statut: {appointment.status}")
print(f"Date: {appointment.date_time}")
print(f"Bénéficiaire: {appointment.name}")

Response 200

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CONFIRMED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "Consultation générale",
  "createdAt": "2026-01-21T09:30:00"
}

Response 404

{
  "code": "APPOINTMENT_NOT_FOUND",
  "message": "Appointment not found with id: 123",
  "timestamp": "2026-01-21T10:00:00"
}

---

GET /appointments

Liste tous les rendez-vous de votre organisation avec pagination et filtres optionnels.

Filtres disponibles

Vous pouvez filtrer par status, departmentId, externalUserId, startDate, endDate et paginer avec page et size.

Request

curl -X GET "https://mc-prd.duckdns.org/api/v1/appointments?page=0&size=20&status=SCHEDULED" \
-H "X-API-Key: YOUR_API_KEY"

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.AppointmentPage;

ApiClient client = new ApiClient("your_api_key");

// Liste simple
AppointmentPage page = client.appointments().list();

// Avec filtres
AppointmentPage filtered = client.appointments()
    .list()
    .status("SCHEDULED")
    .departmentId(5L)
    .externalUserId("customer_12345")
    .page(0)
    .size(20)
    .execute();

System.out.println("Total: " + filtered.getTotalElements());
for (Appointment apt : filtered.getAppointments()) {
    System.out.println(apt.getName() + " - " + apt.getDateTime());
}

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');

// Liste simple
const page = await client.appointments.list();

// Avec filtres
const filtered = await client.appointments.list({
  page: 0,
  size: 20,
  status: 'SCHEDULED',
  departmentId: 5,
  externalUserId: 'customer_12345',
  startDate: '2026-02-01T00:00:00',
  endDate: '2026-02-28T23:59:59'
});

console.log(`Total: ${filtered.totalElements}`);
filtered.appointments.forEach(apt => {
  console.log(`${apt.name} - ${apt.dateTime}`);
});

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');

// Liste simple
$page = $client->appointments->list();

// Avec filtres
$filtered = $client->appointments->list([
    'page' => 0,
    'size' => 20,
    'status' => 'SCHEDULED',
    'departmentId' => 5,
    'externalUserId' => 'customer_12345',
    'startDate' => '2026-02-01T00:00:00',
    'endDate' => '2026-02-28T23:59:59'
]);

echo "Total: {$filtered->totalElements}" . PHP_EOL;
foreach ($filtered->appointments as $apt) {
    echo "{$apt->name} - {$apt->dateTime}" . PHP_EOL;
}

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')

# Liste simple
page = client.appointments.list()

# Avec filtres
filtered = client.appointments.list(
    page=0,
    size=20,
    status='SCHEDULED',
    department_id=5,
    external_user_id='customer_12345',
    start_date='2026-02-01T00:00:00',
    end_date='2026-02-28T23:59:59'
)

print(f"Total: {filtered['totalElements']}")
for apt in filtered['appointments']:
    print(f"{apt['name']} - {apt['dateTime']}")

Paramètres de requête

Paramètre	Type	Défaut	Description
page	integer	0	Numéro de page (commence à 0)
size	integer	20	Éléments par page (max 100)
status	string	-	Filtrer par statut (SCHEDULED, COMPLETED, CANCELLED, MISSED)
departmentId	integer	-	Filtrer par ID de département
externalUserId	string	-	Filtrer par votre ID utilisateur externe
startDate	string (ISO 8601)	-	Rendez-vous après cette date
endDate	string (ISO 8601)	-	Rendez-vous avant cette date

Response 200

{
  "appointments": [
    {
      "id": 123,
      "dateTime": "2026-02-15T10:00:00",
      "status": "SCHEDULED",
      "name": "Amadou Diallo",
      "qrCode": "QR-MONC-123-ABC",
      "departmentId": 5,
      "departmentName": "Consultation générale",
      "externalUserId": "customer_12345",
      "createdAt": "2026-01-21T09:30:00"
    },
    {
      "id": 124,
      "dateTime": "2026-02-15T14:00:00",
      "status": "SCHEDULED",
      "name": "Fatoumata Camara",
      "qrCode": "QR-MONC-124-DEF",
      "departmentId": 5,
      "departmentName": "Consultation générale",
      "createdAt": "2026-01-21T10:15:00"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 45,
  "totalPages": 3,
  "isLast": false
}

---

DELETE /appointments/{id}

Annule un rendez-vous et rembourse automatiquement 1 crédit à votre organisation.

Request

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

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;

ApiClient client = new ApiClient("your_api_key");
Appointment cancelled = client.appointments().cancel(123L);

System.out.println("Rendez-vous annulé");
System.out.println("Nouveau statut: " + cancelled.getStatus());
System.out.println("1 crédit remboursé");

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');
const cancelled = await client.appointments.cancel(123);

console.log('Rendez-vous annulé');
console.log(`Nouveau statut: ${cancelled.status}`);
console.log('1 crédit remboursé');

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');
$cancelled = $client->appointments->cancel(123);

echo "Rendez-vous annulé" . PHP_EOL;
echo "Nouveau statut: {$cancelled->status}" . PHP_EOL;
echo "1 crédit remboursé" . PHP_EOL;

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')
cancelled = client.appointments.cancel(123)

print('Rendez-vous annulé')
print(f'Nouveau statut: {cancelled.status}')
print('1 crédit remboursé')

Response 200

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CANCELLED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "Consultation générale",
  "createdAt": "2026-01-21T09:30:00"
}

Response 404

{
  "code": "APPOINTMENT_NOT_FOUND",
  "message": "Appointment not found with id: 123",
  "timestamp": "2026-01-21T10:00:00"
}

---

Gestion des erreurs

Toutes les erreurs retournent un objet standardisé :

{
  code: string;      // Code d'erreur (ex: INSUFFICIENT_CREDITS)
  message: string;   // Message lisible
  timestamp: string; // Date/heure de l'erreur
}

Codes d'erreur courants

Code	HTTP	Description
INSUFFICIENT_CREDITS	402	Pas assez de crédits pour créer un rendez-vous
APPOINTMENT_NOT_FOUND	404	Rendez-vous introuvable
INVALID_REQUEST	400	Requête invalide (validation échouée)
UNAUTHORIZED	401	API Key invalide ou manquante
FORBIDDEN	403	Ressource n'appartient pas à votre organisation
INTERNAL_ERROR	500	Erreur serveur interne