API Documentation

Overview

The Absence Management API provides endpoints for managing staff absences within the Bee O'clock platform. This API allows businesses to create, update, retrieve, and delete absence records for their members, with support for both individual member absences and business-wide closures.

Base URL

/api/v1/absence

Authentication

All endpoints require:

• Bearer Token: JWT authentication token

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

API Endpoints

1. Get Paginated Absences

Endpoint: GET /paged

Description: Retrieves a paginated list of absences for the authenticated tenant.

Query Parameters:

• page (number, optional): Page number (default: 1)

• pageSize (number, optional): Number of items per page (default: 10)

• Additional pagination parameters from AbsencePaginationDto

Response:

{
  items: AbsenceDto[],
  totalSize: number,
  page: number,
  pageSize: number
}

Permissions Required: READ_ABSENCE

Access Control:

• Users with OWN scope can only see their own absences

• Users with ANY scope can see all absences

• Business-wide absences are visible to all authorized users

---

2. Get Absence by ID

Endpoint: GET /:id

Description: Retrieves a specific absence by its ID.

Path Parameters:

• id (string): The unique identifier of the absence

Response: AbsenceDto

Permissions Required: READ_ABSENCE

Access Control:

• Users can only access absences they are assigned to or business-wide absences

• Returns null if absence not found or access denied

---

3. Create Absence

Endpoint: POST /

Description: Creates a new absence record.

Request Body: AbsenceDto

Required Fields:

• start: Start date/time (ISO string)

• end: End date/time (ISO string)

• type: Absence type (vacation, holiday, break)

• timeZone: Timezone identifier

Optional Fields:

• note: Description or notes about the absence

• entireBusiness: Boolean indicating if this affects the entire business

• members: Array of member IDs affected (required if not entireBusiness)

• locations: Array of affected locations

Response: void (201 Created)

Permissions Required: CREATE_ABSENCE

Validation Rules:

• End date must be after start date

• Must specify either entireBusiness: true or at least one member

• Users with OWN scope can only create absences for themselves

---

4. Update Absence

Endpoint: PUT /:id

Description: Updates an existing absence record.

Path Parameters:

• id (string): The unique identifier of the absence

Request Body: AbsenceDto (complete object with _id field)

Response: void (200 OK)

Permissions Required: EDIT_ABSENCE

Access Control:

• Users can only update absences they have access to

• Business-wide absences require appropriate permissions

---

5. Delete Absence

Endpoint: DELETE /:id

Description: Soft deletes an absence record by updating its state history.

Path Parameters:

• id (string): The unique identifier of the absence

Response: void (200 OK)

Permissions Required: DELETE_ABSENCE

Access Control:

• Users can only delete absences they have access to

• Performs soft delete by updating state history to 'deleted'

Data Transfer Objects

AbsenceDto

{
  _id?: string;
  object?: 'AbsenceDto';
  note?: string;
  start: string;           // ISO date string
  end: string;             // ISO date string
  type?: AbsenceTypeEnum;  // 'vacation' | 'holiday' | 'break'
  entireBusiness?: boolean;
  members?: MemberDto[];
  locations?: LocationDto[];
  timeZone?: string;
  meta?: MetaDto;
  createdAt?: string;
  updatedAt?: string;
}

AbsenceTypeEnum

enum AbsenceTypeEnum {
  vacation = 'vacation',
  holiday = 'holiday',
  break = 'break'
}

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: Absence not found or access denied

• 500 Internal Server Error: Server-side processing error

Error Response Format

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

Permission System

The absence management system uses a role-based permission system with the following permissions:

• READ_ABSENCE: View absence records

• CREATE_ABSENCE: Create new absence records

• EDIT_ABSENCE: Modify existing absence records

• DELETE_ABSENCE: Delete absence records

Permission Scopes

• OWN: User can only manage their own absences

• ANY: User can manage any absences within their tenant

Business Rules

1. Date Validation: End date must be greater than start date

2. Assignment Validation: Must specify either entireBusiness: true or at least one member

3. Permission Enforcement: Users can only manage absences they have permission to access

4. Soft Deletion: Absences are not physically deleted but marked as deleted in state history

5. Timezone Support: All dates are stored with timezone information

6. Business-wide Impact: Setting entireBusiness: true affects all operations regardless of member assignments

Integration Points

• Message Queue: Publishes events for absence creation, updates, and deletions

• WebSocket: Real-time notifications sent to connected clients

• Cache: Automatic cache invalidation for affected queries

• Audit Trail: State history tracking for all changes

Rate Limiting

Standard API rate limiting applies to all endpoints. Refer to the main API documentation for specific limits.

Examples

Create a Personal Absence

POST /api/v1/absence
{
  "start": "2024-12-25T09:00:00.000Z",
  "end": "2024-12-25T17:00:00.000Z",
  "type": "vacation",
  "note": "Christmas vacation",
  "timeZone": "America/New_York",
  "members": [
    { "_id": "member-id-123" }
  ]
}

Create a Business-wide Closure

POST /api/v1/absence
{
  "start": "2024-12-25T00:00:00.000Z",
  "end": "2024-12-25T23:59:59.000Z",
  "type": "holiday",
  "note": "Christmas Day - Business Closed",
  "timeZone": "America/New_York",
  "entireBusiness": true
}