API Endpoints Reference

Dokumentasi lengkap API endpoints yang digunakan oleh MStore Mobile.

🌐 Base URL

Development:  https://dev-api.mstore.com
Staging:      https://staging-api.mstore.com
Production:   https://api.mstore.com

🔐 Authentication

Semua endpoint (kecuali public endpoints) memerlukan authentication token.

Headers

Authorization: Bearer {access_token}
Content-Type: application/json
X-Platform: ios|android|web
X-App-Version: 1.0.0
X-Device-ID: {unique_device_id}
X-Correlation-ID: {uuid}
X-Trace-ID: {uuid}

📚 API Endpoints

Authentication

{
  "email": "[email protected]",
  "password": "password123"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user_123",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "cashier",
      "branchId": "branch_001"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}

POST /api/v1/auth/refresh-token

Refresh access token. Request:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}

POST /api/v1/auth/register-device

{
  "deviceId": "device_abc123",
  "fcmToken": "fcm_token_xyz",
  "platform": "ios",
  "appVersion": "1.0.0"
}

Response:

{
  "success": true,
  "message": "Device registered successfully"
}

POST /api/v1/auth/logout

Logout user. Response:

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

Products

GET /api/v1/products

Get list of products. Query Parameters:

page (int): Page number (default: 1)
limit (int): Items per page (default: 20)
search (string): Search query
category (string): Filter by category
branchId (string): Filter by branch

Response:

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_001",
        "name": "Product Name",
        "sku": "SKU001",
        "barcode": "1234567890",
        "description": "Product description",
        "category": "Category A",
        "price": 50000,
        "cost": 30000,
        "stock": 100,
        "minStock": 10,
        "unit": "pcs",
        "imageUrl": "https://storage.mstore.com/products/prod_001.jpg",
        "isActive": true,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

GET /api/v1/products/

Get product by ID. Response:

{
  "success": true,
  "data": {
    "id": "prod_001",
    "name": "Product Name",
    "sku": "SKU001",
    "barcode": "1234567890",
    "description": "Product description",
    "category": "Category A",
    "price": 50000,
    "cost": 30000,
    "stock": 100,
    "minStock": 10,
    "unit": "pcs",
    "imageUrl": "https://storage.mstore.com/products/prod_001.jpg",
    "isActive": true,
    "variants": [],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

POST /api/v1/products

Create new product. Request:

{
  "name": "New Product",
  "sku": "SKU002",
  "barcode": "0987654321",
  "description": "Product description",
  "category": "Category B",
  "price": 75000,
  "cost": 45000,
  "stock": 50,
  "minStock": 5,
  "unit": "pcs",
  "imageUrl": "https://storage.mstore.com/products/prod_002.jpg"
}

Response:

{
  "success": true,
  "data": {
    "id": "prod_002",
    "name": "New Product",
    // ... other fields
  },
  "message": "Product created successfully"
}

PUT /api/v1/products/

Update product. Request: Same as POST Response:

{
  "success": true,
  "data": {
    "id": "prod_002",
    // ... updated fields
  },
  "message": "Product updated successfully"
}

DELETE /api/v1/products/

Delete product. Response:

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

Transactions

POST /api/v1/transactions

Create new transaction. Request:

{
  "branchCode": "BR001",
  "items": [
    {
      "productId": "prod_001",
      "productName": "Product Name",
      "quantity": 2,
      "price": 50000,
      "subtotal": 100000
    }
  ],
  "subtotal": 100000,
  "discount": 10000,
  "tax": 0,
  "total": 90000,
  "paymentMethod": "cash",
  "paidAmount": 100000,
  "change": 10000,
  "notes": "Transaction notes"
}

Response:

{
  "success": true,
  "data": {
    "id": "trx_001",
    "transactionNumber": "TRX-20241014-001",
    "branchCode": "BR001",
    "items": [...],
    "subtotal": 100000,
    "discount": 10000,
    "tax": 0,
    "total": 90000,
    "paymentMethod": "cash",
    "paidAmount": 100000,
    "change": 10000,
    "status": "completed",
    "createdAt": "2024-10-14T10:00:00Z",
    "createdBy": "user_123"
  },
  "message": "Transaction created successfully"
}

GET /api/v1/transactions

Get transaction history. Query Parameters:

page (int): Page number
limit (int): Items per page
startDate (string): Start date (ISO 8601)
endDate (string): End date (ISO 8601)
branchId (string): Filter by branch
status (string): Filter by status

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "trx_001",
        "transactionNumber": "TRX-20241014-001",
        "total": 90000,
        "paymentMethod": "cash",
        "status": "completed",
        "createdAt": "2024-10-14T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 500,
      "totalPages": 25
    }
  }
}

GET /api/v1/transactions/

Get transaction detail. Response:

{
  "success": true,
  "data": {
    "id": "trx_001",
    "transactionNumber": "TRX-20241014-001",
    "branchCode": "BR001",
    "items": [
      {
        "productId": "prod_001",
        "productName": "Product Name",
        "quantity": 2,
        "price": 50000,
        "subtotal": 100000
      }
    ],
    "subtotal": 100000,
    "discount": 10000,
    "tax": 0,
    "total": 90000,
    "paymentMethod": "cash",
    "paidAmount": 100000,
    "change": 10000,
    "status": "completed",
    "createdAt": "2024-10-14T10:00:00Z",
    "createdBy": {
      "id": "user_123",
      "name": "John Doe"
    }
  }
}

Inventory

GET /api/v1/inventory

