463 lines
11 KiB
Markdown
463 lines
11 KiB
Markdown
# Advanced Order Management API Documentation
|
|
|
|
## Overview
|
|
|
|
The Advanced Order Management API provides comprehensive functionality for managing orders beyond basic operations. This includes partial refunds, void operations, and bill splitting capabilities.
|
|
|
|
## Features
|
|
|
|
- ✅ **Partial Refund**: Refund specific items from paid orders
|
|
- ✅ **Void Order**: Cancel ongoing orders (per item or entire order)
|
|
- ✅ **Split Bill**: Split orders by items or amounts
|
|
- ✅ **Order Status Management**: Support for PARTIAL and VOIDED statuses
|
|
- ✅ **Transaction Tracking**: Complete audit trail for all operations
|
|
- ✅ **Validation**: Comprehensive validation for all operations
|
|
|
|
## API Endpoints
|
|
|
|
### 1. Partial Refund
|
|
|
|
**POST** `/order/partial-refund`
|
|
|
|
Refund specific items from a paid order while keeping the remaining items.
|
|
|
|
#### Request Body
|
|
|
|
```json
|
|
{
|
|
"order_id": 123,
|
|
"reason": "Customer returned damaged items",
|
|
"items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"quantity": 2
|
|
},
|
|
{
|
|
"order_item_id": 789,
|
|
"quantity": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Request Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|--------|----------|--------------------------------|
|
|
| order_id | int64 | Yes | ID of the order to refund |
|
|
| reason | string | Yes | Reason for the partial refund |
|
|
| items | array | Yes | Array of items to refund |
|
|
|
|
#### Item Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|---------------|--------|----------|--------------------------------|
|
|
| order_item_id | int64 | Yes | ID of the order item to refund |
|
|
| quantity | int | Yes | Quantity to refund (min: 1) |
|
|
|
|
#### Response
|
|
|
|
**Success (200 OK)**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"status": 200,
|
|
"data": {
|
|
"order_id": 123,
|
|
"status": "PARTIAL",
|
|
"refunded_amount": 75000,
|
|
"remaining_amount": 25000,
|
|
"reason": "Customer returned damaged items",
|
|
"refunded_at": "2024-01-15T10:30:00Z",
|
|
"customer_name": "John Doe",
|
|
"payment_type": "CASH",
|
|
"refunded_items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"item_name": "Bakso Special",
|
|
"quantity": 2,
|
|
"unit_price": 25000,
|
|
"total_price": 50000
|
|
},
|
|
{
|
|
"order_item_id": 789,
|
|
"item_name": "Es Teh Manis",
|
|
"quantity": 1,
|
|
"unit_price": 25000,
|
|
"total_price": 25000
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Void Order
|
|
|
|
**POST** `/order/void`
|
|
|
|
Void an ongoing order (NEW or PENDING status) either entirely or by specific items.
|
|
|
|
#### Request Body
|
|
|
|
**Void Entire Order:**
|
|
```json
|
|
{
|
|
"order_id": 123,
|
|
"reason": "Customer cancelled order",
|
|
"type": "ALL"
|
|
}
|
|
```
|
|
|
|
**Void Specific Items:**
|
|
```json
|
|
{
|
|
"order_id": 123,
|
|
"reason": "Customer changed mind about some items",
|
|
"type": "ITEM",
|
|
"items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"quantity": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Request Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|--------|----------|--------------------------------|
|
|
| order_id | int64 | Yes | ID of the order to void |
|
|
| reason | string | Yes | Reason for voiding |
|
|
| type | string | Yes | Type: "ALL" or "ITEM" |
|
|
| items | array | No | Required if type is "ITEM" |
|
|
|
|
#### Response
|
|
|
|
**Success (200 OK)**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"status": 200,
|
|
"data": {
|
|
"order_id": 123,
|
|
"status": "VOIDED",
|
|
"reason": "Customer cancelled order",
|
|
"voided_at": "2024-01-15T10:30:00Z",
|
|
"customer_name": "John Doe",
|
|
"voided_items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"item_name": "Bakso Special",
|
|
"quantity": 1,
|
|
"unit_price": 25000,
|
|
"total_price": 25000
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Split Bill
|
|
|
|
**POST** `/order/split-bill`
|
|
|
|
Split an order into a separate order by items or amounts.
|
|
|
|
#### Request Body
|
|
|
|
**Split by Items:**
|
|
```json
|
|
{
|
|
"order_id": 123,
|
|
"type": "ITEM",
|
|
"payment_method": "CASH",
|
|
"payment_provider": "CASH",
|
|
"items": [
|
|
{
|
|
"order_item_id": 789,
|
|
"quantity": 2
|
|
},
|
|
{
|
|
"order_item_id": 101,
|
|
"quantity": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Split by Amount:**
|
|
```json
|
|
{
|
|
"order_id": 123,
|
|
"type": "AMOUNT",
|
|
"payment_method": "CASH",
|
|
"payment_provider": "CASH",
|
|
"amount": 50000
|
|
}
|
|
```
|
|
|
|
#### Request Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|------------------|--------|----------|--------------------------------|
|
|
| order_id | int64 | Yes | ID of the order to split |
|
|
| type | string | Yes | Type: "ITEM" or "AMOUNT" |
|
|
| payment_method | string | Yes | Payment method for split order |
|
|
| payment_provider | string | No | Payment provider for split order|
|
|
| items | array | No | Required if type is "ITEM" |
|
|
| amount | float | No | Required if type is "AMOUNT" (must be less than order total) |
|
|
|
|
#### Item Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|---------------|--------|----------|--------------------------------|
|
|
| order_item_id | int64 | Yes | ID of the order item to split |
|
|
| quantity | int | Yes | Quantity to split (min: 1) |
|
|
|
|
#### Response
|
|
|
|
**Success (200 OK)**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"status": 200,
|
|
"data": {
|
|
"id": 124,
|
|
"partner_id": 1,
|
|
"status": "PAID",
|
|
"amount": 100000,
|
|
"total": 110000,
|
|
"tax": 10000,
|
|
"customer_id": 456,
|
|
"customer_name": "John Doe",
|
|
"payment_type": "CASH",
|
|
"payment_provider": "CASH",
|
|
"source": "POS",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"updated_at": "2024-01-15T10:30:00Z",
|
|
"order_items": [
|
|
{
|
|
"id": 789,
|
|
"item_id": 1,
|
|
"item_name": "Bakso Special",
|
|
"price": 50000,
|
|
"quantity": 2,
|
|
"subtotal": 100000
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Business Logic
|
|
|
|
### Partial Refund Process
|
|
|
|
1. **Validation**
|
|
- Verify order exists and belongs to partner
|
|
- Ensure order status is "PAID"
|
|
- Validate refund items exist and quantities are valid
|
|
|
|
2. **Item Updates**
|
|
- Reduce quantities of refunded items
|
|
- Remove items completely if quantity becomes 0
|
|
- Recalculate order totals
|
|
|
|
3. **Order Status Update**
|
|
- Set status to "PARTIAL" if items remain
|
|
- Set status to "REFUNDED" if all items refunded
|
|
|
|
4. **Transaction Creation**
|
|
- Create refund transaction with negative amount
|
|
- Track refund details
|
|
|
|
### Void Order Process
|
|
|
|
1. **Validation**
|
|
- Verify order exists and belongs to partner
|
|
- Ensure order status is "NEW" or "PENDING"
|
|
- Validate void items if type is "ITEM"
|
|
|
|
2. **Void Operations**
|
|
- **ALL**: Set order status to "VOIDED"
|
|
- **ITEM**: Reduce quantities and recalculate totals
|
|
|
|
3. **Status Management**
|
|
- Set status to "PARTIAL" if items remain
|
|
- Set status to "VOIDED" if all items voided
|
|
|
|
### Split Bill Process
|
|
|
|
1. **Validation**
|
|
- Verify order exists and belongs to partner
|
|
- Ensure order status is "NEW" or "PENDING"
|
|
- Validate split configuration
|
|
|
|
2. **Split Operations**
|
|
- **ITEM**: Create new PAID order with specified items, reduce quantities in original order
|
|
- **AMOUNT**: Create new PAID order with specified amount, reduce amount in original order
|
|
|
|
3. **Order Management**
|
|
- Original order remains PENDING with reduced items/amount
|
|
- New split order becomes PAID with specified payment method
|
|
- Recalculate totals for both orders
|
|
|
|
## Order Status Flow
|
|
|
|
```
|
|
NEW → PENDING → PAID → REFUNDED
|
|
↓ ↓ ↓
|
|
VOIDED VOIDED PARTIAL
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Common Error Responses
|
|
|
|
**Order Not Found (404)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"status": 404,
|
|
"message": "order not found"
|
|
}
|
|
```
|
|
|
|
**Invalid Order Status (400)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"status": 400,
|
|
"message": "only paid order can be partially refunded"
|
|
}
|
|
```
|
|
|
|
**Invalid Quantity (400)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"status": 400,
|
|
"message": "refund quantity 3 exceeds available quantity 2 for item 456"
|
|
}
|
|
```
|
|
|
|
**Split Amount Mismatch (400)**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"status": 400,
|
|
"message": "split amount 95000 must be less than order total 100000"
|
|
}
|
|
```
|
|
|
|
## Database Schema Updates
|
|
|
|
### Orders Table
|
|
|
|
```sql
|
|
-- New statuses supported
|
|
ALTER TABLE orders ADD CONSTRAINT check_status
|
|
CHECK (status IN ('NEW', 'PENDING', 'PAID', 'REFUNDED', 'VOIDED', 'PARTIAL'));
|
|
```
|
|
|
|
### Order Items Table
|
|
|
|
```sql
|
|
-- Support for quantity updates
|
|
ALTER TABLE order_items ADD COLUMN updated_at TIMESTAMP DEFAULT NOW();
|
|
```
|
|
|
|
## Constants
|
|
|
|
### Order Status
|
|
|
|
```go
|
|
const (
|
|
New OrderStatus = "NEW"
|
|
Paid OrderStatus = "PAID"
|
|
Cancel OrderStatus = "CANCEL"
|
|
Pending OrderStatus = "PENDING"
|
|
Refunded OrderStatus = "REFUNDED"
|
|
Voided OrderStatus = "VOIDED" // New
|
|
Partial OrderStatus = "PARTIAL" // New
|
|
)
|
|
```
|
|
|
|
## Testing Examples
|
|
|
|
### cURL Examples
|
|
|
|
**Partial Refund:**
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/order/partial-refund \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
|
-d '{
|
|
"order_id": 123,
|
|
"reason": "Customer returned damaged items",
|
|
"items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"quantity": 2
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
**Void Order:**
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/order/void \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
|
-d '{
|
|
"order_id": 123,
|
|
"reason": "Customer cancelled order",
|
|
"type": "ALL"
|
|
}'
|
|
```
|
|
|
|
**Split Bill:**
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/order/split-bill \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
|
-d '{
|
|
"order_id": 123,
|
|
"type": "ITEM",
|
|
"payment_method": "CASH",
|
|
"payment_provider": "CASH",
|
|
"items": [
|
|
{
|
|
"order_item_id": 456,
|
|
"quantity": 1
|
|
},
|
|
{
|
|
"order_item_id": 789,
|
|
"quantity": 1
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
1. **Authorization**: Only authorized users can perform these operations
|
|
2. **Audit Trail**: All operations are logged with user and timestamp
|
|
3. **Validation**: Strict validation prevents invalid operations
|
|
4. **Data Integrity**: Transaction-based operations ensure consistency
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Bulk Operations**: Support for bulk partial refunds/voids
|
|
2. **Approval Workflow**: Multi-level approval for large operations
|
|
3. **Notification System**: Customer notifications for refunds/voids
|
|
4. **Analytics**: Dashboard for operation trends and analysis
|
|
5. **Integration**: Integration with inventory management systems
|
|
|
|
## Support
|
|
|
|
For questions or issues with the Advanced Order Management API, please contact the development team or create an issue in the project repository. |