Java SDK for MONCRENEAU

The official Java SDK to integrate MONCRENEAU into your Spring Boot, Jakarta EE, or standard Java applications.

Installation

Maven

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

Gradle

implementation 'com.moncreneau:moncreneau-java:1.0.0'

Configuration

Simple Configuration

import com.moncreneau.MoncreneauClient;

public class Main {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      // Ready to use!
  }
}

Spring Boot Configuration

Create a configuration class:

import com.moncreneau.MoncreneauClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MoncreneauConfig {
  
  @Value("${moncreneau.api-key}")
  private String apiKey;
  
  @Value("${moncreneau.base-url:https://mc-prd.duckdns.org/api/v1}")
  private String baseUrl;
  
  @Bean
  public MoncreneauClient moncreneauClient() {
      return MoncreneauClient.builder()
          .apiKey(apiKey)
          .baseUrl(baseUrl)
          .timeout(30) // seconds
          .build();
  }
}

Configuration file application.properties:

moncreneau.api-key=${MONCRENEAU_API_KEY}
moncreneau.base-url=https://mc-prd.duckdns.org/api/v1

Usage Examples

List Departments

import com.moncreneau.MoncreneauClient;
import com.moncreneau.model.Department;
import java.util.List;

public class Example {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      try {
          List<Department> departments = client.departments().list();
          
          for (Department dept : departments) {
              System.out.printf("ID: %d - %s (%s)%n", 
                  dept.getId(), 
                  dept.getName(), 
                  dept.getAddress()
              );
          }
      } catch (Exception e) {
          System.err.println("Error: " + e.getMessage());
      }
  }
}

Create an Appointment

import com.moncreneau.MoncreneauClient;
import com.moncreneau.model.Appointment;
import com.moncreneau.model.CreateAppointmentRequest;
import com.moncreneau.exception.InsufficientCreditsException;

public class Example {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      try {
          CreateAppointmentRequest request = CreateAppointmentRequest.builder()
              .departmentId(5L)
              .dateTime("2026-02-15T10:00:00")
              .name("Amadou Diallo")
              .build();
          
          Appointment appointment = client.appointments().create(request);
          
          System.out.println("✅ Appointment created!");
          System.out.println("ID: " + appointment.getId());
          System.out.println("QR Code: " + appointment.getQrCode());
          System.out.println("Status: " + appointment.getStatus());
          
      } catch (InsufficientCreditsException e) {
          System.err.println("❌ Insufficient credits: " + e.getMessage());
      } catch (Exception e) {
          System.err.println("❌ Error: " + e.getMessage());
      }
  }
}

Check Availability

import com.moncreneau.MoncreneauClient;
import com.moncreneau.model.SlotAvailability;

public class Example {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      try {
          SlotAvailability availability = client.departments()
              .checkAvailability(5L, "2026-02-15T10:00:00");
          
          if (availability.isAvailable()) {
              System.out.println("✅ Slot available!");
              System.out.println("Remaining slots: " + availability.getRemainingSlots());
          } else {
              System.out.println("❌ Slot unavailable");
              System.out.println("Reason: " + availability.getUnavailabilityReason());
          }
      } catch (Exception e) {
          System.err.println("Error: " + e.getMessage());
      }
  }
}

Cancel an Appointment

import com.moncreneau.MoncreneauClient;
import com.moncreneau.model.Appointment;

public class Example {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      try {
          Appointment cancelled = client.appointments().cancel(123L);
          
          System.out.println("✅ Appointment cancelled");
          System.out.println("Status: " + cancelled.getStatus());
          System.out.println("💰 1 credit refunded");
          
      } catch (Exception e) {
          System.err.println("❌ Error: " + e.getMessage());
      }
  }
}

Error Handling

import com.moncreneau.MoncreneauClient;
import com.moncreneau.exception.*;

