Building Information API Documentation

📋 Data Model

All building records contain the following fields:

Field Name	Type	Required	Description
id_bangunan	string(5)	Yes	5-digit building ID (e.g., "00001")
id_supplier	integer	No	Supplier ID (default: 1002)
kategori_bangunan	string	Yes	Building category ("Pejabat", "Komersil", "Rumah Kedai", "Pasaraya")
tarikh_mula_langganan	string	Yes	Start date (DD/MM/YYYY format)
tarikh_tamat_langganan	string	Yes	End date (DD/MM/YYYY format)
no_telefon	string(20)	Yes	Phone number
nama_untuk_dihubungi	string(255)	Yes	Contact person name
alamat_bangunan	text	Yes	Complete building address
latitude	float	Yes	GPS latitude
longitude	float	Yes	GPS longitude
maklumat_cctv	text	No	CCTV information
risiko_bahaya	text	No	Risk hazards description
aktiviti_premis	text	No	Building activities description
occupy	integer	Yes	Number of occupants
floor_plan	string	No	Floor plan file reference

🔌 API Endpoints

GET /buildings

Retrieve all building records from local database

Response Example:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "id_bangunan": "00001",
      "id_supplier": 1002,
      "kategori_bangunan": "Pejabat",
      "tarikh_mula_langganan": "01/01/2024",
      "tarikh_tamat_langganan": "31/12/2024",
      "no_telefon": "60124424848",
      "nama_untuk_dihubungi": "John Doe",
      "alamat_bangunan": "123 Main Street, Kuala Lumpur",
      "latitude": 3.1390,
      "longitude": 101.6869,
      "maklumat_cctv": "24/7 monitoring system",
      "risiko_bahaya": "None identified",
      "aktiviti_premis": "Government offices",
      "occupy": 150,
      "floor_plan": "00001_floorplan.pdf",
      "created_at": "2024-01-01T10:00:00",
      "updated_at": "2024-01-01T10:00:00"
    }
  ],
  "count": 1
}

GET /buildings/{id_bangunan}

Retrieve a specific building by ID

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID

Response Example:

{
  "success": true,
  "data": {
    "id": 1,
    "id_bangunan": "00001",
    "id_supplier": 1002,
    "kategori_bangunan": "Pejabat",
    ...
  }
}

POST /buildings

Create a new building record

Request Body (JSON):

{
  "id_bangunan": "000002",
  "kategori_bangunan": "Komersil",
  "tarikh_mula_langganan": "01/01/2024",
  "tarikh_tamat_langganan": "31/12/2024",
  "no_telefon": "60123456789",
  "nama_untuk_dihubungi": "Jane Smith",
  "alamat_bangunan": "456 Bank Street, Kuala Lumpur",
  "latitude": 3.1500,
  "longitude": 101.7000,
  "maklumat_cctv": "Advanced security system",
  "risiko_bahaya": "None",
  "aktiviti_premis": "Banking operations",
  "occupy": 200
}

Success Response (201):

{
  "success": true,
  "message": "Building created successfully",
  "data": { ... }
}

PUT /buildings/{id_bangunan}

Update an existing building record

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID

Request Body (JSON) - Include only fields to update:

{
  "nama_untuk_dihubungi": "Updated Contact Person",
  "no_telefon": "60199999999",
  "occupy": 250
}

Success Response (200):

{
  "success": true,
  "message": "Building updated successfully",
  "data": { ... }
}

DELETE /buildings/{id_bangunan}

Delete a building record

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID

Success Response (200):

{
  "success": true,
  "message": "Building deleted successfully"
}

🏢 SPKA KPKTHub Integration

These endpoints integrate with the SPKA Syarikat system via KPKTHub API for premises data management.

SPKA Building API: https://primahub.kpkt.gov.my/api/spka/essence/mind/premis
Authentication: Bearer Token required

POST /spka/sync/{id_bangunan}

Manually sync a specific building to SPKA system

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID to sync

Success Response (200):

