API Documentation

Overview

The Business Profile Management API provides endpoints for managing business information, settings, and configuration within the Bee O'clock platform. This API allows businesses to create, update, and retrieve their complete business profile including basic information, media assets, settings configurations, and operational parameters.

Base URL

/api/v1/business-profile

Authentication

All endpoints require:

• Bearer Token: JWT authentication token

• Business-Tenant-Id: Header specifying the business tenant ID

API Endpoints

1. Get Business Profile

Endpoint: GET /

Description: Retrieves the complete business profile for the authenticated tenant.

Response: BusinessProfileDto

Permissions Required: READ_BUSINESS_PROFILE

Response Structure:

{
  _id: string;
  object: 'BusinessProfileDto';
  published: ActiveEnum;
  name: string;
  username?: string;
  description?: string;
  feature?: string;
  facilities?: FacilityEnum[];
  logo?: MediaDto;
  banners?: MediaDto[];
  gallery?: MediaDto[];
  addresses?: AddressDto[];
  contacts?: ContactDto[];
  schedules?: ScheduleDto[];
  specialSchedules?: SpecialScheduleDto[];
  socialNetworkLinks?: SocialNetworkLinkDto[];
  bookingSettings?: BookingSettingsClientDto;
  businessSettings?: BusinessSettingsDto;
  paymentSettings?: PaymentSettingsDto;
  panelSettings?: PanelSettingsDto;
  publicPageSettings?: PublicPageSettingsDto;
  notificationSettings?: NotificationSettingsDto;
  businessTariffPlanType?: BusinessTariffPlanType;
  createdAt?: string;
  updatedAt?: string;
}

---

2. Update Business Profile

Endpoint: PUT /

Description: Updates the complete business profile with the provided data.

Request Body: BusinessProfileDto (complete object)

Response: BusinessProfileDto (updated profile)

Permissions Required: EDIT_BUSINESS_PROFILE

Validation Rules:

• name: Required for business identification

• published: Must be ActiveEnum value (YES/NO)

• Nested objects must pass their respective validation rules

• Media references must exist in the system

---

3. Update Payment Settings

Endpoint: PATCH /payment-settings

Description: Updates only the payment settings portion of the business profile.

Request Body: PaymentSettingsDto

Response: PaymentSettingsDto (updated payment settings)

Permissions Required: EDIT_BUSINESS_PROFILE

Payment Settings Structure:

{
  stripeSettings?: StripeSettingsDto;
  paypalSettings?: PaypalSettingsDto;
  squareSettings?: SquareSettingsDto;
  defaultPaymentMethod?: PaymentMethodEnum;
  acceptedPaymentMethods?: PaymentMethodEnum[];
  currencySettings?: CurrencySettingsDto;
  taxSettings?: TaxSettingsDto;
}

---

Business Profile Media API

Base URL for Media Operations

/api/v1/business-profile-media

4. Update Business Logo

Endpoint: PATCH /logo

Description: Updates the business logo image.

Request: Multipart form data with image file

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

Content Type: multipart/form-data

File Requirements:

• Supported formats: JPEG, PNG, WebP

• Maximum file size: 5MB

• Recommended dimensions: 200x200px (square)

---

5. Delete Business Logo

Endpoint: DELETE /logo

Description: Removes the current business logo.

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

---

6. Update Banner Item

Endpoint: PATCH /banner/:bannerItemId

Description: Updates a specific banner image.

Path Parameters:

• bannerItemId (string): The ID of the banner item to update

Request: Multipart form data with image file

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

File Requirements:

• Supported formats: JPEG, PNG, WebP

• Maximum file size: 10MB

• Recommended dimensions: 1200x400px (landscape)

---

7. Delete Banner Item

Endpoint: DELETE /banner/:bannerItemId

Description: Removes a specific banner image.

Path Parameters:

• bannerItemId (string): The ID of the banner item to delete

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

---

8. Update Gallery Item

Endpoint: PATCH /gallery/:galleryItemId

Description: Updates a specific gallery image.

Path Parameters:

• galleryItemId (string): The ID of the gallery item to update

Request: Multipart form data with image file

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

File Requirements:

• Supported formats: JPEG, PNG, WebP

• Maximum file size: 8MB

• Recommended dimensions: Variable (maintains aspect ratio)

---

9. Delete Gallery Item

Endpoint: DELETE /gallery/:galleryItemId

Description: Removes a specific gallery image.

Path Parameters:

• galleryItemId (string): The ID of the gallery item to delete

Response: void

Permissions Required: EDIT_BUSINESS_PROFILE

---

Data Transfer Objects

BusinessProfileDto

The main DTO containing all business profile information:

{
  _id?: string;
  object?: 'BusinessProfileDto';
  published?: ActiveEnum;           // YES | NO
  name?: string;                   // Business name
  username?: string;               // Unique username/handle
  description?: string;            // Business description
  feature?: string;                // Featured information
  facilities?: FacilityEnum[];     // Business facilities
  logo?: MediaDto;                 // Logo image
  banners?: MediaDto[];           // Banner images
  gallery?: MediaDto[];           // Gallery images
  addresses?: AddressDto[];       // Business addresses
  contacts?: ContactDto[];        // Contact information
  schedules?: ScheduleDto[];      // Operating schedules
  specialSchedules?: SpecialScheduleDto[]; // Special schedules
  socialNetworkLinks?: SocialNetworkLinkDto[]; // Social media links
  bookingSettings?: BookingSettingsClientDto; // Booking configuration
  businessSettings?: BusinessSettingsDto;     // Business configuration
  paymentSettings?: PaymentSettingsDto;       // Payment configuration
  panelSettings?: PanelSettingsDto;          // Panel UI settings
  publicPageSettings?: PublicPageSettingsDto; // Public page settings
  notificationSettings?: NotificationSettingsDto; // Notification settings
  businessTariffPlanType?: BusinessTariffPlanType; // Subscription plan
  createdAt?: string;
  updatedAt?: string;
}

