API Documentation

Overview

The Service Management API provides comprehensive service lifecycle management for the Bee O'clock platform. Services represent bookable offerings provided by businesses, including their configuration, pricing, scheduling, and presentation details.

Base URL

{api_base_url}/api/v1/service

Authentication

All endpoints require Bearer token authentication and business tenant identification.

Headers Required:

Authorization: Bearer <access_token>
x-business-tenant-id: <tenant_id>
Content-Type: application/json

Endpoints

1. Get Paged Services

Retrieve a paginated list of services with optional search functionality.

Endpoint: GET /paged

Query Parameters:

Parameter	Type	Required	Default	Description
page	number	No	1	Page number for pagination
size	number	No	10	Number of items per page
phrase	string	No	-	Search phrase for filtering by service title or description

Example Request:

GET /api/v1/service/paged?page=1&size=10&phrase=haircut
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345

Response Schema:

interface PaginatedServicesResponse {
  items: ServiceDto[];
  totalSize : number;
}

Example Response:

{
  "items": [
    {
      "_id": "64a7b8f123456789abcdef01",
      "object": "ServiceDto",
      "languageVersions": [
        {
          "language": "en",
          "title": "Haircut and Styling",
          "description": "Professional haircut and styling service"
        }
      ],
      "durationVersions": [
        {
          "durationInSeconds": 3600,
          "breakInSeconds": 300,
          "prices": [
            {
              "price": 50.00,
              "currency": "USD"
            }
          ]
        }
      ],
      "presentation": {
        "color": "#FF5733",
        "media": []
      },
      "configuration": {
        "duration": {
          "durationVersionType": "RANGE"
        }
      },
      "prepaymentPolicy": {
        "isRequired": false
      },
      "schedules": [],
      "order": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "totalSize": 1
}

2. Get Service by ID

Retrieve detailed information about a specific service.

Endpoint: GET /{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier

Example Request:

GET /api/v1/service/64a7b8f123456789abcdef01
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345

Response Schema: ServiceDto

Example Response:

{
  "_id": "64a7b8f123456789abcdef01",
  "object": "ServiceDto",
  "languageVersions": [
    {
      "language": "en",
      "title": "Haircut and Styling",
      "description": "Professional haircut and styling service with consultation"
    },
    {
      "language": "es",
      "title": "Corte y Peinado",
      "description": "Servicio profesional de corte y peinado con consulta"
    }
  ],
  "durationVersions": [
    {
      "durationInSeconds": 3600,
      "breakInSeconds": 300,
      "prices": [
        {
          "price": 50.00,
          "currency": "USD",
          "preferredLanguages": ["en"]
        },
        {
          "price": 45.00,
          "currency": "EUR",
          "preferredLanguages": ["es"]
        }
      ]
    }
  ],
  "presentation": {
    "color": "#FF5733",
    "media": [
      {
        "_id": "64a7b8f123456789abcdef02",
        "url": "https://storage.example.com/service-images/haircut.jpg",
        "mimeType": "image/jpeg"
      }
    ]
  },
  "configuration": {
    "duration": {
      "durationVersionType": "RANGE"
    }
  },
  "prepaymentPolicy": {
    "isRequired": true,
    "isPercentage": true,
    "value": "25",
    "minimalCancelTime": "86400"
  },
  "schedules": [
    {
      "weekDays": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ],
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

3. Create Service

Create a new service with complete configuration.

Endpoint: POST /

Request Schema: ServiceDto

Example Request:

POST /api/v1/service
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345
Content-Type: application/json

{
  "languageVersions": [
    {
      "language": "en",
      "title": "Deep Tissue Massage",
      "description": "Therapeutic deep tissue massage for muscle relief"
    }
  ],
  "durationVersions": [
    {
      "durationInSeconds": 5400,
      "breakInSeconds": 600,
      "prices": [
        {
          "price": 80.00,
          "currency": "USD"
        }
      ]
    }
  ],
  "presentation": {
    "color": "#4A90E2"
  },
  "configuration": {
    "duration": {
      "durationVersionType": "FIXED"
    }
  },
  "prepaymentPolicy": {
    "isRequired": false
  },
  "schedules": [
    {
      "weekDays": [1, 2, 3, 4, 5, 6],
      "startTime": "08:00",
      "endTime": "20:00"
    }
  ],
  "order": 2
}

Response Schema: ServiceDto (created service with generated ID)

Example Response:

{
  "_id": "64a7b8f123456789abcdef03",
  "object": "ServiceDto",
  "languageVersions": [
    {
      "language": "en",
      "title": "Deep Tissue Massage",
      "description": "Therapeutic deep tissue massage for muscle relief"
    }
  ],
  "durationVersions": [
    {
      "durationInSeconds": 5400,
      "breakInSeconds": 600,
      "prices": [
        {
          "price": 80.00,
          "currency": "USD"
        }
      ]
    }
  ],
  "presentation": {
    "color": "#4A90E2",
    "media": []
  },
  "configuration": {
    "duration": {
      "durationVersionType": "FIXED"
    }
  },
  "prepaymentPolicy": {
    "isRequired": false
  },
  "schedules": [
    {
      "weekDays": [1, 2, 3, 4, 5, 6],
      "startTime": "08:00",
      "endTime": "20:00"
    }
  ],
  "order": 2,
  "createdAt": "2024-01-25T09:15:00Z",
  "updatedAt": "2024-01-25T09:15:00Z"
}

4. Update Service

Update an existing service's information.

Endpoint: PUT /{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier

Request Schema: ServiceDto

Example Request:

PUT /api/v1/service/64a7b8f123456789abcdef01
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345
Content-Type: application/json

{
  "_id": "64a7b8f123456789abcdef01",
  "languageVersions": [
    {
      "language": "en",
      "title": "Premium Haircut and Styling",
      "description": "Premium haircut and styling service with luxury consultation"
    }
  ],
  "durationVersions": [
    {
      "durationInSeconds": 4200,
      "breakInSeconds": 300,
      "prices": [
        {
          "price": 65.00,
          "currency": "USD"
        }
      ]
    }
  ],
  "prepaymentPolicy": {
    "isRequired": true,
    "isPercentage": true,
    "value": "30",
    "minimalCancelTime": "172800"
  },
  "order": 1
}

Response Schema: ServiceDto (updated service)

5. Update Service Required Resources

Update the list of resources required for a service.

Endpoint: PUT /{id}/required-resources

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier

Request Schema: RequiredResourceDto[]

Example Request:

PUT /api/v1/service/64a7b8f123456789abcdef01/required-resources
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345
Content-Type: application/json

[
  {
    "resourceId": "64a7b8f123456789abcdef04",
    "quantity": 1,
    "isRequired": true
  },
  {
    "resourceId": "64a7b8f123456789abcdef05",
    "quantity": 2,
    "isRequired": false
  }
]

Response: 204 No Content

6. Delete Service

Soft delete a service (marks as deleted while preserving data).

Endpoint: DELETE /{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier

Example Request:

DELETE /api/v1/service/64a7b8f123456789abcdef01
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345

Response Schema:

interface DeleteServiceResponse {
  deletedCount: number;
}

Example Response:

{
  "deletedCount": 1
}

Service Media Management

Upload Service Media

Endpoint: POST /{id}/media

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier

Request: multipart/form-data

Field	Type	Required	Description
file	File	Yes	Image file (JPG, PNG, WebP)
description	string	No	Media description

Example Request:

POST /api/v1/service/64a7b8f123456789abcdef01/media
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-business-tenant-id: 12345
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="service-image.jpg"
Content-Type: image/jpeg

[binary image data]
--boundary
Content-Disposition: form-data; name="description"

Main service promotional image
--boundary--

Delete Service Media

Endpoint: DELETE /{id}/media/{mediaId}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique service identifier
mediaId	string	Yes	Unique media identifier

Data Transfer Objects

ServiceDto

interface ServiceDto {
  _id?: string;
  object?: 'ServiceDto';
  configuration?: ServiceConfigurationDto;
  presentation?: PresentationDto;
  prepaymentPolicy?: PrepaymentPolicyDto;
  languageVersions: LanguageVersionDto[];
  durationVersions?: DurationVersionDto[];
  schedules?: ScheduleDto[];
  order?: number | null;
  createdAt?: string;
  updatedAt?: string;
  entityState?: EntityStateDto[];
}

ServiceConfigurationDto

interface ServiceConfigurationDto {
  object?: 'ServiceConfigurationDto';
  duration?: DurationConfigurationDto;
}

DurationConfigurationDto

interface DurationConfigurationDto {
  object?: 'DurationConfigurationDto';
  durationVersionType: DurationVersionTypeEnum;
}

PresentationDto

interface PresentationDto {
  object?: 'PresentationDto';
  color?: string;
  media?: MediaDto[];
}

PrepaymentPolicyDto

interface PrepaymentPolicyDto {
  object?: 'PrepaymentPolicyDto';
  isRequired: boolean;
  isPercentage?: boolean;
  value?: string;
  minimalCancelTime?: string;
}

DurationVersionDto

interface DurationVersionDto {
  object?: 'DurationVersionDto';
  breakInSeconds?: number;
  durationInSeconds: number;
  prices?: PriceDto[];
}

PriceDto

interface PriceDto {
  object?: 'PriceDto';
  price: number;
  currency?: CurrencyCodeEnum;
  preferredLanguages?: LanguageCodeEnum[];
}

Enums

DurationVersionTypeEnum

enum DurationVersionTypeEnum {
  FIXED = 'FIXED',
  RANGE = 'RANGE'
}

CurrencyCodeEnum

enum CurrencyCodeEnum {
  USD = 'USD',
  EUR = 'EUR',
  GBP = 'GBP',
  // ... other currency codes
}

LanguageCodeEnum

enum LanguageCodeEnum {
  en = 'en',
  es = 'es',
  fr = 'fr',
  de = 'de',
  // ... other language codes
}

Error Responses

Common Error Format

interface ApiErrorResponse {
  statusCode: number;
  message: string;
  error: string;
  timestamp: string;
  path: string;
}

Error Status Codes

Status Code	Error Type	Description
400	Bad Request	Invalid request data or validation errors
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions for the operation
404	Not Found	Service not found
409	Conflict	Service title conflict or business rule violation
422	Unprocessable Entity	Invalid service configuration
500	Internal Server Error	Unexpected server error

Example Error Responses

400 Bad Request - Validation Error:

{
  "statusCode": 400,
  "message": [
    "languageVersions should not be empty",
    "durationVersions[0].durationInSeconds must be a positive number"
  ],
  "error": "Bad Request",
  "timestamp": "2024-01-25T10:15:30Z",
  "path": "/api/v1/service"
}

404 Not Found:

{
  "statusCode": 404,
  "message": "Service with ID 64a7b8f123456789abcdef01 not found",
  "error": "Not Found",
  "timestamp": "2024-01-25T10:15:30Z",
  "path": "/api/v1/service/64a7b8f123456789abcdef01"
}

403 Forbidden:

{
  "statusCode": 403,
  "message": "Insufficient permissions to manage services",
  "error": "Forbidden",
  "timestamp": "2024-01-25T10:15:30Z",
  "path": "/api/v1/service"
}

Business Rules

Service Creation Rules

1. Language Versions: At least one language version is required

2. Duration Versions: At least one duration version is required

3. Pricing: Each duration version must have at least one price

4. Schedules: Schedules are optional but if provided must be valid

5. Order: Order numbers must be unique within tenant

Service Update Rules

1. Immutable Fields: Service ID cannot be changed

2. Language Versions: Cannot remove all language versions

3. Duration Versions: Cannot remove all duration versions

4. Active Orders: Cannot delete services with active orders

5. Media: Media files must be valid image formats

Validation Rules

1. Duration: Duration must be positive integer in seconds

2. Price: Price must be positive number

3. Color: Must be valid hex color code

4. Schedule Times: Start time must be before end time

5. Prepayment: Percentage values must be 0-100

Permission Requirements

All service management operations require appropriate permissions:

• READ_SERVICE: View service information

• CREATE_SERVICE: Create new services

• EDIT_SERVICE: Update existing services

• DELETE_SERVICE: Delete services

• MANAGE_SERVICE_MEDIA: Upload/delete service media

Rate Limiting

• Read Operations: 100 requests per minute

• Write Operations: 30 requests per minute

• Media Upload: 10 requests per minute

Caching

• Service Lists: Cached for 5 minutes

• Individual Services: Cached for 15 minutes

• Cache Invalidation: Automatic on service updates

Integration Examples

JavaScript/TypeScript

// Create service
const serviceData = {
  languageVersions: [
    {
      language: 'en',
      title: 'Massage Therapy',
      description: 'Relaxing massage therapy session'
    }
  ],
  durationVersions: [
    {
      durationInSeconds: 3600,
      prices: [{ price: 60, currency: 'USD' }]
    }
  ]
};

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

const createdService = await response.json();

cURL Examples

# Get paged services
curl -X GET "https://api.beeoclock.com/api/v1/service/paged?page=1&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-business-tenant-id: YOUR_TENANT_ID"

# Create service
curl -X POST "https://api.beeoclock.com/api/v1/service" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-business-tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "languageVersions": [
      {
        "language": "en",
        "title": "Haircut",
        "description": "Professional haircut service"
      }
    ],
    "durationVersions": [
      {
        "durationInSeconds": 1800,
        "prices": [{"price": 30, "currency": "USD"}]
      }
    ]
  }'

# Update service
curl -X PUT "https://api.beeoclock.com/api/v1/service/SERVICE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-business-tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"order": 2}'

# Delete service
curl -X DELETE "https://api.beeoclock.com/api/v1/service/SERVICE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-business-tenant-id: YOUR_TENANT_ID"