Log in
Documentation / API

API Documentation

Guide 75 Nov 19, 2025

Base information for WEEE Manager API Integration

Base Information

  • Base URL: {APP_URL}/api
  • Authentication: Laravel Sanctum (Token-based)
  • Content Type: application/json
  • Rate Limiting: 60 requests per minute per user/IP

Authentication Endpoints

1. Staff Login


Endpoint: POST /api/staff/login

Description: Authenticates staff members and returns an access token for API usage.

Authentication: None (Public endpoint)

Request Body:

{  "email": "staff@example.com",  "password": "password123"}


Validation Rules:

  • email: Required, must be valid email format
  • password: Required


Success Response (200 OK):

{  "success": true,  "token": "1|AbCdEfGhIjKlMnOpQrStUvWxYz...",  "user": {    "id": 1,    "name": "John Doe",    "email": "staff@example.com",    "role": "staff"  }}


Error Response (401 Unauthorized):

{  "success": false,  "message": "Invalid credentials or inactive account"}


Error Response (500 Internal Server Error):

{  "success": false,  "message": "An error occurred during login",  "error": "Error details..."}


Notes:

  • Only users with role = 'staff' can login through this endpoint
  • Only active users (is_active = 1) can login
  • Token name: staff-mobile-app

2. Get Current User


Endpoint: GET /api/user

Description: Returns the currently authenticated user's information.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json


Success Response (200 OK):

{  "success": true,  "user": {    "id": 1,    "name": "John Doe",    "email": "staff@example.com",    "phone": "+1234567890",    "role": "staff",    "is_active": true,    "is_online": false,    "last_seen": "2025-11-19T10:30:00.000000Z",    "created_at": "2025-01-01T00:00:00.000000Z",    "updated_at": "2025-11-19T10:30:00.000000Z"  }}

3. Staff Logout


Endpoint: POST /api/staff/logout

Description: Revokes the current access token and logs out the user.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json


Success Response (200 OK):

{  "success": true,  "message": "Logged out successfully"}

Waste Note Endpoints

4. Get Waste Note Details


Endpoint: GET /api/waste-notes/{id}

Description: Retrieves detailed information about a specific waste note.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json


URL Parameters:

  • id (integer, required): The waste note ID


Success Response (200 OK):

{  "id": 1,  "custom_id": "CLIENT/19115",  "client_id": 1,  "broker_id": 2,  "location_id": 3,  "fleet_id": 4,  "admin_id": null,  "staff_id": null,  "collection_date": "2025-11-20",  "status": "pending",  "client_name": null,  "signature_path": null,  "staff_signature_path": null,  "admin_signature_path": null,  "on_route_at": null,  "on_site_at": null,  "collected_at": null,  "processing_at": null,  "completed_at": null,  "assigned_at": null,  "waste_collection_bin_id": null,  "created_at": "2025-11-19T10:00:00.000000Z",  "updated_at": "2025-11-19T10:00:00.000000Z",  "client": {    "id": 1,    "client_name": "Client Company Ltd",    "postcode": "AB12 3CD",    ...  },  "broker": {    "id": 2,    "broker_name": "Broker Company",    ...  },  "location": {    "id": 3,    "company_name": "Location Name",    ...  },  "fleet": {    "id": 4,    "make": "Ford",    "model": "Transit",    "registration": "AB12 CDE",    ...  },  "wastes": [    {      "id": 1,      "description": "Electronic Waste",      "ewc": "16 02 14",      "code": "HP4",      "physical": "Solid",      "hazardous": true,      "pivot": {        "quantity": 50,        "container_type": "Drum",        "size": 100,        "unit": "kg",        "quantity_received": null,        "un_identification_numbers": null,        "proper_shipping_names": null,        "un_classes": null,        "packaging_groups": null,        "special_handling_requirements": null,        "ewc_code_status": null,        "waste_management_code": null      }    }  ],  "photos": [...],  "clearance_photos": [...]}


Error Response (404 Not Found):

