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

1

Page number for pagination

size

number

10

Number of items per page

phrase

string

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

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

Language Versions: At least one language version is required
Duration Versions: At least one duration version is required
Pricing: Each duration version must have at least one price
Schedules: Schedules are optional but if provided must be valid
Order: Order numbers must be unique within tenant

Service Update Rules

Immutable Fields: Service ID cannot be changed
Language Versions: Cannot remove all language versions
Duration Versions: Cannot remove all duration versions
Active Orders: Cannot delete services with active orders
Media: Media files must be valid image formats

Validation Rules

Duration: Duration must be positive integer in seconds
Price: Price must be positive number
Color: Must be valid hex color code
Schedule Times: Start time must be before end time
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"

PreviousService Management NextInterface Documentation

Last updated 6 months ago

hashtagOverview

hashtagBase URL

hashtagAuthentication

hashtagEndpoints

hashtag1. Get Paged Services

hashtag2. Get Service by ID

hashtag3. Create Service

hashtag4. Update Service

hashtag5. Update Service Required Resources

hashtag6. Delete Service

hashtagService Media Management

hashtagUpload Service Media

hashtagDelete Service Media

hashtagData Transfer Objects

hashtagServiceDto

hashtagServiceConfigurationDto

hashtagDurationConfigurationDto

hashtagPresentationDto

hashtagPrepaymentPolicyDto

hashtagDurationVersionDto

hashtagPriceDto

hashtagEnums

hashtagDurationVersionTypeEnum

hashtagCurrencyCodeEnum

hashtagLanguageCodeEnum

hashtagError Responses

hashtagCommon Error Format

hashtagError Status Codes

hashtagExample Error Responses

hashtagBusiness Rules

hashtagService Creation Rules

hashtagService Update Rules

hashtagValidation Rules

hashtagPermission Requirements

hashtagRate Limiting

hashtagCaching

hashtagIntegration Examples

hashtagJavaScript/TypeScript

hashtagcURL Examples

Overview

Base URL

Authentication

Endpoints

1. Get Paged Services

2. Get Service by ID

3. Create Service

4. Update Service

5. Update Service Required Resources

6. Delete Service

Service Media Management

Upload Service Media

Delete Service Media

Data Transfer Objects

ServiceDto

ServiceConfigurationDto

DurationConfigurationDto

PresentationDto

PrepaymentPolicyDto

DurationVersionDto

PriceDto

Enums

DurationVersionTypeEnum

CurrencyCodeEnum

LanguageCodeEnum

Error Responses

Common Error Format

Error Status Codes

Example Error Responses

Business Rules

Service Creation Rules

Service Update Rules

Validation Rules

Permission Requirements

Rate Limiting

Caching

Integration Examples

JavaScript/TypeScript

cURL Examples