Shipping System — Frontend API Reference

Detailed reference for frontend developers integrating with the Admin API.

Scope: Only the Admin API is exposed over HTTP today (/api/admin/*). Shipment, route, and delivery domain models exist in the database and are documented below for context, but those endpoints are not implemented yet.

Table of Contents

1. Quick Start
2. Global Conventions
3. Authentication
4. Profile
5. Admins
6. Roles & Permissions
7. Drivers
8. Vehicles
9. Driver Unavailabilities
10. Driver–Vehicle Assignments
11. Users (Customers)
12. Domain Models Reference
13. Enums Reference
14. Permissions Reference
15. Error Handling
16. Frontend Integration Checklist

Quick Start

POST /api/admin/login
Content-Type: application/json
Accept-Language: en

{
  "email": "mousa@example.com",
  "password": "password"
}

Store the returned JWT and send it on every subsequent request:

GET /api/admin/drivers
Authorization: Bearer {token}
Accept: application/json
Accept-Language: en

Base URL: {APP_URL}/api — e.g. http://localhost:8000/api when running php artisan serve.

Global Conventions

Request Headers

Response Envelope

Every API response uses this structure:

{
  "status": "Success",
  "message": "Data fetched successfully",
  "data": {},
  "statusCode": 200
}

On login success, the JWT is also returned in the Authorization response header as Bearer {token}.

HTTP Methods

Updates use POST, not PUT or PATCH.

All update endpoints follow the pattern POST /api/admin/{resource}/{id}.

Content Types

When using multipart/form-data:

• Send scalar fields as form fields.
• Send working_days as repeated fields or JSON string (array).
• Send roles / permissions as repeated fields or JSON array string.
• Send image as a file field (max 5 MB, must be an image).

Listing, Filtering & Sorting

Most GET list endpoints accept query string parameters:

Query string values "null" and "" are automatically converted to null by middleware.

Pagination

Paginated endpoints (GET .../paginated) wrap results like this:

{
  "drivers": [],
  "total": 50,
  "count": 10,
  "per_page": 10,
  "current_page": 1,
  "total_pages": 5,
  "links": {
    "first": "http://localhost:8000/api/admin/drivers/paginated?page=1",
    "last": "http://localhost:8000/api/admin/drivers/paginated?page=5",
    "prev": null,
    "next": "http://localhost:8000/api/admin/drivers/paginated?page=2"
  }
}

The collection key matches the resource name:

Page size is fixed at 10 per page.

Authentication

All routes under /api/admin/* except POST /login require a valid JWT in the Authorization header.

• Guard: admin
• Library: JWT Auth (tymon/jwt-auth)
• Token TTL: Returned as expires_in (seconds) in login response. Configured via JWT_TTL env (minutes); if unset, token may not expire.

POST /api/admin/login

Authenticate an admin and receive a JWT.

Auth required: No

Request body:

Example request body:

{
  "email": "mousa@example.com",
  "password": "SecurePass123!",
  "fcm_token": "device-fcm-token-abc123"
}

Success response 200:

{
  "status": "Success",
  "message": "User successfully signed in",
  "data": {
    "admin": {
      "id": 1,
      "name": "mousa",
      "email": "mousa@example.com",
      "roles": ["operations_manager"],
      "permission_groups": [
        {
          "group": "Driver",
          "group_label": "Drivers",
          "permissions": [
            {
              "id": 1,
              "name": "ViewAny:Driver",
              "display_name": "View Any",
              "group": "Driver"
            }
          ]
        }
      ]
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
  },
  "statusCode": 200
}

Error responses:

POST /api/admin/logout

Invalidate the current JWT session.

Auth required: Yes

Request body: None

Success response 200:

{
  "status": "Success",
  "message": "User successfully signed out",
  "data": null,
  "statusCode": 200
}

Error responses:

Profile

Manage the currently authenticated admin's own profile. Does not require admin-management permissions.

GET /api/admin/profile

Permission required: None (authentication only)

Success response 200: Returns an AdminResource (see Admins) with:

• is_current_admin: true
• permission_groups included
• roles included

POST /api/admin/profile

Update the authenticated admin's profile.

Permission required: None (authentication only)

Request body (JSON or multipart):

Example request body:

{
  "name": "mousa",
  "email": "mousa.updated@example.com",
  "password": "NewSecurePass123!"
}

Success response 200: Updated AdminResource with message profileUpdatedSuccessfully.

Admins

Back-office user management.

Permission prefix: Admin (e.g. ViewAny:Admin, Create:Admin)

Hidden admin accounts (configured via HIDDEN_ADMIN env) are excluded from listings.

Endpoints

List Query Parameters

Create Request Body

Example request body:

{
  "name": "mousa",
  "email": "mousa@example.com",
  "password": "SecurePass123!",
  "roles": ["operations_manager"]
}

Update Request Body

Same fields as create, all optional (sometimes rules apply). Omit password to keep current password. Send roles: [] to remove all roles.

Example request body:

{
  "name": "mousa",
  "email": "mousa.admin@example.com",
  "roles": ["super_admin"]
}

Admin Resource Shape

{
  "id": 1,
  "name": "mousa",
  "email": "mousa@example.com",
  "image": "http://localhost:8000/storage/1/admin_image.jpg",
  "roles": ["super_admin"],
  "permission_groups": [],
  "is_current_admin": false,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

Delete Constraints

• Cannot delete your own account → 403 with message cannotDeleteCurrentAdmin

Roles & Permissions

Role-based access control using Spatie Permission (guard: admin).

Permission prefixes: Role, Permission

Endpoints

List Query Parameters (roles)

Create Role Request Body

Example request body:

{
  "name": "warehouse_manager",
  "permissions": ["ViewAny:Driver", "Create:Driver", "ViewAny:Vehicle"]
}

Update Role Request Body

Example request body:

{
  "name": "warehouse_manager",
  "permissions": ["ViewAny:Driver", "Update:Driver"]
}

Sync Permissions Request Body

POST /api/admin/roles/{id}/permissions

Example request body:

{
  "permissions": ["ViewAny:Driver", "Create:Driver", "ViewAny:Vehicle", "Create:Vehicle"]
}

Success message: permissionsAssignedSuccessfully

Role Resource Shape

{
  "id": 2,
  "name": "warehouse_manager",
  "guard_name": "admin",
  "permission_groups": [
    {
      "group": "Driver",
      "group_label": "Drivers",
      "permissions": [
        {
          "id": 1,
          "name": "ViewAny:Driver",
          "display_name": "View Any",
          "group": "Driver"
        }
      ]
    }
  ],
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

Permission Group Shape

Used in login, profile, roles, and the permissions list:

{
  "group": "Driver",
  "group_label": "Drivers",
  "permissions": [
    {
      "id": 1,
      "name": "ViewAny:Driver",
      "display_name": "View Any",
      "group": "Driver"
    }
  ]
}

Constraints

• Super admin role cannot be modified or deleted → 403 (cannotModifySuperAdmin)

Drivers

Delivery driver management.

Permission prefix: Driver

Endpoints

List Query Parameters

Sortable columns: name, phone, driver_number, work_start_time, work_end_time, created_at, distance

When lat/lng are provided, results include a distance field (km) and default-sort by nearest first unless sort_by is explicitly set.

Time format: HH:MM:SS or HH:MM (auto-normalized to HH:MM:SS).

Create Request Body

Example request body:

{
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa.driver@example.com",
  "password": "SecurePass123!",
  "address": "Damascus, Syria",
  "license_number": "SY-12345",
  "working_days": ["sun", "mon", "tue", "wed", "thu"],
  "work_start_time": "08:00:00",
  "work_end_time": "17:00:00",
  "lat": 33.5138,
  "lng": 36.2765,
  "is_active": true
}

Update Request Body

Same fields as create. All fields optional except where sometimes + required applies. Password optional (omit to keep current).

Example request body:

{
  "name": "mousa",
  "phone": "944654321",
  "phone_country": "+963",
  "work_start_time": "09:00:00",
  "work_end_time": "18:00:00",
  "is_active": true
}

Driver Resource Shape

{
  "id": 1,
  "driver_number": "482910",
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa.driver@example.com",
  "image": "http://localhost:8000/storage/2/driver_image.jpg",
  "address": "Damascus, Syria",
  "license_number": "DL-12345",
  "working_days": ["sun", "mon", "tue", "wed", "thu"],
  "work_start_time": "08:00:00",
  "work_end_time": "17:00:00",
  "lat": 24.7136,
  "lng": 46.6753,
  "is_active": true,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z",
  "distance": 3.2
}

Vehicles

Fleet vehicle management.

Permission prefix: Vehicle

Endpoints

List Query Parameters

Create Request Body

Example request body:

{
  "plate_number": "DMS-1234",
  "owner_type": "company",
  "max_weight": 1500,
  "max_volume": 12.5
}

Example request body (driver-owned):

{
  "plate_number": "DMS-5678",
  "owner_type": "driver",
  "owner_id": 1,
  "max_weight": 2000,
  "max_volume": 15
}

Update Request Body

Example request body:

{
  "plate_number": "DMS-9999",
  "max_weight": 1800,
  "max_volume": 14,
  "is_active": false
}

Vehicle Resource Shape

{
  "id": 1,
  "plate_number": "ABC-1234",
  "owner_type": "company",
  "owner_type_label": "الشركة",
  "owner_id": null,
  "max_weight": 1500,
  "max_volume": 12.5,
  "is_active": true,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

Driver Unavailabilities

Time-off / unavailability blocks for drivers.

Permission prefix: DriverUnavailability

Endpoints

Also accessible via GET /api/admin/drivers/{id}/unavailabilities.

List Query Parameters

Create Request Body

Example request body:

{
  "driver_id": 1,
  "start_date": "2026-06-01",
  "end_date": "2026-06-05",
  "reason": "Annual leave"
}

Update Request Body

Same fields, all optional. If both dates are provided on update, end_date must still be after start_date.

Example request body:

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-10",
  "reason": "Extended leave"
}

Driver Unavailability Resource Shape

{
  "id": 1,
  "driver_id": 5,
  "start_date": "2026-06-01T00:00:00.000000Z",
  "end_date": "2026-06-05T00:00:00.000000Z",
  "reason": "Annual leave",
  "created_at": "2026-05-20T10:00:00.000000Z",
  "updated_at": "2026-05-20T10:00:00.000000Z"
}

Driver–Vehicle Assignments

Links drivers to vehicles for operational use. A vehicle can only have one active assignment at a time (released_at === null).

Permission prefix: DriverVehicleAssignment

Endpoints

Assign

No request body. Creates a record with:

• assigned_at = current timestamp
• released_at = null

Error: 422 if vehicle already has an active assignment (vehicleAlreadyAssigned)

Unassign

No request body. Sets released_at to current timestamp on the active assignment.

Error: 404 if no active assignment exists (vehicleAssignmentNotFound)

Driver Vehicle Assignment Resource Shape

{
  "id": 1,
  "driver_id": 3,
  "vehicle_id": 7,
  "assigned_at": "2026-06-01T08:00:00.000000Z",
  "released_at": null,
  "vehicle": {
    "id": 7,
    "plate_number": "XYZ-5678",
    "owner_type": "company",
    "owner_type_label": "الشركة",
    "owner_id": null,
    "max_weight": 2000,
    "max_volume": 15,
    "is_active": true,
    "created_at": "...",
    "updated_at": "..."
  },
  "driver": {
    "id": 3,
    "driver_number": "482910",
    "name": "mousa"
  },
  "created_at": "2026-06-01T08:00:00.000000Z",
  "updated_at": "2026-06-01T08:00:00.000000Z"
}

Users (Customers)

End customers who place shipments. These are not admin accounts.

Permission prefix: User

Endpoints

List Query Parameters

Create Request Body

Example request body:

{
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa@example.com",
  "company_name": "Mousa Trading Co."
}

Update Request Body

Same fields, all optional. Phone uniqueness is re-validated when phone or phone_country changes.

Example request body:

{
  "name": "mousa",
  "phone": "944654321",
  "phone_country": "+963",
  "company_name": "Mousa Logistics"
}

User Resource Shape

{
  "id": 1,
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa@example.com",
  "company_name": "Mousa Trading Co.",
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

Domain Models Reference

Currently Exposed via API

Planned Domain (Not Yet in API)

These models exist in the database and will power shipment/route features. No HTTP endpoints exist for them yet.

Shipment (shipments)

Core delivery order placed by a customer.

Relationships:

• user → User
• shipment_items → ShipmentItem[]
• shipment_stops → ShipmentStop[]
• shipment_events → ShipmentEvent[]
• proof_of_deliveries → ProofOfDelivery[]
• failed_deliveries → FailedDelivery[]

ShipmentItem (shipment_items)

Individual items within a shipment.

ShipmentStop (shipment_stops)

Pickup, delivery, or intermediate stops on a shipment route.

ShipmentEvent (shipment_events)

Audit log / timeline entries for a shipment.

Route (routes)

Optimized daily route assigned to a driver and vehicle.

Relationships:

• driver → Driver
• vehicle → Vehicle
• route_stops → RouteStop[]
• route_assignments → RouteAssignment[]

RouteStop (route_stops)

An ordered stop on a driver's route, linked to a shipment stop.

RouteAssignment (route_assignments)

Tracks driver assignment history to a route.

ProofOfDelivery (proof_of_deliveries)

Delivery confirmation record.

FailedDelivery (failed_deliveries)

Record of a failed delivery attempt.

StaticContent (static_contents)

Key-value CMS / app configuration store (not yet in API).

Entity Relationship Diagram (Overview)

User ──< Shipment ──< ShipmentItem
                  ──< ShipmentStop ──< RouteStop >── Route >── Driver
                  ──< ShipmentEvent                  └── Vehicle
                  ──< ProofOfDelivery
                  ──< FailedDelivery

Driver ──< DriverVehicleAssignment >── Vehicle
       ──< DriverUnavailability
       ──< RouteAssignment >── Route

Admin ──< Role ──< Permission

Enums Reference

All enum values are snake_case strings. Store them as string constants in the frontend.

OwnerTypes

Used in API today — vehicle ownership.

API returns both owner_type (value) and owner_type_label (Arabic label).

Suggested TypeScript:

type OwnerType = 'company' | 'driver';

ShipmentStatuses

Planned — shipment lifecycle state.

Typical flow:

draft → pending → assigned → pickup_in_progress → picked_up → at_hub
  → out_for_delivery → delivered
                                    ↘ delivery_failed → returned
Any state → cancelled

ShipmentTypes

ShipmentStopTypes

PaymentTypes

RouteStatuses

RouteStopStatuses

ShipmentEvents

Timeline event types logged on shipments.

MediaTypes

Internal media collection names (used for image uploads).

StaticContentTypes

CMS / app configuration keys (not yet in API).

NotificationTypes

Push notification categories (PHP backed enum).

Working Days (not a PHP enum)

Driver schedule days. Accepted as array values in create/update requests.

Suggested TypeScript:

type WorkingDay = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat';

Permissions Reference

Permissions control what each admin can do. Check them client-side to show/hide UI elements.

Naming Convention

{Action}:{Model}

Examples:

• ViewAny:Driver — can list drivers
• Create:Vehicle — can create vehicles
• Update:Admin — can edit admins
• Delete:Role — can delete roles

Custom Permissions

These do not map to a CRUD model:

How to Check Permissions on Frontend

After login, inspect data.admin.permission_groups:

function hasPermission(
  permissionGroups: PermissionGroup[],
  permissionName: string
): boolean {
  return permissionGroups.some(group =>
    group.permissions.some(p => p.name === permissionName)
  );
}

// Usage
if (hasPermission(admin.permission_groups, 'Create:Driver')) {
  // Show "Add Driver" button
}

Super admin role has all permissions implicitly.

Error Handling

HTTP Status Codes

Common Error Messages

Validation errors return the first validation message as message.

Error Response Shape

{
  "status": "Error",
  "message": "Wrong Credentials",
  "data": null,
  "statusCode": 401
}

Frontend Integration Checklist

• Store JWT from login response (data.token)
• Send Authorization: Bearer {token} on every authenticated request
• Set Accept-Language: en or ar for localized messages
• Use POST for all updates (not PUT/PATCH)
• Use multipart/form-data when uploading image fields
• Gate UI by checking permission_groups from login/profile response
• Handle the standard { status, message, data, statusCode } envelope
• Use paginated endpoints with page query param for tables
• Pass search, sort_by, sort_direction for filterable lists
• For vehicles: enforce owner_id rules based on owner_type
• For drivers: send working_days as array; times as HH:MM or HH:MM:SS
• Shipment/route features: use enums from this doc but wait for backend API routes

Route Index (Quick Reference)

Generated from the shipping_system codebase. Last updated: June 2026.