Quick Start

Clone the platform repository and move into its root directory.

git clone https://github.com/Wally-And-Cody/Shopee_AutoRedeemer_v2.git
cd Shopee_AutoRedeemer_v2

Your terminal is now positioned in the repository root, where the Docker Compose configuration is located.

Each service provides an .env.example file. Copy each template to the corresponding .env file before starting the stack.

cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/admin/.env.example frontend/admin/.env
cp frontend/public/.env.example frontend/public/.env

Set the following critical variables. Keep secrets out of version control.

• Root**.env**: POSTGRES_USER, POSTGRES_PASSWORD
• backend/.env: JWT_SECRET_KEY with at least 32 characters, JWT_REFRESH_SECRET_KEY with at least 32 characters, PG_PASSWORD, SHOPEE_ENVIRONMENT_HOSTNAME, SHOPEE_REDIRECT_URI, ALLOWED_CORS_HOSTNAMES, PUBLIC_REDEMPTION_PORTAL_HOSTNAME
• frontend/admin/.env: VITE_BACKEND_API_HOSTNAME=http://localhost:8080
• frontend/public/.env: VITE_BACKEND_API_HOSTNAME=http://localhost:8080

Confirm that every service has a populated .env file before continuing.

Start the services in detached mode.

docker-compose up -d

Docker Compose starts Redis on port 6379, PostgreSQL on port 5435, the backend on port 8080, and the worker. The worker starts automatically when TOKEN_REFRESH_WORKER=true is set in backend/.env.

Check the running containers with docker-compose ps. Each required service should report a running or healthy status.

Use the sellers endpoint to create an administrator account, then log in to obtain a JWT.

# Create an admin seller
curl -X POST http://localhost:8080/api/sellers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "securepassword",
    "name": "Admin User",
    "role": "ADMIN"
  }'

# Login to get a JWT
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "securepassword"
  }'

Save the JWT from the login response. Use it in the Authorization header for the remaining seller and shop requests.

Register the Shopee shop against the seller account. Replace the partner credentials and shop ID with values from your Shopee Open Platform account.

curl -X POST http://localhost:8080/api/shops \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_JWT>" \
  -d '{
    "seller_id": 1,
    "shopee_partner_id": "123456",
    "shopee_partner_key": "your-partner-key",
    "shopee_shop_id": "67890"
  }'

A successful response confirms that the shop is associated with seller ID 1.

Request the Shopee authorization URL for the shop.

curl "http://localhost:8080/api/token/auth-url?shop_id=1" \
  -H "Authorization: Bearer <YOUR_JWT>"

Open the returned authorization URL in a browser and approve access in Shopee. Shopee redirects to the configured callback URL, where the platform stores the shop's access and refresh tokens.

After the redirect completes, the shop is authorized for product and order operations.

Run the initial product sync in full mode. Use the JWT from the login response.

curl "http://localhost:8080/api/sync-products?mode=full&shop_id=1" \
  -H "Authorization: Bearer <YOUR_JWT>"

Use mode=incremental for later syncs. Poll the sync status endpoint while the job runs.

curl "http://localhost:8080/api/sync-products/status?shop_id=1" \
  -H "Authorization: Bearer <YOUR_JWT>"

Continue when the status response shows that the product sync has completed.

Assign the redemption destination to a synced product.

curl -X POST http://localhost:8080/api/products/1/redeem_url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_JWT>" \
  -d '{"redeem_url": "https://example.com/redeem"}'

A successful response confirms that product ID 1 has a redemption URL.

Submit a Shopee order ID to the redemption endpoint.

curl -X POST http://localhost:8080/api/redemption \
  -H "Content-Type: application/json" \
  -d '{"order_id": "240101ABCDEF123"}'

The response contains a response array with redemption entries and a warnings array. An empty warnings array indicates that the test completed without reported issues.