> For the complete documentation index, see [llms.txt](https://docs.beeoclock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beeoclock.com/services/business-profile/api.md).

# 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:**

```typescript
{
  _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:**

```typescript
{
  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:

```typescript
{
  _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

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

#### ContactDto

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

#### ScheduleDto

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

### ActiveEnum

```typescript
enum ActiveEnum {
  NO = 0,
  YES = 1
}
```

### FacilityEnum

```typescript
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

```typescript
{
  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

```javascript
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

```javascript
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

```javascript
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

```javascript
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]
```