`DW-Agents/dw-agents/AMAZON-PAAPI-SETUP.md`

184 lines
# Amazon Product Advertising API Setup Guide

Get REAL Amazon product data and prices for the Purchasing Office Supply Agent!

## 🎯 What You'll Get

- ✅ Real-time product prices from Amazon
- ✅ Product titles, descriptions, and images
- ✅ Customer ratings and review counts
- ✅ Direct product URLs with your affiliate tag
- ✅ Compare prices across Amazon Personal and Business

## 📋 Prerequisites

- An Amazon account (you already have two: Personal and Business)
- A website or social media presence (required by Amazon)

## 🚀 Step-by-Step Setup

### Step 1: Join Amazon Associates Program

1. **Visit Amazon Associates**
   - Go to: https://associates.amazon.com
   - Click "Sign Up" or "Join Now for Free"

2. **Account Information**
   - Use your Amazon account: `nataliaabrams@gmail.com` or `info@designerwallcoverings.com`
   - Fill in your contact information

3. **Website/App Information**
   - Add your website: `designerwallcoverings.com`
   - Or add social media: Instagram, Facebook, YouTube, etc.
   - Describe how you'll use affiliate links (e.g., "Office supply purchasing recommendations")

4. **Complete Profile**
   - Choose your preferred payment method
   - Agree to the Operating Agreement
   - Submit your application

5. **Get Your Associate ID**
   - After approval, note your **Associate ID** (e.g., `yoursite-20`)
   - This is your `PAAPI_PARTNER_TAG`

### Step 2: Request Product Advertising API Access

1. **Log into Associates Dashboard**
   - Visit: https://associates.amazon.com

2. **Navigate to API Tools**
   - Go to: **Tools** → **Product Advertising API**
   - Click **"Join Product Advertising API"** or **"Request Access"**

3. **Accept Terms**
   - Review and accept the PA-API License Agreement
   - Submit your request

4. **Get API Credentials**
   - Once approved, you'll be directed to create **AWS Access Keys**
   - Click **"Manage Your Credentials"** or **"Add Credentials"**
   - This creates:
     - **Access Key ID** (your `PAAPI_ACCESS_KEY`)
     - **Secret Access Key** (your `PAAPI_SECRET_KEY`)
   - **⚠️ IMPORTANT:** Save these immediately - you can't view the Secret Key again!

### Step 3: Configure Your Environment

1. **Copy the example environment file**
   ```bash
   cd /root/DW-Agents
   cp .env.example .env
   ```

2. **Edit .env with your credentials**
   ```bash
   nano .env
   ```

3. **Add your credentials**
   ```env
   PAAPI_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
   PAAPI_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   PAAPI_PARTNER_TAG=yoursite-20
   PAAPI_HOST=webservices.amazon.com
   PAAPI_REGION=us-east-1
   ```

4. **Save and exit** (Ctrl+O, Enter, Ctrl+X in nano)

### Step 4: Test Your Integration

```bash
cd /root/DW-Agents
npx tsx amazon-paapi-integration.ts
```

You should see real Amazon product prices!

### Step 5: Restart Purchasing Agent

```bash
pm2 restart dw-purchasing-office
```

Your purchasing agent will now fetch REAL Amazon prices! 🎉

## 🔍 Testing Individual Searches

Search for specific products:

```typescript
import { searchAmazonProducts } from './amazon-paapi-integration';

// Search for office supplies
const results = await searchAmazonProducts('printer paper', 10);
console.log(results.products);
```

## 📊 API Usage Limits

**Free Tier (Amazon Associates):**
- 1 request per second
- 8,640 requests per day
- Must generate sales to maintain API access

**Important:** Amazon requires that your affiliate links generate at least one sale within the first 180 days, then at least one sale every 365 days thereafter.

## ⚠️ Troubleshooting

### "Invalid AWS Access Key ID"
- Check that your `PAAPI_ACCESS_KEY` is correct
- Ensure no extra spaces in .env file

### "Invalid Signature"
- Verify your `PAAPI_SECRET_KEY` is correct
- Check that there are no line breaks or spaces

### "Product not found"
- Try different search terms
- Some products may be unavailable via PA-API

### "Too Many Requests"
- You've hit the rate limit (1 req/sec)
- Add delays between requests
- Cache results to reduce API calls

## 🎁 Bonus: Multi-Account Setup

To search both Personal and Business accounts:

1. Create separate Associate IDs for each account
2. Add both to your .env:
   ```env
   PAAPI_PARTNER_TAG_PERSONAL=personal-20
   PAAPI_PARTNER_TAG_BUSINESS=business-20
   ```
3. Switch partner tags when searching different accounts

## 📚 Resources

- **Amazon Associates:** https://associates.amazon.com
- **PA-API Documentation:** https://webservices.amazon.com/paapi5/documentation/
- **API Reference:** https://webservices.amazon.com/paapi5/documentation/search-items.html
- **Node.js Library:** https://www.npmjs.com/package/amazon-paapi

## 🔒 Security Notes

- ✅ Never commit .env files to git
- ✅ Keep your Secret Key private
- ✅ Rotate keys if compromised
- ✅ Use environment variables in production

## 💡 Next Steps

Once configured, your Purchasing Agent will:
1. ✅ Fetch real-time prices from Amazon
2. ✅ Compare Personal vs Business account pricing
3. ✅ Show product ratings and reviews
4. ✅ Generate affiliate links (earn commissions!)
5. ✅ Track price history and trends

---

**Questions?** Run: `npx tsx amazon-paapi-integration.ts` for setup status