API Documentation

Overview

The Customer Management API provides comprehensive endpoints for managing customer information, relationships, and interactions within the Bee O'clock panel service. This API enables businesses to maintain customer records, handle attendee management, and support order-customer relationships with robust validation and data integrity.

Base URL

{base_url}/v1/customer

Authentication

All endpoints require authentication via Bearer token and business tenant ID header.

Authorization: Bearer {access_token}
x-business-tenant-id: {tenant_id}

Core Endpoints

1. Get Paginated Customers

Retrieves a paginated list of customers for the authenticated business.

Endpoint: GET /paged

Headers:

Authorization: Bearer {access_token}
x-business-tenant-id: {tenant_id}

Query Parameters:

{
  page?: number;           // Page number (default: 1)
  limit?: number;          // Items per page (default: 10, max: 100)
  sortBy?: string;         // Sort field (firstName, lastName, email, createdAt)
  sortDirection?: 'asc' | 'desc'; // Sort direction (default: 'desc')
  search?: string;         // Search term for name or email
  customerType?: CustomerTypeEnum; // Filter by customer type
}

Response:

{
  items: CustomerDto[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
  meta?: {
    searchTerm?: string;
    filters?: Record<string, any>;
  };
}

Example Request:

curl -X GET "https://api.beeoclock.com/v1/customer/paged?page=1&limit=20&search=john&sortBy=firstName" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-business-tenant-id: 614d1c4c5f1b2c001f5a7b23"

Example Response:

{
  "items": [
    {
      "object": "CustomerDto",
      "_id": "67b8ac9d4b39c2fd27431017",
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "[phone]",
      "note": "Regular customer, prefers morning appointments",
      "customerType": "regular",
      "state": "active",
      "createdAt": "2025-02-21T16:40:41.031Z",
      "updatedAt": "2025-02-22T12:13:24.745Z"
    }
  ],
  "totalSize": 20,
}

Error Responses:

// 400 Bad Request
{
  "statusCode": 400,
  "message": "Invalid pagination parameters",
  "error": "Bad Request"
}

// 403 Forbidden
{
  "statusCode": 403,
  "message": "Insufficient permissions to read customers",
  "error": "Forbidden"
}

---

2. Get Customer by ID

Retrieves detailed information for a specific customer.

Endpoint: GET /{id}

Path Parameters:

• id (string, required): Customer ID

Response:

CustomerDto

Example Request:

curl -X GET "https://api.beeoclock.com/v1/customer/67b8ac9d4b39c2fd27431017" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-business-tenant-id: 614d1c4c5f1b2c001f5a7b23"

Example Response:

{
  "object": "CustomerDto",
  "_id": "67b8ac9d4b39c2fd27431017",
  "firstName": "John",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "[phone]",
  "note": "Regular customer, prefers morning appointments",
  "customerType": "regular",
  "state": "active",
  "stateHistory": [
    {
      "state": "active",
      "setAt": "2025-02-21T16:40:41.031Z",
      "reason": "Customer created"
    }
  ],
  "createdAt": "2025-02-21T16:40:41.031Z",
  "updatedAt": "2025-02-22T12:13:24.745Z",
  "_version": "2"
}

Error Responses:

// 404 Not Found
{
  "statusCode": 404,
  "message": "Customer not found",
  "error": "Not Found"
}

---

3. Create Customer

Creates a new customer record with validation.

Endpoint: POST /

Request Body:

CustomerDto {
  firstName?: string;      // Customer first name
  lastName?: string;       // Customer last name
  email?: string;          // Customer email (validated)
  phone?: string;          // Customer phone (validated and normalized)
  note?: string;           // Internal notes about customer
  customerType?: CustomerTypeEnum; // Customer type (default: 'regular')
}

Validation Rules:

• At least one of: firstName, lastName, email, or phone must be provided

• Email must be valid format if provided

• Phone must be valid format if provided (automatically normalized)

• Customer type defaults to 'regular'

Response:

CustomerDto // Complete customer object with generated ID

Example Request:

curl -X POST "https://api.beeoclock.com/v1/customer" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-business-tenant-id: 614d1c4c5f1b2c001f5a7b23" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "[phone]",
    "note": "Prefers text message reminders"
  }'

Example Response:

{
  "object": "CustomerDto",
  "_id": "67b8ac9d4b39c2fd27431018",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "1987654321",
  "note": "Prefers text message reminders",
  "customerType": "regular",
  "state": "active",
  "stateHistory": [
    {
      "state": "active",
      "setAt": "2025-02-25T10:30:15.123Z",
      "reason": "Customer created"
    }
  ],
  "createdAt": "2025-02-25T10:30:15.123Z",
  "updatedAt": "2025-02-25T10:30:15.123Z",
  "_version": "1"
}

Error Responses:

// 400 Bad Request - Validation Error
{
  "statusCode": 400,
  "message": "At least one field must be filled: phone, email, first name or last name.",
  "error": "Bad Request"
}