Get inventory list. Query Parameters:

branchId (string): Filter by branch
lowStock (boolean): Show only low stock items

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "productId": "prod_001",
        "productName": "Product Name",
        "sku": "SKU001",
        "stock": 100,
        "minStock": 10,
        "status": "sufficient",
        "lastUpdated": "2024-10-14T10:00:00Z"
      }
    ]
  }
}

POST /api/v1/inventory/adjustment

Create inventory adjustment. Request:

{
  "branchId": "branch_001",
  "productId": "prod_001",
  "type": "in|out|adjustment",
  "quantity": 50,
  "reason": "Stock opname",
  "notes": "Additional notes"
}

Response:

{
  "success": true,
  "data": {
    "id": "adj_001",
    "productId": "prod_001",
    "type": "in",
    "quantity": 50,
    "previousStock": 100,
    "newStock": 150,
    "createdAt": "2024-10-14T10:00:00Z"
  },
  "message": "Inventory adjusted successfully"
}

Dashboard

GET /api/v1/dashboard/summary

Get dashboard summary. Query Parameters:

branchId (string): Filter by branch
startDate (string): Start date
endDate (string): End date

Response:

{
  "success": true,
  "data": {
    "revenue": {
      "today": 5000000,
      "thisWeek": 30000000,
      "thisMonth": 120000000,
      "growth": 15.5
    },
    "transactions": {
      "today": 150,
      "thisWeek": 980,
      "thisMonth": 4200,
      "growth": 12.3
    },
    "topProducts": [
      {
        "productId": "prod_001",
        "productName": "Product Name",
        "quantity": 500,
        "revenue": 25000000
      }
    ],
    "lowStockItems": 5,
    "pendingOrders": 10
  }
}

Reports

GET /api/v1/reports/sales

Get sales report. Query Parameters:

branchId (string): Filter by branch
startDate (string): Start date (required)
endDate (string): End date (required)
groupBy (string): day|week|month

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalRevenue": 120000000,
      "totalTransactions": 4200,
      "averageTransaction": 28571
    },
    "details": [
      {
        "date": "2024-10-01",
        "revenue": 4000000,
        "transactions": 140,
        "averageTransaction": 28571
      }
    ]
  }
}

❌ Error Responses

Standard Error Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {
      "field": "Additional error details"
    }
  }
}

HTTP Status Codes

200 - OK
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Validation Error
429 - Too Many Requests
500 - Internal Server Error
503 - Service Unavailable

Common Error Codes

AUTH_001 - Invalid credentials
AUTH_002 - Token expired
AUTH_003 - Invalid token
AUTH_004 - Insufficient permissions

PRODUCT_001 - Product not found
PRODUCT_002 - Duplicate SKU
PRODUCT_003 - Invalid product data

TRANSACTION_001 - Transaction not found
TRANSACTION_002 - Insufficient stock
TRANSACTION_003 - Invalid payment amount

INVENTORY_001 - Inventory not found
INVENTORY_002 - Invalid adjustment quantity

🔄 Pagination

Standard pagination format:

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}

🚀 Rate Limiting

Rate Limit: 100 requests per minute per user
Headers:
- X-RateLimit-Limit: 100
- X-RateLimit-Remaining: 95
- X-RateLimit-Reset: 1697270400

📊 Versioning

API menggunakan versioning di URL path:

Current: /api/v1/
Future: /api/v2/

Next Steps

API Best Practices:

✅ Gunakan HTTPS untuk semua requests
✅ Include correlation ID untuk tracking
✅ Handle rate limiting gracefully
✅ Implement retry logic untuk network errors
✅ Cache responses when appropriate

Endpoints

​API Endpoints Reference

​🌐 Base URL

​🔐 Authentication

​Headers

​📚 API Endpoints

​Authentication

​POST /api/v1/auth/login

​POST /api/v1/auth/refresh-token

​POST /api/v1/auth/register-device

​POST /api/v1/auth/logout

​Products

​GET /api/v1/products

​GET /api/v1/products/

​POST /api/v1/products

​PUT /api/v1/products/

​DELETE /api/v1/products/

​Transactions

​POST /api/v1/transactions

​GET /api/v1/transactions

​GET /api/v1/transactions/

​Inventory

​GET /api/v1/inventory

​POST /api/v1/inventory/adjustment

​Dashboard

​GET /api/v1/dashboard/summary

​Reports

​GET /api/v1/reports/sales

​❌ Error Responses

​Standard Error Format

​HTTP Status Codes

​Common Error Codes

​🔄 Pagination

​🚀 Rate Limiting

​📊 Versioning

​Next Steps

API Endpoints Reference

🌐 Base URL

🔐 Authentication

Headers

📚 API Endpoints

Authentication

POST /api/v1/auth/login

POST /api/v1/auth/refresh-token

POST /api/v1/auth/register-device

POST /api/v1/auth/logout

Products

GET /api/v1/products

GET /api/v1/products/

POST /api/v1/products

PUT /api/v1/products/

DELETE /api/v1/products/

Transactions

POST /api/v1/transactions

GET /api/v1/transactions

GET /api/v1/transactions/

Inventory

GET /api/v1/inventory

POST /api/v1/inventory/adjustment

Dashboard

GET /api/v1/dashboard/summary

Reports

GET /api/v1/reports/sales

❌ Error Responses

Standard Error Format

HTTP Status Codes

Common Error Codes

🔄 Pagination

🚀 Rate Limiting

📊 Versioning

Next Steps