Panduan Lengkap: Dokumentasi API Texa Bot untuk Manajemen Pesanan
# 📚 API Documentation - Texa Bot Database API
Complete REST API documentation for order management system.
## 🌐 Base URL
```
http://localhost:3000/api
```
---
## 📋 Table of Contents
1. [Authentication](#authentication)
2. [Health Check](#health-check)
3. [Orders](#orders)
4. [Search](#search)
5. [Statistics](#statistics)
6. [Import](#import)
7. [Export](#export)
8. [Error Handling](#error-handling)
---
## 🔐 Authentication
Currently, the API does not require authentication. For production use, implement JWT or API key authentication.
---
## 🏥 Health Check
### Check API Status
```http
GET /api/health
```
**Response**
```json
{
"status": "OK",
"message": "API Server is running",
"timestamp": "2025-09-30T10:30:00.000Z"
}
```
---
## 📦 Orders
### Get All Orders
Retrieve orders with optional filtering.
```http
GET /api/orders
```
**Query Parameters**
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `limit` | integer | Max results (default: 50) | `limit=100` |
| `no_pesanan` | string | Filter by order number | `no_pesanan=25070105` |
| `username` | string | Filter by username | `username=ifandi94` |
| `nama_produk` | string | Filter by product name | `nama_produk=helm` |
| `provinsi` | string | Filter by province | `provinsi=jakarta` |
| `kota` | string | Filter by city | `kota=bengkulu` |
| `status` | string | Filter by status | `status=Selesai` |
| `no_resi` | string | Filter by tracking number | `no_resi=SPX123` |
**Example Request**
```bash
curl "http://localhost:3000/api/orders?limit=10&status=Selesai&provinsi=jakarta"
```
**Response**
```json
{
"success": true,
"count": 10,
"filters": {
"limit": 10,
"status": "Selesai",
"provinsi": "jakarta"
},
"data": [
{
"id": 1,
"no_pesanan": "25070105C0T40C",
"status_pesanan": "Selesai",
"nama_produk": "Kaca Helm Honda Scoopy",
"username_pembeli": "ifandi94",
"total_pembayaran": 36358,
"provinsi": "DKI JAKARTA",
...
}
]
}
```
---
### Get Single Order
Retrieve a specific order by order number.
```http
GET /api/orders/:noPesanan
```
**Parameters**
| Parameter | Type | Description |
|-----------|------|-------------|
| `noPesanan` | string | Order number (14 characters) |
**Example Request**
```bash
curl "http://localhost:3000/api/orders/25070105C0T40C"
```
**Response**
```json
{
"success": true,
"data": {
"id": 1,
"no_pesanan": "25070105C0T40C",
"status_pesanan": "Selesai",
"nama_produk": "Kaca Helm Honda Scoopy",
"nama_variasi": "Clear Lekuk+ Rg baut",
"username_pembeli": "ifandi94",
"nama_penerima": "I******3",
"no_telepon": "******67",
"alamat_pengiriman": "Gu******",
"kota_kabupaten": "KOTA JAKARTA UTARA",
"provinsi": "DKI JAKARTA",
"total_pembayaran": 36358,
"waktu_pesanan_dibuat": "2025-07-01 01:02",
"waktu_pesanan_selesai": "2025-07-04 18:09",
...
}
}
```
**Error Response (404)**
```json
{
"success": false,
"error": "Order not found"
}
```
---
### Get Orders by Product
Get all orders for a specific product.
```http
GET /api/products/:productName/orders
```
**Example Request**
```bash
curl "http://localhost:3000/api/products/helm/orders?limit=20"
```
**Response**
```json
{
"success": true,
"count": 15,
"product": "helm",
"data": [...]
}
```
---
### Get Orders by Province
Get all orders from a specific province.
```http
GET /api/provinces/:province/orders
```
**Example Request**
```bash
curl "http://localhost:3000/api/provinces/JAKARTA/orders?limit=50"
```
---
### Get Orders by City
Get all orders from a specific city.
```http
GET /api/cities/:city/orders
```
**Example Request**
```bash
curl "http://localhost:3000/api/cities/BENGKULU/orders?limit=30"
```
---
### Get Orders by Username
Get all orders from a specific user.
```http
GET /api/users/:username/orders
```
**Example Request**
```bash
curl "http://localhost:3000/api/users/ifandi94/orders"
```
---
## 🔍 Search
### Advanced Search
Perform complex searches with multiple filters.
```http
POST /api/orders/search
Content-Type: application/json
```
**Request Body**
```json
{
"no_pesanan": "2507",
"username": "ifandi",
"nama_produk": "helm",
"provinsi": "jakarta",
"kota": "jakarta utara",
"status": "Selesai",
"no_resi": "SPX",
"limit": 100
}
```
**Example Request**
```bash
curl -X POST "http://localhost:3000/api/orders/search" \
-H "Content-Type: application/json" \
-d '{
"nama_produk": "helm scoopy",
"provinsi": "jakarta",
"status": "Selesai",
"limit": 20
}'
```
**Response**
```json
{
"success": true,
"count": 15,
"data": [...]
}
```
---
## 📊 Statistics
### Get Statistics
Get comprehensive database statistics.
```http
GET /api/statistics
```
**Example Request**
```bash
curl "http://localhost:3000/api/statistics"
```
**Response**
```json
{
"success": true,
"data": {
"totalOrders": {
"count": 1500
},
"totalRevenue": {
"total": 75000000
},
"ordersByStatus": [
{
"status_pesanan": "Selesai",
"count": 1450
},
{
"status_pesanan": "Dibatalkan",
"count": 50
}
],
"topProducts": [
{
"nama_produk": "Kaca Helm Honda Scoopy",
"count": 250,
"revenue": 9000000
},
...
],
"topProvinces": [
{
"provinsi": "DKI JAKARTA",
"count": 450
},
...
],
"topCities": [
{
"kota_kabupaten": "KOTA JAKARTA UTARA",
"count": 200
},
...
]
}
}
```
---
## 📤 Import
### Import Excel File
Upload and import Excel file to database.
```http
POST /api/import
Content-Type: multipart/form-data
```
**Form Data**
| Field | Type | Description |
|-------|------|-------------|
| `file` | file | Excel file (.xlsx or .xls) |
**Example Request**
```bash
curl -X POST "http://localhost:3000/api/import" \
-F "[email protected]_20250731.xlsx"
```
**Response**
```json
{
"success": true,
"message": "Import completed",
"data": {
"filename": "Order.all.20250701_20250731.xlsx",
"totalRecords": 1500,
"successCount": 1498,
"failedCount": 2,
"errors": [
{
"row": 45,
"order": "25070123ABC456",
"error": "Duplicate entry"
}
]
}
}
```
---
### Get Import Logs
Retrieve import history.
```http
GET /api/import-logs
```
**Example Request**
```bash
curl "http://localhost:3000/api/import-logs"
```
**Response**
```json
{
"success": true,
"data": [
{
"id": 1,
"filename": "Order.all.20250701_20250731.xlsx",
"total_records": 1500,
"success_count": 1498,
"failed_count": 2,
"import_date": "2025-09-30 10:30:00",
"status": "partial",
"error_message": "[{\"row\":45,\"error\":\"Duplicate\"}]"
}
]
}
```
---
## 📥 Export
### Export Data as JSON
Export filtered data as JSON.
```http
GET /api/export/json
```
**Query Parameters**
Same as GET /api/orders
**Example Request**
```bash
curl "http://localhost:3000/api/export/json?provinsi=jakarta&limit=1000" \
-o orders-export.json
```
**Response**
Direct JSON download of filtered orders.
---
## ⚠️ Error Handling
### Error Response Format
All errors follow this format:
```json
{
"success": false,
"error": "Error message description"
}
```
### HTTP Status Codes
| Code | Description |
|------|-------------|
| `200` | Success |
| `400` | Bad Request - Invalid parameters |
| `404` | Not Found - Resource doesn't exist |
| `500` | Internal Server Error |
### Common Errors
**Invalid File Type**
```json
{
"success": false,
"error": "Only Excel files (.xlsx, .xls) are allowed"
}
```
**Order Not Found**
```json
{
"success": false,
"error": "Order not found"
}
```
**No File Uploaded**
```json
{
"success": false,
"error": "No file uploaded"
}
```
---
## 🧪 Testing Examples
### cURL Examples
```bash
# Health check
curl http://localhost:3000/api/health
# Get 10 orders
curl "http://localhost:3000/api/orders?limit=10"
# Search by product
curl "http://localhost:3000/api/orders?nama_produk=helm&limit=5"
# Get statistics
curl http://localhost:3000/api/statistics
# Advanced search
curl -X POST http://localhost:3000/api/orders/search \
-H "Content-Type: application/json" \
-d '{"provinsi":"jakarta","status":"Selesai"}'
# Import Excel
curl -X POST http://localhost:3000/api/import \
-F "[email protected]"
```
### JavaScript/Node.js Example
```javascript
const axios = require('axios');
// Get orders
async function getOrders() {
const response = await axios.get('http://localhost:3000/api/orders', {
params: {
limit: 10,
status: 'Selesai'
}
});
console.log(response.data);
}
// Search orders
async function searchOrders() {
const response = await axios.post('http://localhost:3000/api/orders/search', {
nama_produk: 'helm',
provinsi: 'jakarta',
limit: 20
});
console.log(response.data);
}
// Import file
async function importFile() {
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('file', fs.createReadStream('orders.xlsx'));
const response = await axios.post('http://localhost:3000/api/import', form, {
headers: form.getHeaders()
});
console.log(response.data);
}
```
### Python Example
```python
import requests
# Get orders
response = requests.get('http://localhost:3000/api/orders', params={
'limit': 10,
'status': 'Selesai'
})
print(response.json())
# Search orders
response = requests.post('http://localhost:3000/api/orders/search', json={
'nama_produk': 'helm',
'provinsi': 'jakarta',
'limit': 20
})
print(response.json())
# Import file
with open('orders.xlsx', 'rb') as f:
files = {'file': f}
response = requests.post('http://localhost:3000/api/import', files=files)
print(response.json())
```
---
## 📝 Notes
1. All timestamps are in format: `YYYY-MM-DD HH:MM`
2. Currency values are in Indonesian Rupiah (IDR)
3. Default limit is 50 records per request
4. Maximum file upload size is 50MB
5. Excel files must match the expected schema
---
## 🔒 Security Recommendations
For production deployment:
1. Add API authentication (JWT/API Keys)
2. Implement rate limiting
3. Use HTTPS
4. Validate all inputs
5. Sanitize user data
6. Use environment variables for sensitive data
7. Enable CORS only for trusted domains
8. Add request logging
9. Implement pagination for large datasets
10. Add database backups
---
## 📞 Support
For issues or questions:
- Check logs: `./logs/bot.log`
- Test with: `npm test`
- Create issue on GitHub
---
Made with ❤️ by Texa Bot Team
