Skip to content

API Reference

Base URL: https://yourdomain.com/api

Authentication

ESP32 endpoints require the X-API-Key header:

X-API-Key: your-secret-api-key

Endpoints

Health Check

GET /api/

Response:

{
  "status": "ok",
  "message": "REward API v1.0"
}

Notifications

Send to Topic

Send push notification to all subscribers of a topic.

POST /api/notify/topic
Content-Type: application/json

Body:

{
  "topic": "all_users",
  "title": "New Announcement 📢",
  "body": "Check out our new features!",
  "data": {
    "type": "announcement"
  }
}

Topics: - all_users - All registered users - offers_updates - Users subscribed to offer notifications

Response:

{
  "success": true,
  "message": "Notification sent to topic: all_users",
  "fcmResponse": { ... }
}

Send to User

Send push notification to a specific user.

POST /api/notify/user
Content-Type: application/json

Body (by userId):

{
  "userId": "abc123",
  "title": "Hello! 👋",
  "body": "This is a personal notification."
}

Body (by FCM token):

{
  "fcmToken": "device_fcm_token",
  "title": "Hello! 👋",
  "body": "This is a personal notification."
}

Kiosk (ESP32)

Get Kiosk Info

GET /api/kiosk/{kioskId}

Response:

{
  "success": true,
  "kiosk": {
    "id": "kiosk001",
    "name": "CIC College Kiosk",
    "address": "New Cairo, Egypt",
    "status": "available",
    "plasticCount": 150,
    "metalCount": 75,
    "lastUpdated": "2024-12-19T22:30:00Z"
  }
}

Update Kiosk Status

POST /api/kiosk/{kioskId}/status
Content-Type: application/json
X-API-Key: your-secret-key

Body:

{
  "status": "available"
}

Status Values: - available - Ready for use - maintenance - Under maintenance - offline - Not operational

Submit Transaction

When user recycles items, ESP32 calls this endpoint.

POST /api/kiosk/transaction
Content-Type: application/json
X-API-Key: your-secret-key

Body:

{
  "kioskId": "kiosk001",
  "userId": "user123",
  "plasticCount": 3,
  "metalCount": 2
}

Response:

{
  "success": true,
  "transaction": {
    "userId": "user123",
    "kioskId": "kiosk001",
    "plasticCount": 3,
    "metalCount": 2,
    "totalItems": 5,
    "pointsEarned": 50,
    "newBalance": 150
  },
  "pushNotification": true
}

What it does: 1. Creates transaction record in Firestore 2. Updates user's points and recycled count 3. Updates kiosk's item counts 4. Creates in-app notification for user 5. Sends push notification to user's device

User

Get User Info

GET /api/user/{userId}

Response:

{
  "success": true,
  "user": {
    "id": "user123",
    "name": "John Doe",
    "currentPoints": 150,
    "totalPoints": 500,
    "recycledCount": 50,
    "rank": "Silver",
    "hasFcmToken": true
  }
}

Error Responses

{
  "error": "Error message here"
}

HTTP Status Codes: - 200 - Success - 400 - Bad request (missing fields) - 401 - Unauthorized (invalid API key) - 404 - Not found - 500 - Server error