The Order Management API provides comprehensive functionality for managing orders within the Bee O'clock panel service. This module handles the complete order lifecycle, including creation, updates, status management, and deletion of orders containing services and products.
Base Configuration
Authentication
All endpoints require Bearer token authentication.
Headers
Authorization: Bearer <token> - Required for all endpoints
x-business-tenant-id: <tenant_id> - Required for multi-tenancy support
Content-Type: application/json - For POST/PUT requests
Base URL
/api/v1/order
Endpoints
1. Get Paginated Orders
Endpoint:GET /api/v1/order/paged
Description: Retrieves a paginated list of orders with advanced filtering capabilities.
Query Parameters:
Response:
Example Request:
Example Response:
2. Get Order by ID
Endpoint:GET /api/v1/order/{id}
Description: Retrieves a specific order by its ID with permission validation.
Path Parameters:
id (string, required) - Order ID
Response:OrderDto
Example Request:
Example Response:
3. Create Order
Endpoint:POST /api/v1/order
Description: Creates a new order with services and products through a saga pattern with validation and rollback capabilities.
Request Body:OrderDto
Response:OrderDto
Example Request:
Example Response:
4. Update Order
Endpoint:PUT /api/v1/order/{id}
Description: Updates an existing order with validation and permission checks.
Path Parameters:
id (string, required) - Order ID
Request Body:OrderDto
Response:OrderDto
Example Request:
5. Delete Order
Endpoint:DELETE /api/v1/order/{id}
Description: Soft deletes an order with permission validation and dependency checking.
Path Parameters:
id (string, required) - Order ID
Response:void (204 No Content)
Example Request:
Data Models
OrderDto
OrderServiceDto
OrderProductDto
OrderAppointmentDetailsDto
OrderPaginationDto
Enums
OrderStatusEnum
OrderServiceStatusEnum
ReservationTypeEnum
PaymentStatusEnum
Error Handling
Common Error Responses
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Entity
Business Rules
Order Creation
Service Validation: All services must be valid and available
Time Slot Validation: Appointment times must not conflict with existing bookings
Specialist Availability: Assigned specialists must be available during requested times
Customer Validation: Customer must exist and be valid
Product Validation: All products must be available in inventory
Order Updates
Status Transitions: Updates must follow valid status transition rules
Service Modification: Changes to services require specialist availability validation
Payment Constraints: Cannot modify orders with completed payments
Time Constraints: Cannot modify past appointments
Permission Validation: User must have appropriate permissions for the scope of changes
Order Deletion
Soft Delete: Orders are marked as deleted rather than physically removed
Payment Check: Cannot delete orders with active or completed payments
Dependency Validation: Cannot delete orders with dependent records
History Preservation: All historical data is maintained for audit purposes
Permission Scopes
OWN: Users can only access orders assigned to them
TEAM: Users can access orders within their team
BUSINESS: Users can access all orders within the business
ADMIN: Full access to all order operations
Performance Considerations
Pagination
Default page size: 10 items
Maximum page size: 100 items
Use pagination for large datasets to maintain performance
Filtering
Date range filters are optimized with database indexes
Status filtering uses enum indexes for fast queries
Member ID filtering supports array-based queries
Caching
Order data is cached for frequently accessed items
Cache invalidation occurs on order updates
Cache warming for dashboard queries
Database Optimization
Compound indexes on status, dates, and member IDs
Separate collections for order services and products
Optimized queries with projection for large orders
{
page?: number; // Page number (default: 1)
size?: number; // Items per page (default: 10)
phrase?: string; // Search phrase for order content
start?: string; // Start date filter (ISO string)
end?: string; // End date filter (ISO string)
customerId?: string; // Filter by customer ID
statuses?: OrderStatusEnum[]; // Filter by order statuses
memberIds?: string[]; // Filter by assigned member IDs
}
{
items: OrderDto[];
totalSize: number;
}
GET /api/v1/order/paged?page=1&size=10&statuses[]=inProgress&statuses[]=confirmed&start=2024-01-01T00:00:00.000Z&end=2024-12-31T23:59:59.999Z
Authorization: Bearer <token>
x-business-tenant-id: <tenant_id>
{
_id?: string; // Order ID
status?: OrderStatusEnum; // Order status
meta?: MetaDto; // Metadata information
products?: OrderProductDto[]; // Order products
services?: OrderServiceDto[]; // Order services
paymentStatus?: PaymentStatusEnum; // Payment status
businessNote?: string; // Internal business note
notificationSettings?: OrderNotificationSettingsDto; // Notification preferences
customer?: CustomerDto; // Customer information
createdAt?: string; // Creation timestamp
updatedAt?: string; // Last update timestamp
}
{
_id?: string; // Service ID
orderId?: string; // Parent order ID
serviceSnapshot?: ServiceDto; // Service configuration snapshot
orderAppointmentDetails?: OrderAppointmentDetailsDto; // Appointment details
status: OrderServiceStatusEnum; // Service status
customerNote?: string; // Customer note for service
meta?: MetaDto; // Service metadata
paymentStatus?: PaymentStatusEnum; // Service payment status
createdAt?: string; // Creation timestamp
updatedAt?: string; // Last update timestamp
}
{
_id?: string; // Product ID
orderId?: string; // Parent order ID
orderServiceId?: string; // Associated service ID
productSnapshot: ProductDto; // Product configuration snapshot
quantity: number; // Product quantity
meta?: MetaDto; // Product metadata
paymentStatus?: PaymentStatusEnum; // Product payment status
createdAt?: string; // Creation timestamp
updatedAt?: string; // Last update timestamp
}
{
start: string; // Appointment start time (ISO string)
end: string; // Appointment end time (ISO string)
type?: ReservationTypeEnum; // Reservation type
languageCodes?: LanguageCodeEnum[]; // Preferred languages
specialists: SpecialistDto[]; // Assigned specialists
attendants?: AttendantDto[]; // Service attendants
location?: LocationDto; // Service location
attachments?: AttachmentDto[]; // Additional attachments
}
{
page?: number; // Page number
size?: number; // Items per page
phrase?: string; // Search phrase
start?: string; // Start date filter
end?: string; // End date filter
customerId?: string; // Customer ID filter
statuses?: OrderStatusEnum[]; // Status filters
memberIds?: string[]; // Member ID filters
}
enum OrderStatusEnum {
draft = 'draft', // Order in draft state
deleted = 'deleted', // Order deleted
requested = 'requested', // Order requested
confirmed = 'confirmed', // Order confirmed
inProgress = 'inProgress', // Order in progress
done = 'done', // Order completed
cancelled = 'cancelled', // Order cancelled
rejected = 'rejected', // Order rejected
waitingForPayment = 'waitingForPayment' // Awaiting payment
}
enum OrderServiceStatusEnum {
requested = 'requested', // Service requested
accepted = 'accepted', // Service accepted
ready = 'ready', // Service ready
inProgress = 'inProgress', // Service in progress
done = 'done', // Service completed
rejected = 'rejected', // Service rejected
cancelled = 'cancelled', // Service cancelled
deleted = 'deleted' // Service deleted
}
