Main API

Overview

Main API adalah core business logic service. Menangani manajemen keluarga, relawan, collector, pengumpulan UCO, pickup request, impact tracking, dan CMS.

• REST: Port 8081 (dev) / 8080 (prod)
• Base URL (prod): https://api.waqfuel.com
• Auth: JWT via Authorization: Bearer <token> (validated via JWKS dari auth-api)

Public Endpoints

Health Check

GET /health

Response includes status DB dan gRPC connections.

Impact (Public)

GET /impact/platform                        # Platform-wide impact stats
GET /impact/family/{id}                     # Impact per family (by ID)
GET /impact/family-by-code/{code}           # Impact per family (by public code)
GET /impact-factors                         # List impact factors
GET /impact-factors/{key}/total/global      # Global total per factor
GET /impact-factors/{key}/monthly/global    # Monthly breakdown
GET /impact-factors/{key}/yearly/global     # Yearly breakdown

Landing Page (Public CMS)

GET /landing/hero        # Hero section content
GET /landing/branding    # Branding info
GET /landing/footer      # Footer content

Gallery (Public)

GET /gallery/categories       # List categories
GET /gallery/categories/tree  # Categories as tree
GET /gallery/photos           # Public photos
GET /gallery/photos/recent    # Recent photos

Protected Endpoints

Family Management

POST   /families          # Buat keluarga baru
GET    /families          # List keluarga (filtered by volunteer area)
GET    /families/{id}     # Detail keluarga
PATCH  /families/{id}     # Update keluarga

Request body (create):

{
  "name": "Keluarga Budi",
  "phone": "+628123456789",
  "province": "DKI Jakarta",
  "city": "Jakarta Selatan",
  "district": "Kebayoran Baru",
  "village": "Senayan",
  "rtrw": "RT 003/RW 005"
}

Volunteer Management

POST   /volunteers        # Register volunteer
GET    /volunteers        # List volunteers
GET    /volunteers/{id}   # Detail
PATCH  /volunteers/{id}   # Update service area

Collection Tracking

POST   /collections               # Catat pengumpulan UCO
GET    /collections               # List collections
GET    /collections/unbatched     # Collections belum di-batch
GET    /collections/{id}          # Detail
DELETE /collections/{id}          # Hapus
POST   /collections/upload-url   # Get presigned URL untuk bukti foto

Request body (create):

{
  "family_id": "uuid",
  "liters": 2.5,
  "notes": "Minyak jelantah dari penggorengan"
}

Pickup Requests

Lihat Pickup Request Workflow untuk state machine lengkap.

POST   /pickup-requests                       # Buat draft
GET    /pickup-requests                       # List
GET    /pickup-requests/{id}                  # Detail
PATCH  /pickup-requests/{id}                  # Edit draft
DELETE /pickup-requests/{id}                  # Hapus draft
POST   /pickup-requests/{id}/submit           # Submit
POST   /pickup-requests/{id}/approve          # Approve
POST   /pickup-requests/{id}/reject           # Reject
POST   /pickup-requests/{id}/reopen           # Reopen
POST   /pickup-requests/{id}/mark-picked-up   # Mark picked up
POST   /pickup-requests/{id}/verify           # Verify
POST   /pickup-requests/{id}/complete         # Complete
POST   /pickup-requests/{id}/cancel           # Cancel

Impact Factors (Admin)

GET    /impact-factors/admin          # List (admin view)
POST   /impact-factors                # Create factor
PATCH  /impact-factors/{id}           # Update factor
DELETE /impact-factors/{id}           # Delete factor
GET    /impact-factors/{key}/history  # Audit trail (super_admin)

Admin User Management

GET    /admin/users                           # List all users
POST   /admin/users                           # Create user (invitation flow)
GET    /admin/users/{id}                      # Detail
DELETE /admin/users/{id}                      # Hard delete
PATCH  /admin/users/{id}/testing-flag         # Toggle testing flag
POST   /admin/users/{id}/resend-invitation    # Resend invitation email

Landing CMS (Admin)

GET  /admin/landing/hero          # Get hero
PUT  /admin/landing/hero          # Update hero
GET  /admin/landing/branding      # Get branding
PUT  /admin/landing/branding      # Update branding
GET  /admin/landing/footer        # Get footer
PUT  /admin/landing/footer        # Update footer
POST /admin/landing/upload-url    # Presigned URL for media

Gallery Admin

POST   /admin/gallery/categories       # Create category
PATCH  /admin/gallery/categories/{id}  # Update category
DELETE /admin/gallery/categories/{id}  # Delete category
POST   /admin/gallery/photos           # Add photo
PATCH  /admin/gallery/photos/{id}      # Update photo
DELETE /admin/gallery/photos/{id}      # Delete photo
POST   /admin/gallery/upload-url       # Presigned URL

Role-Based Access

Endpoint Group	volunteer	collector	admin	super_admin
Family CRUD	area-filtered	-	all	all
Collection CRUD	own	-	all	all
Pickup Request	create/submit	mark-picked-up	approve/reject/complete	all
Impact Factors	read	read	CRUD	CRUD + history
Admin Users	-	-	limited	full
Landing CMS	-	-	full	full
Gallery	-	-	full	full