Warehouse Stock

API Documentation

Overview

Welcome to the Warehouse Stock Management System API documentation. This API provides a comprehensive solution for managing inventory, products, and transactions in a warehouse environment.

Products Management

Create, read, update, and delete product information including SKUs, and descriptions.

Inventory Control

Track stock levels for each product.

Transaction

Record all stock movements including receipts and orders.

Setup & Installation

🚀 Quick Start with Docker

1. Clone the repository

git clone https://github.com/ekayudinata/warehouse-stock-management-app.git
cd warehouse-stock-management-app

2. Copy environment file

cp .env.example .env

3. Start Docker containers

docker-compose -f docker/warehouse-stock/docker-compose.yml up -d

3. Access container

docker exec -it --user=root warehouse_stock_php_fpm bash

4. Install PHP dependencies

composer install

5. Generate application key

php artisan key:generate

6. Access mysql bash

docker exec -it --user=root warehouse_stock_mysql bash

6. Create database

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS warehouse_stock_management_app;"

7. Run migrations and seeders

php artisan migrate --seed

8. Set storage permissions

chown -R www-data:www-data storage bootstrap/cache

🔧 Manual Setup

Prerequisites

  • PHP 8.1+
  • Composer
  • MySQL 5.7+

1. Clone the repository

git clone https://github.com/ekayudinata/warehouse-stock-management-app.git
cd warehouse-stock-management-app

2. Install PHP dependencies

composer install

3. Configure environment

Copy the example env file and generate application key:

cp .env.example .env
php artisan key:generate

Update the .env file with your database credentials and other settings.

5. Run migrations and seeders

php artisan migrate --seed

6. Start the development server

php artisan serve

Your application should now be running at http://localhost:8000

Authentication

The API uses Laravel Sanctum for authentication. To authenticate your requests, include the API token in the Authorization header.

Obtaining an API Token

Include your email and password to obtain an API token: 

curl -X POST http://localhost:8000/api/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "testUser@example.com", "password": "password"}'

Test User Credentials:
Email: testUser@example.com
Password: password

Using the API Token

Include the token in the Authorization header for authenticated requests: 

curl -X GET http://localhost:8000/api/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API Documentation

Products

GET /api/v1/products

Retrieve a list of all products with pagination.

Example Request

curl -X GET http://localhost:8000/api/v1/products \
  -H "Accept: application/json"

Example Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "sku": "test",
            "name": "data",
            "description": "Test",
            "unit_price": "800.00",
            "created_at": "2025-09-19T04:09:22.000000Z",
            "updated_at": "2025-10-29T11:53:07.000000Z"
        },
        {
            "id": 2,
            "sku": "NET-9623",
            "name": "LG Network Cable 3325",
            "description": "Non occaecati ducimus eligendi vel voluptas facere error aut illum iure ea iste sapiente accusantium est porro.",
            "unit_price": "276.28",
            "created_at": "2025-06-24T13:53:11.000000Z",
            "updated_at": "2025-02-01T21:17:14.000000Z"
        }
    ],
    "pagination": {
        "total": 25,
        "per_page": 15,
        "current_page": 1,
        "last_page": 2,
        "from": 1,
        "to": 15
    }
}
POST /api/v1/products

Create a new product.

Request Body

{
  "sku": "PROD-00123",
  "name": "Premium Wireless Headphones",
  "description": "High-quality wireless headphones with noise cancellation",
  "unit_price": 199.99
}

Example Request

curl -X POST http://localhost:8000/api/v1/products \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"sku":"PROD-00123","name":"Premium Wireless Headphones","description":"High-quality wireless headphones with noise cancellation","unit_price":199.99}'

Example Response (201 Created)

{
  "status": "success",
  "message": "Product created successfully",
  "data": {
    "id": 101,
    "sku": "PROD-00123",
    "name": "Premium Wireless Headphones",
    "description": "High-quality wireless headphones with noise cancellation",
    "unit_price": "199.99",
    "created_at": "2025-10-29T15:30:00.000000Z",
    "updated_at": "2025-10-29T15:30:00.000000Z"
  }
}
PUT /api/v1/products/{product}

Update an existing product. All fields are optional, but at least one field must be provided.

URL Parameters

Parameter
Type
Description
product
integer
ID of the product to update

Request Body

{
  "name": "Premium Wireless Headphones (Updated)",
  "description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life",
  "unit_price": 219.99
}

Example Request

curl -X PUT http://localhost:8000/api/v1/products/101 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"name":"Premium Wireless Headphones (Updated)","description":"High-quality wireless headphones with active noise cancellation and 30-hour battery life","unit_price":219.99}'