{
  "success": true,
  "message": "Building successfully synced to SPKA system",
  "spka_response": { ... }
}

GET /spka/fetch/{id_bangunan}

Fetch building data from SPKA system

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID to fetch

Success Response (200):

{
  "success": true,
  "message": "Building data fetched from SPKA system",
  "spka_data": { ... }
}

POST /spka/sync-all

Sync all local buildings to SPKA system (bulk operation)

Success Response (200):

{
  "success": true,
  "message": "Bulk sync completed",
  "results": {
    "total": 5,
    "successful": 4,
    "failed": 1,
    "errors": [
      {
        "id_bangunan": "000005",
        "error": "SPKA API Error: 400 - Invalid data"
      }
    ]
  }
}

📝 Usage Examples

SPKA Integration Examples:

# Sync single building to SPKA
curl -X POST https://jages.org/kpkt/api/spka/sync/00001

# Fetch building from SPKA
curl -X GET https://jages.org/kpkt/api/spka/fetch/00001

# Bulk sync all buildings to SPKA
curl -X POST https://jages.org/kpkt/api/spka/sync-all

Using cURL:

# Get all buildings
curl -X GET https://jages.org/kpkt/api/buildings

# Get specific building
curl -X GET https://jages.org/kpkt/api/buildings/00001

# Create new building
curl -X POST https://jages.org/kpkt/api/buildings \
  -H "Content-Type: application/json" \
  -d '{
    "id_bangunan": "000003",
    "kategori_bangunan": "Rumah Kedai",
    "tarikh_mula_langganan": "01/01/2024",
    "tarikh_tamat_langganan": "31/12/2024",
    "no_telefon": "60123456789",
    "nama_untuk_dihubungi": "Test User",
    "alamat_bangunan": "Test Address",
    "latitude": 3.1390,
    "longitude": 101.6869,
    "occupy": 100
  }'

# Update building
curl -X PUT https://jages.org/kpkt/api/buildings/000003 \
  -H "Content-Type: application/json" \
  -d '{"occupy": 150}'

# Delete building
curl -X DELETE https://jages.org/kpkt/api/buildings/000003

Using JavaScript (Fetch API):

// Get all buildings
fetch('/api/buildings')
  .then(response => response.json())
  .then(data => console.log(data));

// Create new building
fetch('/api/buildings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id_bangunan: '000004',
    kategori_bangunan: 'Pasaraya',
    tarikh_mula_langganan: '01/01/2024',
    tarikh_tamat_langganan: '31/12/2024',
    no_telefon: '60123456789',
    nama_untuk_dihubungi: 'JavaScript User',
    alamat_bangunan: 'JavaScript Address',
    latitude: 3.1390,
    longitude: 101.6869,
    occupy: 75
  })
})
.then(response => response.json())
.then(data => console.log(data));

🔄 SPKA Sync Endpoints

These endpoints manage synchronization with the SPKA KPKTHub API system.

POST /sync-buildings

Sync all building records to SPKA KPKTHub API

Response Example:

{
  "success": true,
  "message": "Buildings sync completed",
  "results": {
    "successful": 3,
    "failed": 0,
    "details": [
      {
        "id_bangunan": "00001",
        "status": "success",
        "spka_response": "Premises data received"
      }
    ]
  }
}

POST /sync-building/{id_bangunan}

Sync a specific building to SPKA KPKTHub API

Path Parameters:

Parameter	Type	Description
id_bangunan	string	6-digit building ID to sync

⚙️ Configuration

The system uses spka_config.py for API configuration including endpoints, authentication tokens, and data mappings.

Features:

🔒 Secure token-based authentication for SPKA APIs
🌐 Primary and secondary API endpoints for failover
🗺️ Field mapping for data transformation
📊 Comprehensive error handling and logging
🔄 Automatic sync on data creation

⚠️ Error Handling

All endpoints return standardized error responses:

{
  "success": false,
  "error": "Error message description"
}

HTTP Status Codes:

Code	Description
200	Success
201	Created
400	Bad Request (validation error)
404	Not Found
500	Internal Server Error