{  "message": "Waste note not found"}

5. Update Waste Note Status


Endpoint: PATCH /api/waste-notes/{id}

Description: Updates the status of a waste note.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json

Content-Type: application/json


URL Parameters:

  • id (integer, required): The waste note ID


Request Body:

{  "status": "on_route"}


Valid Status Values:

  • pending
  • assigned
  • on_route
  • on_site
  • collected
  • processing
  • received & ready to process
  • Ready for Client Signature
  • ready to be completed
  • completed
  • cancelled


Validation Rules:

  • status: Required, must be one of the valid status values


Success Response (200 OK):

{  "message": "Job status updated successfully",  "waste_note": {    "id": 1,    "status": "on_route",    "on_route_at": "2025-11-19T10:30:00.000000Z",    ...  }}


Notes:

  • Status changes automatically update corresponding timestamp fields
  • Only admins can set processing and completed statuses
  • Staff members can update other statuses for assigned jobs

6. Store Waste Note Photo


Endpoint: POST /api/waste-note-photos

Description: Uploads a photo for a waste note.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json

Content-Type: multipart/form-data


Request Body (multipart/form-data):

waste_note_id: 1

photo: [binary file]


Validation Rules:

  • waste_note_id: Required, must exist in waste_notes table
  • photo: Required, must be an image file, max 100MB


Success Response (200 OK):

{  "success": true,  "message": "Photo uploaded successfully",  "photo": {    "id": 1,    "waste_note_id": 1,    "path": "waste-photos/1/photo_123.jpg",    "original_name": "photo.jpg",    "mime_type": "image/jpeg",    "size": 1024000,    "created_at": "2025-11-19T10:30:00.000000Z"  }}


Note: This endpoint appears to be referenced in the RouteServiceProvider but the actual controller method may need to be implemented. Check WasteNoteController for the storePhoto method.

Staff/Job Management Endpoints

7. Get Staff Jobs


Endpoint: GET /api/staff/jobs

Description: Retrieves all jobs (waste notes) assigned to the authenticated staff member.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json


Success Response (200 OK):

{  "jobs": [    {      "id": 1,      "custom_id": "CLIENT/19115",      "job_type": "waste_note",      "status": "assigned",      "collection_date": "2025-11-20",      "client": {...},      "location": {...},      "assigned_staff": [...]    }  ]}


Note: This endpoint is referenced in the RouteServiceProvider but the getStaffJobs method needs to be implemented in JobController.

8. Update Staff Location


Endpoint: POST /api/staff/location

Description: Updates the current location of the authenticated staff member.

Authentication: Required (Bearer Token)

Headers:

Authorization: Bearer {token}

Accept: application/json

Content-Type: application/json


Request Body:

{  "latitude": 51.5074,  "longitude": -0.1278,  "accuracy": 10}


Expected Response (200 OK):

{  "success": true,  "message": "Location updated successfully"}


Note: This endpoint is referenced in the RouteServiceProvider but the updateLocation method needs to be implemented in StaffController.

Authentication & Authorization

Token Usage


All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer {your_token_here}

Token Acquisition

  1. Call POST /api/staff/login with valid credentials
  2. Extract the token from the response
  3. Use this token in the Authorization header for all subsequent requests

Token Expiration

  • Tokens do not expire by default (expiration: null in config)
  • Tokens are revoked on logout
  • Each user can have multiple active tokens

Role-Based Access

  • Staff Role: Can access assigned jobs and update their own location
  • Admin Role: Has additional permissions for processing and completing waste notes

Error Handling

Common HTTP Status Codes

  • 200 OK: Request successful
  • 401 Unauthorized: Invalid or missing authentication token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Error Response Format

{  "success": false,  "message": "Error message description",  "errors": {    "field_name": ["Validation error message"]  }}

Rate Limiting

  • Limit: 60 requests per minute
  • Scope: Per authenticated user or IP address
  • Header: Rate limit information is included in response headers:
  • X-RateLimit-Limit: Total allowed requests
  • X-RateLimit-Remaining: Remaining requests
  • Retry-After: Seconds until limit resets (when exceeded)