// 400 Bad Request - Email Format Error
{
  "statusCode": 400,
  "message": "Invalid email format: invalid-email",
  "error": "Bad Request"
}

// 409 Conflict - Duplicate Customer
{
  "statusCode": 409,
  "message": "Customer with this email already exists",
  "error": "Conflict"
}

---

4. Update Customer

Updates an existing customer record with partial updates supported.

Endpoint: PUT /{id}

Path Parameters:

• id (string, required): Customer ID to update

Request Body:

CustomerDto // Partial update object

Response:

CustomerDto // Updated customer object

Example Request:

curl -X PUT "https://api.beeoclock.com/v1/customer/67b8ac9d4b39c2fd27431017" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-business-tenant-id: 614d1c4c5f1b2c001f5a7b23" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Updated note: Customer prefers afternoon appointments",
    "phone": "[phone]"
  }'

Example Response:

{
  "object": "CustomerDto",
  "_id": "67b8ac9d4b39c2fd27431017",
  "firstName": "John",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "1234567891",
  "note": "Updated note: Customer prefers afternoon appointments",
  "customerType": "regular",
  "state": "active",
  "stateHistory": [
    {
      "state": "active",
      "setAt": "2025-02-21T16:40:41.031Z",
      "reason": "Customer created"
    }
  ],
  "createdAt": "2025-02-21T16:40:41.031Z",
  "updatedAt": "2025-02-25T11:45:30.456Z",
  "_version": "3"
}

---

5. Delete Customer

Soft deletes a customer record (sets state to inactive).

Endpoint: DELETE /{id}

Path Parameters:

• id (string, required): Customer ID to delete

Response:

void // No content returned

Example Request:

curl -X DELETE "https://api.beeoclock.com/v1/customer/67b8ac9d4b39c2fd27431017" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-business-tenant-id: 614d1c4c5f1b2c001f5a7b23"

Success Response:

HTTP/1.1 200 OK

Error Responses:

// 404 Not Found
{
  "statusCode": 404,
  "message": "Customer not found",
  "error": "Not Found"
}

// 409 Conflict - Customer has active orders
{
  "statusCode": 409,
  "message": "Cannot delete customer with active orders",
  "error": "Conflict"
}

---

Data Transfer Objects

CustomerDto

interface CustomerDto {
  object?: 'CustomerDto';
  _id?: string;              // Auto-generated MongoDB ObjectId
  firstName?: string;        // Customer first name (max 100 chars)
  lastName?: string;         // Customer last name (max 100 chars)
  phone?: string;           // Normalized phone number (numbers only)
  email?: string;           // Validated email address
  note?: string;            // Internal business notes (max 1000 chars)
  customerType?: CustomerTypeEnum; // Customer classification
  state?: string;           // Entity state (active, inactive)
  stateHistory?: StateHistoryEntry[]; // State change audit trail
  createdAt?: string;       // ISO date string
  updatedAt?: string;       // ISO date string
  _version?: string;        // Optimistic locking version
}

CustomerPaginationDto

interface CustomerPaginationDto {
  page?: number;            // Page number (min: 1, default: 1)
  limit?: number;           // Items per page (min: 1, max: 100, default: 10)
  sortBy?: string;          // Sort field
  sortDirection?: 'asc' | 'desc'; // Sort direction
  search?: string;          // Search term
  customerType?: CustomerTypeEnum; // Filter by type
}

Enumerations

CustomerTypeEnum

enum CustomerTypeEnum {
  regular = 'regular',        // Regular registered customer
  unregistered = 'unregistered', // Unregistered customer
  new = 'new',               // First-time customer
  anonymous = 'anonymous'     // Anonymous customer (public orders)
}

Customer-Order Relationships

Order Integration

Customers are integrated with orders through the attendee system:

// Customer as order attendee
interface AttendantDto {
  object: 'AttendantDto';
  customer: CustomerDto;     // Customer snapshot
  firstTime: boolean;        // First visit indicator
}

// Order contains customer references
interface OrderDto {
  customer: CustomerDto;     // Primary customer (payer)
  services: OrderServiceDto[]; // Services with attendees
}

// Each service has appointment details with attendees
interface OrderAppointmentDetailsDto {
  attendees: AttendantDto[]; // Multiple attendees per service
  // ... other appointment details
}

Payment Integration

Customers are captured in payment records:

interface PaymentDto {
  payer: CustomerDto;        // Customer who made payment
  orderId: string;           // Associated order
  // ... payment details
}

Validation Rules

Customer Creation Validation

1. Mandatory Fields: At least one of firstName, lastName, email, or phone required

2. Email Validation: Must match regex pattern for valid email format

3. Phone Validation: Must match international phone number pattern

4. Phone Normalization: Automatically extracts and stores only numbers

5. Duplicate Prevention: Prevents duplicate customers based on email/phone combination

Business Rules

1. Customer Types:

   • regular: Standard registered customers with full profile

   • unregistered: Customers without full registration

   • new: First-time customers

   • anonymous: Anonymous public order customers

2. Data Integrity:

   • Customer data is snapshotted in orders and payments

   • Updates to customer records don't affect historical data

   • Soft deletion preserves data for reporting and history