public class Example {
  public static void main(String[] args) {
      MoncreneauClient client = new MoncreneauClient("YOUR_API_KEY");
      
      try {
          // Your API call
          client.appointments().create(request);
          
      } catch (InsufficientCreditsException e) {
          // Not enough credits
          System.err.println("Insufficient credits: " + e.getMessage());
          System.err.println("Available credits: " + e.getAvailableCredits());
          System.err.println("Required credits: " + e.getRequiredCredits());
          
      } catch (ValidationException e) {
          // Validation failed
          System.err.println("Validation errors:");
          e.getErrors().forEach(error -> 
              System.err.println("- " + error.getField() + ": " + error.getMessage())
          );
          
      } catch (NotFoundException e) {
          // Resource not found
          System.err.println("Not found: " + e.getMessage());
          
      } catch (UnauthorizedException e) {
          // Invalid API key
          System.err.println("Invalid API key");
          
      } catch (ApiException e) {
          // Generic API error
          System.err.println("API error: " + e.getMessage());
          System.err.println("Status code: " + e.getStatusCode());
          
      } catch (Exception e) {
          // Network or unexpected error
          System.err.println("Unexpected error: " + e.getMessage());
      }
  }
}

Spring Boot Integration

Service

import com.moncreneau.MoncreneauClient;
import com.moncreneau.model.*;
import org.springframework.stereotype.Service;
import lombok.RequiredArgsConstructor;

@Service
@RequiredArgsConstructor
public class AppointmentService {
  
  private final MoncreneauClient moncreneauClient;
  
  public List<Department> listDepartments() {
      return moncreneauClient.departments().list();
  }
  
  public Appointment createAppointment(Long deptId, String dateTime, String name) {
      CreateAppointmentRequest request = CreateAppointmentRequest.builder()
          .departmentId(deptId)
          .dateTime(dateTime)
          .name(name)
          .build();
          
      return moncreneauClient.appointments().create(request);
  }
  
  public SlotAvailability checkAvailability(Long deptId, String dateTime) {
      return moncreneauClient.departments().checkAvailability(deptId, dateTime);
  }
}

Controller

import com.moncreneau.model.*;
import com.moncreneau.exception.InsufficientCreditsException;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.*;
import lombok.RequiredArgsConstructor;

@RestController
@RequestMapping("/api/appointments")
@RequiredArgsConstructor
public class AppointmentController {
  
  private final AppointmentService appointmentService;
  
  @PostMapping
  public ResponseEntity<?> createAppointment(@RequestBody CreateAppointmentDto dto) {
      try {
          Appointment appointment = appointmentService.createAppointment(
              dto.getDepartmentId(),
              dto.getDateTime(),
              dto.getName()
          );
          return ResponseEntity.status(HttpStatus.CREATED).body(appointment);
          
      } catch (InsufficientCreditsException e) {
          return ResponseEntity.status(HttpStatus.PAYMENT_REQUIRED)
              .body(Map.of("error", e.getMessage()));
      }
  }
  
  @GetMapping("/departments/{id}/availability")
  public ResponseEntity<SlotAvailability> checkAvailability(
      @PathVariable Long id,
      @RequestParam String dateTime
  ) {
      SlotAvailability availability = appointmentService.checkAvailability(id, dateTime);
      return ResponseEntity.ok(availability);
  }
}

Advanced Configuration

Timeout and Retry

import com.moncreneau.MoncreneauClient;
import java.time.Duration;

MoncreneauClient client = MoncreneauClient.builder()
  .apiKey("YOUR_API_KEY")
  .timeout(Duration.ofSeconds(30))
  .connectTimeout(Duration.ofSeconds(10))
  .maxRetries(3)
  .retryDelay(Duration.ofSeconds(1))
  .build();

Custom Logging

import com.moncreneau.MoncreneauClient;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

Logger logger = LoggerFactory.getLogger("moncreneau");

MoncreneauClient client = MoncreneauClient.builder()
  .apiKey("YOUR_API_KEY")
  .logger(logger)
  .debug(true)
  .build();

Resources

• Complete API Documentation
• Spring Boot Examples
• Javadoc