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 (remboursement pris en charge par votre code : voir la note sous DELETE /appointments/{id}).

SDK PHP et Java

Les exemples PHP et Java ci-dessous utilisent la syntaxe des SDK officiels — pas encore publiés sur Packagist/Maven Central (voir SDK PHP et SDK Java). Node.js et Python sont publiés et utilisables dès aujourd'hui.

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.Moncreneau;
import com.moncreneau.exceptions.MoncreneauException;
import java.util.Map;

Moncreneau client = new Moncreneau("your_api_key");

Map<String, Object> data = Map.of(
    "departmentId", 5,
    "dateTime", "2026-02-15T10:00:00",
    "name", "Amadou Diallo",
    "workerId", 42,
    "externalUserId", "customer_12345"
);

try {
    Map<String, Object> appointment = client.appointments.create(data);
    System.out.println("Rendez-vous créé avec ID: " + appointment.get("id"));
    System.out.println("QR Code: " + appointment.get("qrCode"));
} catch (MoncreneauException e) {
    if ("INSUFFICIENT_CREDITS".equals(e.getErrorCode())) {
        System.err.println("Crédits insuffisants: " + e.getMessage());
    }
}

Node.js
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('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\Moncreneau;
use Moncreneau\Exceptions\MoncreneauException;

$client = new Moncreneau('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 (MoncreneauException $e) {
    if ($e->getErrorCode() === 'INSUFFICIENT_CREDITS') {
        echo "Crédits insuffisants: {$e->getMessage()}" . PHP_EOL;
    }
}

Python
from moncreneau import Moncreneau, MoncreneauError

client = Moncreneau('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['qrCode']}")
except MoncreneauError as e:
    if e.code == 'INSUFFICIENT_CREDITS':
        print(f"Crédits insuffisants: {e.message}")

Response 201 - Success

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

Response 402 - Insufficient Credits

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits to create appointment. Current: 0, Required: 1"
  }
}

Response 400 - Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid.",
    "details": [
      { "field": "dateTime", "message": "must not be null" }
    ]
  }
}

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.Moncreneau;
import java.util.Map;

Moncreneau client = new Moncreneau("your_api_key");
Map<String, Object> appointment = client.appointments.retrieve("123");

System.out.println("Statut: " + appointment.get("status"));
System.out.println("Date: " + appointment.get("dateTime"));
System.out.println("Bénéficiaire: " + appointment.get("name"));

Node.js
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('your_api_key');
const appointment = await client.appointments.retrieve('123');

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

PHP
<?php
use Moncreneau\Moncreneau;

$client = new Moncreneau('your_api_key');
$appointment = $client->appointments->retrieve('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 Moncreneau

client = Moncreneau('your_api_key')
appointment = client.appointments.retrieve('123')

print(f"Statut: {appointment['status']}")
print(f"Date: {appointment['dateTime']}")
print(f"Bénéficiaire: {appointment['name']}")

Response 200

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

Response 404

{
  "error": {
    "code": "APPOINTMENT_NOT_FOUND",
    "message": "Appointment not found with id: 123"
  }
}

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.Moncreneau;
import java.util.Map;

Moncreneau client = new Moncreneau("your_api_key");

// Liste simple
Map<String, Object> page = client.appointments.list(Map.of());

// Avec filtres
Map<String, Object> filtered = client.appointments.list(Map.of(
    "status", "SCHEDULED",
    "departmentId", "5",
    "externalUserId", "customer_12345",
    "page", "0",
    "size", "20"
));

System.out.println("Total: " + filtered.get("totalElements"));

Node.js
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('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\Moncreneau;

$client = new Moncreneau('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 Moncreneau

client = Moncreneau('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": "a1b2c3d4-...",
      "departmentId": 5,
      "departmentName": "Consultation générale",
      "externalUserId": "customer_12345",
      "createdAt": "2026-01-21T09:30:00"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 45,
  "totalPages": 3,
  "isLast": false
}

DELETE /appointments/{id}

Annule (archive) un rendez-vous.

Comportement réel

Cet endpoint archive le rendez-vous — il ne modifie pas son status (qui reste SCHEDULED), et ne rembourse pas automatiquement de crédit aujourd'hui, contrairement à l'annulation effectuée depuis le dashboard web. La réponse est un 200 sans corps.

Request

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

Java
import com.moncreneau.Moncreneau;

Moncreneau client = new Moncreneau("your_api_key");
client.appointments.cancel("123");
System.out.println("Rendez-vous archivé");

Node.js
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('your_api_key');
await client.appointments.cancel('123');
console.log('Rendez-vous archivé');

PHP
<?php
use Moncreneau\Moncreneau;

$client = new Moncreneau('your_api_key');
$client->appointments->cancel('123');
echo "Rendez-vous archivé" . PHP_EOL;

Python
from moncreneau import Moncreneau

client = Moncreneau('your_api_key')
client.appointments.cancel('123')
print('Rendez-vous archivé')

Response 200

Corps vide.

Response 404

{
  "error": {
    "code": "APPOINTMENT_NOT_FOUND",
    "message": "Appointment not found with id: 123"
  }
}

Gestion des erreurs

Toutes les erreurs retournent une enveloppe standardisée :

{
  error: {
    code: string;               // Code d'erreur (ex: INSUFFICIENT_CREDITS)
    message: string;            // Message lisible
    details?: Array<{           // Présent uniquement pour les erreurs de validation (400)
      field: string;
      message: string;
    }>;
  }
}

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
`VALIDATION_ERROR`	400	Corps de requête invalide (voir `details`)
`INVALID_DATE_FORMAT`	400	Date malformée (`startDate`/`endDate`)
`MISSING_API_KEY` / `INVALID_API_KEY`	401	Clé API manquante, invalide ou révoquée
`INSUFFICIENT_SCOPE`	403	Scope insuffisant pour cette opération
`RATE_LIMIT_EXCEEDED`	429	Limite de requêtes/heure dépassée
`INTERNAL_ERROR`	500	Erreur serveur interne

Voir Gestion des erreurs pour le détail complet.

POST /appointments​

Request​

Response 201 - Success​

Response 402 - Insufficient Credits​

Response 400 - Bad Request​

GET /appointments/{id}​

Request​

Response 200​

Response 404​

GET /appointments​

Request​

Paramètres de requête​

Response 200​

DELETE /appointments/{id}​

Request​

Response 200​

Response 404​

Gestion des erreurs​

Codes d'erreur courants​

POST /appointments

Request

Response 201 - Success

Response 402 - Insufficient Credits

Response 400 - Bad Request

GET /appointments/{id}

Request

Response 200

Response 404

GET /appointments

Request

Paramètres de requête

Response 200

DELETE /appointments/{id}

Request

Response 200

Response 404

Gestion des erreurs

Codes d'erreur courants