Data Models

User Model

{
  "id": integer,
  "name": string,
  "email": string,
  "phone": string|null,
  "role": "staff"|"admin",
  "is_active": boolean,
  "is_online": boolean,
  "last_seen": datetime|null,
  "created_at": datetime,
  "updated_at": datetime
}

Waste Note Model

{
  "id": integer,
  "custom_id": string,
  "client_id": integer,
  "broker_id": integer|null,
  "location_id": integer,
  "fleet_id": integer,
  "admin_id": integer|null,
  "staff_id": integer|null,
  "collection_date": date|null,
  "status": string,
  "client_name": string|null,
  "signature_path": string|null,
  "staff_signature_path": string|null,
  "admin_signature_path": string|null,
  "on_route_at": datetime|null,
  "on_site_at": datetime|null,
  "collected_at": datetime|null,
  "processing_at": datetime|null,
  "completed_at": datetime|null,
  "assigned_at": datetime|null,
  "waste_collection_bin_id": integer|null,
  "created_at": datetime,
  "updated_at": datetime
}

Waste Model

{
  "id": integer,
  "description": string,
  "ewc": string,
  "code": string,
  "physical": string,
  "hazardous": boolean,
  "pivot": {
    "quantity": numeric,
    "container_type": string|null,
    "size": numeric|null,
    "unit": string|null,
    "quantity_received": numeric|null,
    "un_identification_numbers": string|null,
    "proper_shipping_names": string|null,
    "un_classes": string|null,
    "packaging_groups": string|null,
    "special_handling_requirements": text|null,
    "ewc_code_status": "accepted"|"rejected"|null,
    "waste_management_code": string|null
  }
}

Implementation Notes

Incomplete Endpoints


The following endpoints are defined in the RouteServiceProvider but their controller methods may need implementation:

  1. GET /api/staff/jobs - JobController@getStaffJobs
  2. POST /api/staff/location - StaffController@updateLocation
  3. POST /api/waste-note-photos - WasteNoteController@storePhoto

Security Considerations

  1. All API routes use Sanctum authentication
  2. CSRF protection is disabled for API routes
  3. Rate limiting is enforced at 60 requests/minute
  4. Staff members can only access assigned jobs
  5. Admins have elevated permissions for certain operations

Additional Features

  • Middleware: auth:sanctum for protected routes
  • Throttling: Applied via api middleware group
  • CORS: Handled by Laravel's HandleCors middleware
  • Content Negotiation: All responses are JSON

Testing the API

Using cURL


Login:

curl -X POST http://your-domain.com/api/staff/login \

  -H "Content-Type: application/json" \

  -H "Accept: application/json" \

  -d '{"email":"staff@example.com","password":"password"}'


Get User:

curl -X GET http://your-domain.com/api/user \

  -H "Authorization: Bearer YOUR_TOKEN_HERE" \

  -H "Accept: application/json"


Update Waste Note Status:

curl -X PATCH http://your-domain.com/api/waste-notes/1 \

  -H "Authorization: Bearer YOUR_TOKEN_HERE" \

  -H "Content-Type: application/json" \

  -H "Accept: application/json" \

  -d '{"status":"on_route"}'

Using Postman

  1. Create a new request
  2. Set the method and URL
  3. Add headers:
  • Accept: application/json
  • Authorization: Bearer {token} (for protected endpoints)
  1. Add request body (for POST/PATCH requests)
  2. Send the request

Changelog & Version

  • Current Version: 1.0
  • Last Updated: November 19, 2025
  • Laravel Version: 11.x
  • Sanctum Version: 4.x


This documentation covers all the currently implemented API endpoints for external calls in the WEEE Manager application. The API is designed primarily for a mobile staff application to interact with the waste management system.


Tags: API

Quick Actions

All Documentation Text Guides Video Tutorials