moegoapis

Block API Documentation (moego.business.block.v1)

📌 1. Functional Overview

Block represents a time period that is blocked off in a staff member’s schedule. This module provides the following functions:

Applicable to scenarios such as staff scheduling, calendar management, and availability tracking.

🎯 2. Design Goals

🧩 3. Core Concepts

1. Block

Represents a time period that is blocked off in a staff member’s schedule. This can be used for breaks, meetings, or any other time when the staff member is not available for appointments.

Field Name Type Description
id string Unique identifier for the block
staffId string ID of the staff member whose schedule is being blocked
duration google.type.Interval The time interval during which the staff member is unavailable (uses Google’s standard Interval type to represent start and end times)
description string Optional description of why the time is blocked off (e.g., “Lunch break”, “Team meeting”)
colorCode string Color code used to visually distinguish this block in the calendar UI (should be a valid hex color code like “#FF0000” for red)
businessId string ID of the business where this block is created (used for access control and filtering blocks by business)

📈 4. Typical Usage Flow

✅ Scenario: User integrates and debugs the Block API

Here is a typical integration flow:

  1. CreateBlock
    • Define a new block with specific duration for a staff member
    • Set an optional description explaining why the time is blocked
    • Assign a color code for visual distinction in the calendar UI
  2. GetBlock
    • Retrieve detailed information about a specific block using its unique ID
    • Verify block configuration and check time conflicts
  3. Schedule Management & Monitoring
    • Regularly create and update blocks to manage staff availability
    • Use blocks to prevent scheduling conflicts
    • Monitor staff schedules across multiple business locations

📦 5. API Interface Descriptions

1. CreateBlock (CreateBlock)

✅ Functionality:

Creates a new block in a staff member’s schedule.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
businessId string Yes Company identifier for scoping the block creation
staffId string Yes ID of the staff member whose schedule will be blocked
duration Interval Yes Time interval during which the staff member will be unavailable (must have both start and end times specified)
description string No Optional description explaining why the time is being blocked off (examples: “Lunch break”, “Team meeting”, “Training session”)
colorCode string No Optional color code for visual distinction in the calendar UI (should be a valid hex color code like “#FF0000” for red)

📌 Return Value:

Field Name Type Description
id string Unique identifier for the block
staffId string ID of the staff member whose schedule is being blocked
duration google.type.Interval The time interval during which the staff member is unavailable (uses Google’s standard Interval type to represent start and end times)
description string Optional description of why the time is blocked off (e.g., “Lunch break”, “Team meeting”)
colorCode string Color code used to visually distinguish this block in the calendar UI (should be a valid hex color code like “#FF0000” for red)
businessId string ID of the business where this block is created (used for access control and filtering blocks by business)

⚠️ Error Codes:

2. GetBlock (GetBlock)

✅ Functionality:

Retrieves detailed information about a specific block by its ID.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
id string Yes Unique identifier of the block to retrieve

📌 Return Value:

Field Name Type Description
id string Unique identifier for the block
staffId string ID of the staff member whose schedule is being blocked
duration google.type.Interval The time interval during which the staff member is unavailable (uses Google’s standard Interval type to represent start and end times)
description string Optional description of why the time is blocked off (e.g., “Lunch break”, “Team meeting”)
colorCode string Color code used to visually distinguish this block in the calendar UI (should be a valid hex color code like “#FF0000” for red)
businessId string ID of the business where this block is created (used for access control and filtering blocks by business)

⚠️ Error Codes:

3. ListBlocks (ListBlocks)

✅ Functionality:

Retrieves a list of blocks based on the provided filter criteria.

🎯 Use Cases:

🔧 Request Parameters:

Field Name Type Required Description
pagination object Yes Pagination parameters including page_size (max 500) and optional page_token for next page
companyId string Yes Company identifier for multi-location businesses
businessIds []string Yes List of business location IDs to include in the search
filter object No Optional filter criteria
filter.startTime google.type.Interval No Filter by blocks start time range
filter.endTime google.type.Interval No Filter by blocks end time range

📌 Return Value:

Field Name Type Description
blocks []Block List of blocks matching the filter criteria
nextPageToken string Token for retrieving the next page of results; empty if there are no more results

⚠️ Error Codes:

🧪 6. Usage Examples

Example 1: CreateBlock

{
  "businessId": "biz_001",
  "staffId": "staff_001",
  "duration": {
    "startTime": "2024-09-15T12:00:00Z",
    "endTime": "2024-09-15T13:00:00Z"
  },
  "description": "Lunch break",
  "colorCode": "#FFA500"
}

Example 2: GetBlock

{
  "id": "block_001"
}

⚠️ 7. Usage Limitations

TODO

📎 8. FAQ

Question Answer
How to verify if a block exists? Use GetBlock to check if the block ID returns a valid response
Can I create overlapping blocks? While technically possible, it’s recommended to avoid creating overlapping blocks for the same staff member
How to manage staff availability effectively? Use CreateBlock to define all unavailable time periods and check them before scheduling appointments
Why does creating a block return “permission denied”? You may lack the necessary permissions for the specified business ID or staff member
How to handle time zone differences? All times should be specified in UTC format with proper time zone conversion handled at the application level

📌 9. Common Error Codes

Error Code Description
NOT_FOUND Block ID, business ID, or staff ID does not exist
PERMISSION_DENIED Current user has no access rights
INVALID_ARGUMENT Invalid request parameters
INTERNAL Internal server error

📎 10. Related File References