3. Multi-tenancy:

   • All operations are tenant-scoped

   • Customers are isolated per business tenant

   • No cross-tenant data access

Error Handling

Common Error Codes

Status Code	Error Type	Description
400	Validation Error	Invalid request data or missing required fields
401	Unauthorized	Invalid or missing authentication token
403	Forbidden	Insufficient permissions for operation
404	Not Found	Customer not found
409	Conflict	Duplicate customer or business rule violation
422	Unprocessable Entity	Valid request but business logic prevents execution
500	Internal Server Error	Unexpected server error

Error Response Format

interface ErrorResponse {
  statusCode: number;
  message: string;
  error: string;
  details?: string[];     // Additional validation errors
  timestamp?: string;     // Error timestamp
  path?: string;         // Request path
}

Security Considerations

Authentication & Authorization

• Bearer Token Required: All endpoints require valid JWT token

• Tenant Isolation: Strict tenant-based data separation

• Permission Validation: Role-based access control for operations

• Audit Logging: All customer operations are logged for security

Data Protection

• PII Handling: Customer data treated as Personally Identifiable Information

• GDPR Compliance: Support for data portability and deletion rights

• Encryption: Sensitive data encrypted at rest and in transit

• Access Logging: Customer data access is logged and monitored

Rate Limiting

• API Rate Limits: Standard rate limiting applied to all endpoints

• Bulk Operations: Special consideration for pagination and bulk retrieval

• Search Optimization: Search queries optimized to prevent performance issues

Performance Considerations

Database Optimization

• Indexing: Optimized indexes on frequently queried fields

• Pagination: Efficient cursor-based pagination for large datasets

• Caching: Redis caching for frequently accessed customer data

• Query Optimization: Selective field projection for list operations

Caching Strategy

// Cache keys
const CACHE_KEYS = {
  CUSTOMER_BY_ID: 'customer:id:{customerId}',
  PAGED_CUSTOMERS: 'customers:paged:{tenantId}:{hash}',
  CUSTOMER_SEARCH: 'customers:search:{tenantId}:{query}'
};

// Cache TTL
const CACHE_TTL = {
  CUSTOMER_DETAILS: 300,    // 5 minutes
  CUSTOMER_LIST: 60,        // 1 minute
  SEARCH_RESULTS: 180       // 3 minutes
};

Integration Examples

Customer Creation Flow

// Step 1: Validate customer data
const customerData = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  phone: '[phone]'
};

// Step 2: Create customer
const response = await fetch('/v1/customer', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'x-business-tenant-id': tenantId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(customerData)
});

const customer = await response.json();

// Step 3: Customer ID available for orders
const customerId = customer._id;

Order Attendee Integration

// Using customer in order creation
const orderService = {
  serviceSnapshot: { /* service details */ },
  orderAppointmentDetails: {
    start: '2025-03-01T10:00:00Z',
    end: '2025-03-01T11:00:00Z',
    attendees: [{
      customer: customer,      // CustomerDto
      firstTime: false
    }]
  }
};

Customer Search and Selection

// Search customers for appointment booking
const searchResponse = await fetch(
  `/v1/customer/paged?search=${encodeURIComponent(searchTerm)}&limit=10`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-business-tenant-id': tenantId
    }
  }
);

const { items: customers } = await searchResponse.json();

// Present customer list for selection
customers.forEach(customer => {
  console.log(`${customer.firstName} ${customer.lastName} (${customer.email})`);
});

Testing Examples

Unit Testing

describe('Customer API', () => {
  test('should create customer with valid data', async () => {
    const customerData = {
      firstName: 'Test',
      lastName: 'User',
      email: '[email protected]'
    };

    const response = await request(app)
      .post('/v1/customer')
      .set('Authorization', `Bearer ${authToken}`)
      .set('x-business-tenant-id', tenantId)
      .send(customerData)
      .expect(200);

    expect(response.body.firstName).toBe('Test');
    expect(response.body.email).toBe('[email protected]');
    expect(response.body._id).toBeDefined();
  });

  test('should validate email format', async () => {
    const invalidData = {
      firstName: 'Test',
      email: 'invalid-email'
    };

    await request(app)
      .post('/v1/customer')
      .set('Authorization', `Bearer ${authToken}`)
      .set('x-business-tenant-id', tenantId)
      .send(invalidData)
      .expect(400);
  });
});

---

Summary

The Customer Management API provides a robust foundation for managing customer relationships within the Bee O'clock ecosystem. Key features include:

• Comprehensive CRUD Operations with validation and error handling

• Advanced Search and Pagination for efficient customer discovery

• Strong Data Validation ensuring data quality and consistency

• Integration Support for orders, payments, and appointments

• Multi-tenant Architecture with proper data isolation

• Performance Optimization through caching and efficient querying

• Security Compliance with authentication, authorization, and audit logging

The API supports complex business scenarios including customer-order relationships, payment processing, and historical data preservation while maintaining high performance and data integrity standards.