Todd/inventory-barcode-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
inventory-barcode-system/docs/API.md

9.5 KiB
Raw Permalink Blame History

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:

{
  "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:

{
  "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:

{
  "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:

{
  "product_code": "ABC123",
  "description": "Sample Product",
  "category": "Electronics",
  "unit_of_measure": "pcs"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "new_level": 150,
  "change_reason": "Stock replenishment",
  "updated_by": "user123"
}

Response:

{
  "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:

{
  "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:

{
  "product_code": "ABC123",
  "format": "CODE128",
  "width": 2,
  "height": 100,
  "displayValue": true
}

Response:

{
  "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:

{
  "product_code": "ABC123",
  "size": 200,
  "error_correction": "M",
  "include_product_info": true
}

Response:

{
  "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:

{
  "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:

{
  "code_data": "ABC123",
  "code_type": "barcode"
}

Response:

{
  "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:

{
  "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:
curl -X POST \
  http://localhost:3000/api/products/import \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@inventory.xlsx'
  1. Generate barcodes for imported products:
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
    }
  }'
  1. Update inventory after scanning:
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"
  }'
  1. Export updated inventory:
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.