Sales Order API Documentation
RESTful API for managing Sales Orders in the QUADS ERP system. This API provides access to all public methods from the SalesOrder_BO class through modern REST endpoints.
Base URL
https://your-domain.com/api
Authentication
The API supports two authentication methods:
- Session-based: Use existing ERP session (automatically detected)
- Token-based: Include Authorization header with Bearer token or API key
Authorization: Bearer your-jwt-token
Authorization: ApiKey your-api-key
Response Format
All responses follow a consistent JSON structure:
Success Response:
{
"success": true,
"data": { ... },
"message": "Optional success message"
}
Error Response:
{
"success": false,
"error": {
"message": "Error description",
"code": 400,
"details": [ ... ]
}
}
Endpoints
GET /sales-orders/max-number
Get the maximum sales order number for a given year and location.
Query Parameters
| Parameter | Type | Required | Description |
|---|
| year_id | integer | Yes | Financial year ID |
| location_id | integer | Yes | Location ID |
Example Request
GET /api/sales-orders/max-number?year_id=2024&location_id=1
Example Response
{
"success": true,
"data": {
"max_sales_order_number": "SO-2024-001",
"year_id": 2024,
"location_id": 1
}
}
POST /sales-orders
Create a new sales order with details.
Request Body
{
"customer_id": 123,
"sales_order_date": "2024-01-27",
"location_id": 1,
"sales_order_no": "SO-2024-002",
"grand_total": 15000.00,
"remarks": "Urgent order",
"details": [
{
"product_id": 456,
"packsize_id": 789,
"quantity": 10,
"rate": 1000.00,
"amount": 10000.00,
"remarks": "Product remarks"
}
],
"other_charges": [
{
"description": "Shipping",
"amount": 500.00
}
]
}
Example Response
{
"success": true,
"message": "Sales order created successfully",
"data": {
"sales_order_id": 1001,
"order_number": "SO-2024-002",
"total_amount": 15000.00
}
}
GET /sales-orders/{id}
Retrieve a specific sales order by ID.
Path Parameters
| Parameter | Type | Description |
|---|
| id | integer | Sales order ID |
Example Response
{
"success": true,
"data": {
"sales_order_id": 1001,
"sales_order_no": "SO-2024-002",
"customer_id": 123,
"customer_name": "ABC Company",
"sales_order_date": "2024-01-27",
"location_id": 1,
"grand_total": 15000.00,
"details": [
{
"sales_order_detail_id": 2001,
"product_id": 456,
"product_name": "Product ABC",
"quantity": 10,
"rate": 1000.00,
"amount": 10000.00
}
]
}
}
PUT /sales-orders/{id}
Update an existing sales order.
Request Body
Same structure as POST /sales-orders, but all fields are optional.
Example Response
{
"success": true,
"message": "Sales order updated successfully",
"data": {
"sales_order_id": 1001,
"updated": true
}
}
DELETE /sales-orders/{id}
Delete (soft delete) a sales order.
Example Response
{
"success": true,
"message": "Sales order deleted successfully",
"data": {
"sales_order_id": 1001,
"deleted": true
}
}
POST /sales-orders/validate-licence
Validate product licences for sales order details.
Request Body
{
"sales_order_details": [
{
"product_id": 456,
"quantity": 10
}
]
}
Example Response
{
"success": true,
"data": {
"validation_message": "Warning: Product XYZ licence expires soon",
"has_warnings": true
}
}
POST /sales-orders/calculate-totals
Calculate order totals for given details and charges.
Request Body
{
"details": [
{
"quantity": 10,
"rate": 1000.00
}
],
"other_charges": [
{
"amount": 500.00
}
]
}
Example Response
{
"success": true,
"data": {
"subtotal": 10000.00,
"other_charges_total": 500.00,
"grand_total": 10500.00
}
}
GET /sales-orders/dropdown-options/{type}
Generate HTML dropdown options for forms.
Path Parameters
| Parameter | Values | Description |
|---|
| type | field-officers, products, locations, customers, ports | Type of dropdown options |
Query Parameters
| Parameter | Type | Description |
|---|
| selected_id | integer | ID of selected option (optional) |
Example Response
{
"success": true,
"data": {
"type": "products",
"html": "<option value=\"1\">Product A</option><option value=\"2\" selected>Product B</option>",
"selected_id": 2
}
}
Error Codes
| Code | Description |
|---|
| 400 | Bad Request - Invalid input data |
| 401 | Unauthorized - Authentication required |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource not found |
| 422 | Unprocessable Entity - Validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server error |
Rate Limiting
API requests are limited to 100 requests per minute per IP address. Exceeded limits will return a 429 status code.
Data Types
| Type | Format | Example |
|---|
| Date | YYYY-MM-DD | 2024-01-27 |
| DateTime | YYYY-MM-DD HH:mm:ss | 2024-01-27 14:30:00 |
| Decimal | Floating point | 1234.56 |
| Boolean | true/false | true |
Examples
JavaScript (Fetch API)
// Create a new sales order
fetch('/api/sales-orders', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-token'
},
body: JSON.stringify({
customer_id: 123,
sales_order_date: '2024-01-27',
location_id: 1,
grand_total: 15000.00,
details: [
{
product_id: 456,
quantity: 10,
rate: 1000.00,
amount: 10000.00
}
]
})
})
.then(response => response.json())
.then(data => console.log(data));
PHP (cURL)
$data = [
'customer_id' => 123,
'sales_order_date' => '2024-01-27',
'location_id' => 1,
'grand_total' => 15000.00,
'details' => [
[
'product_id' => 456,
'quantity' => 10,
'rate' => 1000.00,
'amount' => 10000.00
]
]
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://your-domain.com/api/sales-orders');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer your-token'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
Support
For API support and questions, please contact the development team or refer to the main ERP system documentation.
Generated on: