Providers & Resources API

Provider management and resource (hotels, buses, rest stops) endpoints

1. Purpose

This API group manages all B2B provider–related resources:

Provider companies (شركات السياحة)
Buses (الباصات)
Hotels (الفنادق)
Rest stops (الاستراحات)
Provider staff accounts

These APIs back the Provider Portal UI and partially the Admin Panel, and must stay consistent with the domain model and functional specs.

2. Provider Company API

All provider company endpoints are Admin-only and protected by appropriate RBAC.

2.1 List Providers (Admin only)

GET/api/v1/admin/providers

Parameter	Description
search	Optional free-text search (name, email, phone)
status	ACTIVE \| INACTIVE

2.2 Get Provider Details (Admin only)

GET/api/v1/admin/providers/{id}

Returns provider master data plus high-level stats for dashboard cards.

2.3 Create Provider (Admin only)

POST/api/v1/admin/providers

2.4 Update Provider (Admin only)

PUT/api/v1/admin/providers/{id}

Updates provider master data.

2.5 Activate / Deactivate Provider (Admin only)

POSTPOST /api/v1/admin/providers/{id}/activate

POSTPOST /api/v1/admin/providers/{id}/deactivate

Toggles provider status between ACTIVE and INACTIVE. When INACTIVE, all related provider resources (Trips / Buses / Hotels / Rest Stops) become unlisted in B2C Web & Mobile.

3. Provider Staff Accounts (Admin only)

3.1 Create Staff Account

POST/api/v1/admin/providers/{provider_id}/staff

Creates a staff account scoped to a specific provider. The role must match allowed provider roles per RBAC.

3.2 List Provider Staff

GET/api/v1/admin/providers/{id}/staff

Lists all staff accounts for the given provider.

4. Buses API

Matches "قائمة الباصات" + modal "إضافة باص جديد" in the Provider Portal.

4.1 List Buses (Provider)

GET/api/v1/provider/buses

Auth: Provider Admin / Provider Staff. Results are always scoped to the authenticated provider.

Parameter	Description
status	ACTIVE \| INACTIVE \| UNDER_MAINTENANCE
search	Free-text (plate number, model, driver name)

4.2 Create Bus (Provider)

POST/api/v1/provider/buses

Fails if plate_number already exists for this provider
Driver information is embedded in the bus entity (no standalone drivers resource in this phase)
File uploads for photos are handled via multipart/form-data

4.3 Update Bus

PUT/api/v1/provider/buses/{id}

Updates bus details (including embedded driver info and features). Must respect soft-delete and provider scoping rules.

4.4 Delete Bus

DELETE/api/v1/provider/buses/{id}

Soft-deletes a bus. The UI shows the "حذف الباص!" confirmation modal before calling this endpoint.

5. Hotels API

Matches "قائمة الفنادق" + modal "إضافة فندق جديد".

5.1 List Hotels (Provider)

GET/api/v1/provider/hotels

Auth: Provider Admin / Provider Staff

5.2 Create Hotel (Provider)

POST/api/v1/provider/hotels

5.3 Update & Delete Hotel

PUT /api/v1/provider/hotels/{id}DELETE /api/v1/provider/hotels/{id}

Updates or soft-deletes hotel records; deleted hotels should not appear in trip creation UIs.

6. Rest Stops API

Matches "قائمة الاستراحات" + modal "إضافة استراحة جديدة".

6.1 List Rest Stops (Provider)

GET/api/v1/provider/rest-stops

6.2 Create Rest Stop (Provider)

POST/api/v1/provider/rest-stops

6.3 Update & Delete Rest Stop

PUT /api/v1/provider/rest-stops/{id}DELETE /api/v1/provider/rest-stops/{id}

Updates or soft-deletes rest stops; deleted rest stops should not appear in trip composition screens.

7. Cross-Relations & Constraints

CR-1Provider Visibility Constraint

If provider status = INACTIVE, then all provider resources (Trips / Buses / Hotels / Rest Stops) become unlisted in B2C Web & Mobile. Admin still retains visibility via Admin endpoints.

CR-2Trip Composition Consistency

A trip references: One hotel (mandatory for non-Umrah trips), One bus (from the same provider), Assigned driver (via embedded driver info in the bus), Multiple rest stops (optional, but must belong to the same provider). Provider cannot reference resources belonging to a different provider.

CR-3Soft Delete

All provider resources use soft-delete. Soft-deleted buses/hotels/rest-stops must not appear in trip creation/editing screens or provider resource lists.

8. Error Cases

EC-1Duplicate Plate Number

If provider adds a bus with an existing plate_number (for this provider):

BUS_PLATE_ALREADY_EXISTS

EC-2Invalid Hotel Stars

stars must be within {1,2,3,4,5,6,7}. UI currently shows support for 6–7 stars; business confirmation is still required.

EC-3Missing Mandatory Fields

Requests missing mandatory fields (especially name, city, status) must return standard validation errors.

9. Permissions Summary (High-Level)

Endpoint Group	Provider Admin	Provider Staff	Admin	Super Admin
Providers CRUD	❌	❌	✔️	✔️
Staff accounts	❌	❌	✔️	✔️
Buses CRUD	✔️	✔️	✔️	✔️
Hotels CRUD	✔️	✔️	✔️	✔️
Rest stops CRUD	✔️	✔️	✔️	✔️
Cross-provider read	❌	❌	✔️	✔️

Full matrix in 08-rbac/roles-and-permissions-matrix.md