Key Nested DTOs

AddressDto

{
  _id?: string;
  street: string;
  city: string;
  state?: string;
  zipCode?: string;
  country: string;
  coordinates?: {
    latitude: number;
    longitude: number;
  };
  isPrimary?: boolean;
}

ContactDto

{
  _id?: string;
  type: ContactTypeEnum;    // PHONE | EMAIL | WEBSITE
  value: string;
  label?: string;
  isPrimary?: boolean;
}

ScheduleDto

{
  dayOfWeek: DayOfWeekEnum;
  isOpen: boolean;
  openTime?: string;        // HH:mm format
  closeTime?: string;       // HH:mm format
  breaks?: BreakDto[];
}

ActiveEnum

enum ActiveEnum {
  NO = 0,
  YES = 1
}

FacilityEnum

enum FacilityEnum {
  PARKING = 'PARKING',
  WIFI = 'WIFI',
  ACCESSIBILITY = 'ACCESSIBILITY',
  CARD_PAYMENT = 'CARD_PAYMENT',
  CASH_PAYMENT = 'CASH_PAYMENT',
  APPOINTMENT_ONLY = 'APPOINTMENT_ONLY',
  WALK_INS_WELCOME = 'WALK_INS_WELCOME'
}

Error Responses

Common HTTP Status Codes

• 400 Bad Request: Invalid request data or validation errors

• 401 Unauthorized: Missing or invalid authentication token

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Business profile not found

• 413 Payload Too Large: File upload exceeds size limits

• 415 Unsupported Media Type: Invalid file format for media uploads

• 500 Internal Server Error: Server-side processing error

Error Response Format

{
  statusCode: number;
  message: string | string[];
  error?: string;
}

Permission System

The business profile management system uses a role-based permission system:

• READ_BUSINESS_PROFILE: View business profile information

• EDIT_BUSINESS_PROFILE: Modify business profile information

Permission Enforcement

• All endpoints require appropriate permissions

• Media upload/delete operations require EDIT permissions

• Profile visibility is controlled by the published field

Business Rules

📝 Profile Validation

1. Name Requirement: Business name is required for profile creation

2. Publication Control: Only published profiles are visible to clients

3. Media Limits: Maximum file sizes enforced for different media types

4. Format Restrictions: Only supported image formats allowed for media

🖼️ Media Management

1. Logo Requirements: Square format recommended, single logo per business

2. Banner Specifications: Landscape format for promotional banners

3. Gallery Flexibility: Multiple images with preserved aspect ratios

4. Automatic Cleanup: Orphaned media files are cleaned up periodically

⚙️ Settings Hierarchy

1. Business Settings: Core operational parameters

2. Booking Settings: Customer booking configuration

3. Payment Settings: Financial transaction setup

4. Notification Settings: Communication preferences

5. Panel Settings: Administrative interface customization

Integration Points

• Media Service: File upload and management

• Identity Service: User authentication and authorization

• Notification Service: Settings synchronization

• Payment Service: Payment gateway configuration

• Cache Service: Performance optimization

Rate Limiting

Standard API rate limiting applies to all endpoints:

• GET requests: 100 requests per minute

• PUT/PATCH requests: 20 requests per minute

• Media uploads: 10 requests per minute

Examples

Get Business Profile

GET /api/v1/business-profile
Authorization: Bearer <jwt-token>
Business-Tenant-Id: <tenant-id>

Response:
{
  "_id": "64f7b1234567890abcdef123",
  "object": "BusinessProfileDto",
  "published": 1,
  "name": "Bella Vista Salon",
  "username": "bellavista",
  "description": "Premium hair and beauty services",
  "addresses": [
    {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA",
      "isPrimary": true
    }
  ],
  "bookingSettings": {
    "autoBookOrder": true,
    "earliestBooking": 24,
    "latestBooking": 4320
  }
}

Update Business Profile

PUT /api/v1/business-profile
Authorization: Bearer <jwt-token>
Business-Tenant-Id: <tenant-id>
Content-Type: application/json

{
  "name": "Bella Vista Spa & Salon",
  "description": "Premium hair, beauty, and spa services",
  "facilities": ["PARKING", "WIFI", "CARD_PAYMENT"],
  "addresses": [
    {
      "street": "123 Main Street",
      "city": "New York", 
      "state": "NY",
      "zipCode": "10001",
      "country": "USA",
      "isPrimary": true
    }
  ]
}

Update Payment Settings

PATCH /api/v1/business-profile/payment-settings
Authorization: Bearer <jwt-token>
Business-Tenant-Id: <tenant-id>
Content-Type: application/json

{
  "defaultPaymentMethod": "STRIPE",
  "acceptedPaymentMethods": ["STRIPE", "PAYPAL", "CASH"],
  "stripeSettings": {
    "publishableKey": "pk_test_...",
    "webhookSecret": "whsec_..."
  }
}

Upload Business Logo

PATCH /api/v1/business-profile-media/logo
Authorization: Bearer <jwt-token>
Business-Tenant-Id: <tenant-id>
Content-Type: multipart/form-data

Form Data:
- file: [image file]