Initial commit: Inventory Barcode System
This commit is contained in:
507
docs/API.md
Normal file
507
docs/API.md
Normal file
@ -0,0 +1,507 @@
|
||||
# Inventory Barcode System API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Inventory Barcode System provides a RESTful API for managing products, inventory levels, and generating barcodes/QR codes. This documentation covers all available endpoints, request/response formats, and usage examples.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://localhost:3000/api
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
Currently, the API does not require authentication. In production environments, consider implementing proper authentication and authorization mechanisms.
|
||||
|
||||
## Error Handling
|
||||
|
||||
All API endpoints return consistent error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": true,
|
||||
"message": "Error description",
|
||||
"code": "ERROR_CODE",
|
||||
"details": {}
|
||||
}
|
||||
```
|
||||
|
||||
Common HTTP status codes:
|
||||
- `200` - Success
|
||||
- `201` - Created
|
||||
- `400` - Bad Request
|
||||
- `404` - Not Found
|
||||
- `409` - Conflict
|
||||
- `500` - Internal Server Error
|
||||
|
||||
## Products API
|
||||
|
||||
### Get All Products
|
||||
|
||||
Retrieve a list of all products in the system.
|
||||
|
||||
**Endpoint:** `GET /api/products`
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (optional): Page number for pagination (default: 1)
|
||||
- `limit` (optional): Number of items per page (default: 50)
|
||||
- `search` (optional): Search term for product code or description
|
||||
- `category` (optional): Filter by product category
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"category": "Electronics",
|
||||
"unit_of_measure": "pcs",
|
||||
"created_at": "2024-01-01T00:00:00.000Z",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 50,
|
||||
"total": 100,
|
||||
"pages": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Product by ID
|
||||
|
||||
Retrieve a specific product by its ID.
|
||||
|
||||
**Endpoint:** `GET /api/products/:id`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"category": "Electronics",
|
||||
"unit_of_measure": "pcs",
|
||||
"created_at": "2024-01-01T00:00:00.000Z",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Create Product
|
||||
|
||||
Create a new product in the system.
|
||||
|
||||
**Endpoint:** `POST /api/products`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"category": "Electronics",
|
||||
"unit_of_measure": "pcs"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"category": "Electronics",
|
||||
"unit_of_measure": "pcs",
|
||||
"created_at": "2024-01-01T00:00:00.000Z",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update Product
|
||||
|
||||
Update an existing product.
|
||||
|
||||
**Endpoint:** `PUT /api/products/:id`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"description": "Updated Product Description",
|
||||
"category": "Updated Category",
|
||||
"unit_of_measure": "kg"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Product
|
||||
|
||||
Delete a product from the system.
|
||||
|
||||
**Endpoint:** `DELETE /api/products/:id`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Product deleted successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### Import Products from Excel
|
||||
|
||||
Import products from an Excel file.
|
||||
|
||||
**Endpoint:** `POST /api/products/import`
|
||||
|
||||
**Request:** Multipart form data with Excel file
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"imported": 50,
|
||||
"skipped": 5,
|
||||
"errors": [
|
||||
{
|
||||
"row": 10,
|
||||
"error": "Invalid product code format"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Inventory API
|
||||
|
||||
### Get Inventory Levels
|
||||
|
||||
Retrieve inventory levels for all products or specific products.
|
||||
|
||||
**Endpoint:** `GET /api/inventory`
|
||||
|
||||
**Query Parameters:**
|
||||
- `product_id` (optional): Filter by specific product ID
|
||||
- `low_stock` (optional): Show only products with low stock levels
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"product_id": 1,
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"current_level": 100,
|
||||
"minimum_level": 10,
|
||||
"maximum_level": 500,
|
||||
"last_updated": "2024-01-01T00:00:00.000Z",
|
||||
"updated_by": "system"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Update Inventory Level
|
||||
|
||||
Update the inventory level for a specific product.
|
||||
|
||||
**Endpoint:** `PUT /api/inventory/:productId`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"new_level": 150,
|
||||
"change_reason": "Stock replenishment",
|
||||
"updated_by": "user123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"product_id": 1,
|
||||
"old_level": 100,
|
||||
"new_level": 150,
|
||||
"change_reason": "Stock replenishment",
|
||||
"updated_by": "user123",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Inventory History
|
||||
|
||||
Retrieve the history of inventory changes for a product.
|
||||
|
||||
**Endpoint:** `GET /api/inventory/:productId/history`
|
||||
|
||||
**Query Parameters:**
|
||||
- `limit` (optional): Number of history records to return (default: 50)
|
||||
- `from_date` (optional): Start date for history filter (ISO format)
|
||||
- `to_date` (optional): End date for history filter (ISO format)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"product_id": 1,
|
||||
"old_level": 90,
|
||||
"new_level": 100,
|
||||
"change_reason": "Stock adjustment",
|
||||
"updated_by": "user123",
|
||||
"updated_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Export Inventory to Excel
|
||||
|
||||
Export current inventory levels to an Excel file.
|
||||
|
||||
**Endpoint:** `GET /api/inventory/export`
|
||||
|
||||
**Query Parameters:**
|
||||
- `format` (optional): Export format ('xlsx' or 'csv', default: 'xlsx')
|
||||
- `include_history` (optional): Include inventory history (true/false, default: false)
|
||||
|
||||
**Response:** Excel file download
|
||||
|
||||
## Codes API
|
||||
|
||||
### Generate Barcode
|
||||
|
||||
Generate a barcode for a specific product.
|
||||
|
||||
**Endpoint:** `POST /api/codes/barcode`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"product_code": "ABC123",
|
||||
"format": "CODE128",
|
||||
"width": 2,
|
||||
"height": 100,
|
||||
"displayValue": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"product_code": "ABC123",
|
||||
"format": "CODE128",
|
||||
"barcode_svg": "<svg>...</svg>",
|
||||
"barcode_base64": "data:image/png;base64,..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Generate QR Code
|
||||
|
||||
Generate a QR code for a specific product.
|
||||
|
||||
**Endpoint:** `POST /api/codes/qrcode`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"product_code": "ABC123",
|
||||
"size": 200,
|
||||
"error_correction": "M",
|
||||
"include_product_info": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"product_code": "ABC123",
|
||||
"qr_code_svg": "<svg>...</svg>",
|
||||
"qr_code_base64": "data:image/png;base64,...",
|
||||
"embedded_data": {
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"timestamp": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Generate Printable Layout
|
||||
|
||||
Generate a printable PDF layout with barcodes/QR codes.
|
||||
|
||||
**Endpoint:** `POST /api/codes/printable`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"products": ["ABC123", "DEF456", "GHI789"],
|
||||
"code_type": "barcode",
|
||||
"layout": {
|
||||
"page_size": "A4",
|
||||
"labels_per_row": 3,
|
||||
"labels_per_column": 8,
|
||||
"include_description": true,
|
||||
"font_size": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** PDF file download
|
||||
|
||||
### Decode Scanned Code
|
||||
|
||||
Decode a scanned barcode or QR code and retrieve product information.
|
||||
|
||||
**Endpoint:** `POST /api/codes/decode`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"code_data": "ABC123",
|
||||
"code_type": "barcode"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"product": {
|
||||
"id": 1,
|
||||
"product_code": "ABC123",
|
||||
"description": "Sample Product",
|
||||
"category": "Electronics"
|
||||
},
|
||||
"inventory": {
|
||||
"current_level": 100,
|
||||
"minimum_level": 10,
|
||||
"last_updated": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Health Check
|
||||
|
||||
### System Health
|
||||
|
||||
Check the health status of the application.
|
||||
|
||||
**Endpoint:** `GET /health`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "OK",
|
||||
"timestamp": "2024-01-01T00:00:00.000Z",
|
||||
"uptime": 3600,
|
||||
"memory": {
|
||||
"rss": 50331648,
|
||||
"heapTotal": 20971520,
|
||||
"heapUsed": 15728640,
|
||||
"external": 1048576
|
||||
},
|
||||
"version": "v18.17.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
API endpoints are rate-limited to prevent abuse:
|
||||
- Default: 100 requests per 15 minutes per IP address
|
||||
- File upload endpoints: 10 requests per 15 minutes per IP address
|
||||
|
||||
## File Upload Limits
|
||||
|
||||
- Maximum file size: 10MB
|
||||
- Supported formats: .xlsx, .xls
|
||||
- Maximum concurrent uploads: 3
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete Import Workflow
|
||||
|
||||
1. **Upload Excel file:**
|
||||
```bash
|
||||
curl -X POST \
|
||||
http://localhost:3000/api/products/import \
|
||||
-H 'Content-Type: multipart/form-data' \
|
||||
-F 'file=@inventory.xlsx'
|
||||
```
|
||||
|
||||
2. **Generate barcodes for imported products:**
|
||||
```bash
|
||||
curl -X POST \
|
||||
http://localhost:3000/api/codes/printable \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"products": ["ABC123", "DEF456"],
|
||||
"code_type": "barcode",
|
||||
"layout": {
|
||||
"page_size": "A4",
|
||||
"labels_per_row": 3,
|
||||
"include_description": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
3. **Update inventory after scanning:**
|
||||
```bash
|
||||
curl -X PUT \
|
||||
http://localhost:3000/api/inventory/1 \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"new_level": 85,
|
||||
"change_reason": "Scanned update",
|
||||
"updated_by": "scanner_user"
|
||||
}'
|
||||
```
|
||||
|
||||
4. **Export updated inventory:**
|
||||
```bash
|
||||
curl -X GET \
|
||||
'http://localhost:3000/api/inventory/export?format=xlsx' \
|
||||
--output updated_inventory.xlsx
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `VALIDATION_ERROR` | Request validation failed |
|
||||
| `PRODUCT_NOT_FOUND` | Product does not exist |
|
||||
| `DUPLICATE_PRODUCT_CODE` | Product code already exists |
|
||||
| `INVALID_FILE_FORMAT` | Unsupported file format |
|
||||
| `FILE_TOO_LARGE` | File exceeds size limit |
|
||||
| `DATABASE_ERROR` | Database operation failed |
|
||||
| `GENERATION_ERROR` | Code generation failed |
|
||||
| `EXPORT_ERROR` | Export operation failed |
|
||||
|
||||
## Support
|
||||
|
||||
For technical support or questions about the API, please refer to the system documentation or contact the development team.
|
||||
Reference in New Issue
Block a user