apskel-pos-backend/test_voucher_api.md

Voucher API Test Guide

API Endpoints

1. Get Random Vouchers for Spin

GET /api/v1/vouchers/spin

Query Parameters:

• limit (optional): Number of vouchers to return (1-50, default: 10)

Response:

{
  "message": "Success",
  "data": {
    "vouchers": [
      {
        "voucher_code": "VOUCHER001",
        "name": "John Doe",
        "phone_number": "08**1234",
        "is_winner": false
      },
      {
        "voucher_code": "VOUCHER002",
        "name": "Jane Smith",
        "phone_number": "09**5678",
        "is_winner": false
      }
    ],
    "count": 2
  }
}

2. Get Random Vouchers by Rows (UPDATED!)

GET /api/v1/vouchers/rows

Query Parameters:

• rows (optional): Number of rows to return (1-10, default: 4)
• winner_number (optional): Winner number to filter by (if not provided, defaults to 0)

Logic:

• If winner_number is provided: Randomly select from vouchers where winner_number = provided_value AND is_winner = false
• If no vouchers found for the specified winner_number: Fallback to winner_number = 0 AND is_winner = false
• If winner_number is not provided: Randomly select from vouchers where winner_number = 0 AND is_winner = false
• Excludes vouchers already marked as winners
• Distributes vouchers evenly across the specified number of rows
• Automatically selects one random winner from each row and sets their is_winner to true

Response:

{
  "message": "Success",
  "data": {
    "rows": [
      {
        "row_number": 1,
        "vouchers": [
          {
            "voucher_code": "VOUCHER001",
            "name": "John Doe",
            "phone_number": "08**1234",
            "is_winner": true
          },
          {
            "voucher_code": "VOUCHER002",
            "name": "Jane Smith",
            "phone_number": "09**5678",
            "is_winner": false
          },
          {
            "voucher_code": "VOUCHER003",
            "name": "Bob Johnson",
            "phone_number": "08**9012",
            "is_winner": false
          }
        ]
      },
      {
        "row_number": 2,
        "vouchers": [
          {
            "voucher_code": "VOUCHER004",
            "name": "Alice Brown",
            "phone_number": "09**3456",
            "is_winner": false
          },
          {
            "voucher_code": "VOUCHER005",
            "name": "Charlie Wilson",
            "phone_number": "08**7890",
            "is_winner": true
          }
        ]
      }
    ],
    "total_rows": 2,
    "total_vouchers": 5
  }
}

3. List All Vouchers

GET /api/v1/vouchers

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10, max: 100)

Response:

{
  "message": "Success",
  "data": {
    "data": [
      {
        "id": "uuid",
        "name": "John Doe",
        "email": "john@example.com",
        "phone_number": "08123456789",
        "voucher_code": "VOUCHER001",
        "winner_number": 1,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total_count": 1,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

4. Get Voucher by ID

GET /api/v1/vouchers/{id}

Response:

{
  "message": "Success",
  "data": {
    "id": "uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "08123456789",
    "voucher_code": "VOUCHER001",
    "winner_number": 1,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

5. Get Voucher by Code

GET /api/v1/vouchers/code/{code}

Response:

{
  "message": "Success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "08123456789",
    "voucher_code": "VOUCHER001",
    "winner_number": 1,
    "is_winner": false
  }
}

Features

1. Random Selection: The /spin endpoint returns random vouchers from the database
2. Phone Number Masking: Phone numbers are masked for privacy (shows first 2 and last 2 digits)
3. Pagination: List endpoint supports pagination
4. Authentication: All endpoints require admin or manager role
5. Validation: Input validation for limit parameters

Database Schema

CREATE TABLE vouchers (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL,
    phone_number VARCHAR(20) NOT NULL,
    voucher_code VARCHAR(50) NOT NULL,
    winner_number INT NOT NULL DEFAULT 0,
    is_winner BOOLEAN NOT NULL DEFAULT FALSE
);

Usage Examples

# Get 5 random vouchers for spin
curl -X GET "http://localhost:8080/api/v1/vouchers/spin?limit=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 4 rows (default) - vouchers distributed evenly across rows
curl -X GET "http://localhost:8080/api/v1/vouchers/rows" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers distributed evenly across 3 rows (from winner_number = 0)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers from winner_number = 1 (fallback to winner_number = 0 if none found)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3&winner_number=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers from winner_number = 5 (will fallback to winner_number = 0 if none found)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3&winner_number=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# List all vouchers with pagination
curl -X GET "http://localhost:8080/api/v1/vouchers?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"