Example Response (200 OK)

{
  "status": "success",
  "message": "Product updated successfully",
  "data": {
    "id": 101,
    "sku": "PROD-00123",
    "name": "Premium Wireless Headphones (Updated)",
    "description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life",
    "unit_price": "219.99",
    "created_at": "2025-10-29T15:30:00.000000Z",
    "updated_at": "2025-10-29T16:45:22.000000Z"
  }
}
DELETE /api/v1/products/{product}

Delete a product from the system. This action cannot be undone.

URL Parameters

Parameter
Type
Description
product
integer
ID of the product to delete

Example Request

curl -X DELETE http://localhost:8000/api/v1/products/101 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response (200 OK)

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

Error Response (404 Not Found)

{
  "status": "error",
  "message": "Product not found"
}

Transactions

POST /api/v1/transactions

Record a new inventory transaction (stock in/out).

Request Body

{
  "product_id": 1,
  "quantity": 10,
  "type": "in",
  "note": "Received new stock"
}

Example Request

curl -X POST http://localhost:8000/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"product_id":1,"quantity":10,"type":"in","note":"Received new stock"}'

Example Response (201 Created)

{
  "status": "success",
  "message": "Transaction created successfully",
  "data": {
    "id": 1,
    "product_id": 1,
    "quantity": 10,
    "type": "in",
    "note": "Received new stock",
    "user_id": 1,
    "created_at": "2025-10-29T15:45:00.000000Z",
    "updated_at": "2025-10-29T15:45:00.000000Z",
    "product": {
      "id": 1,
      "sku": "PROD-00123",
      "name": "Premium Wireless Headphones",
      "description": "High-quality wireless headphones with noise cancellation",
      "unit_price": "199.99",
      "created_at": "2025-10-29T15:30:00.000000Z",
      "updated_at": "2025-10-29T15:30:00.000000Z"
    }
  },
  "inventory": {
    "product_id": 1,
    "new_quantity": 10
  }
}

Error Response (422 Unprocessable Entity)

{
  "status": "error",
  "message": "Validation error",
  "errors": {
    "product_id": [
      "The product id field is required."
    ],
    "quantity": [
      "The quantity field is required."
    ],
    "type": [
      "The selected type is invalid."
    ]
  }
}

Error Response (500 Internal Server Error)

{
  "status": "error",
  "message": "Insufficient stock for this transaction"
}

Request Fields

Field
Type
Required
Description
product_id
integer
Yes
ID of the product for the transaction
quantity
integer
Yes
Number of items (must be greater than 0)
type
string
Yes
Transaction type: 'in' for stock in, 'out' for stock out
note
string
No
Optional note about the transaction (max 500 chars)

GraphQL API

Interact with the inventory system using GraphQL. All GraphQL requests should be sent as POST requests to /graphql endpoint.

QUERY Get All Products

GraphQL Query

query {
  products {
    id
    sku
    name
    description
    unit_price
    created_at
    updated_at
  }
}

Example Request

curl -X POST http://localhost:8000/graphql \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"query":"{products{id sku name description unit_price created_at updated_at}}"}'

Example Response

{
  "data": {
    "products": [
      {
        "id": "1",
        "sku": "PROD-00123",
        "name": "Premium Wireless Headphones",
        "description": "High-quality wireless headphones with noise cancellation",
        "unit_price": 199.99,
        "created_at": "2025-10-29T15:30:00.000000Z",
        "updated_at": "2025-10-29T15:30:00.000000Z"
      },
      {
        "id": "2",
        "sku": "KB-00456",
        "name": "Mechanical Keyboard",
        "description": "RGB mechanical keyboard with blue switches",
        "unit_price": 129.99,
        "created_at": "2025-10-28T10:15:30.000000Z",
        "updated_at": "2025-10-28T10:15:30.000000Z"
      }
    ]
  }
}

Available Types

Type
Fields
Type
Description
Product
id
ID!
Unique identifier
sku
String!
Stock Keeping Unit
name
String!
Product name
description
String
Product description
unit_price
Float!
Price per unit

Error Handling

The API returns standard HTTP response codes to indicate the success or failure of an API request.

Code Status Description
200 OK The request was successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Authentication failed or not provided
403 Forbidden Insufficient permissions
404 Not Found Resource not found
422 Unprocessable Entity Validation errors occurred
500 Internal Server Error Server error occurred

Error Response Format

When an error occurs, the API returns a JSON object with error details: 

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ]
  }
}