Amazon Observer for Magento 2

A comprehensive Magento 2 module that synchronizes product listings from your Amazon store using the Amazon Product Advertising API (PAAPI 5.0).

Features

• Real-time Product Synchronization: Import products from Amazon using ASINs or keyword search
• Automated Updates: Scheduled cron jobs for price and inventory updates
• Image Management: Automatic download and import of Amazon product images
• Category Mapping: Map Amazon categories to Magento categories
• Admin Configuration: Complete admin interface for API credentials and settings
• Command Line Interface: CLI commands for manual synchronization
• Debug Logging: Comprehensive logging for troubleshooting
• Rate Limiting: Built-in API rate limiting to comply with Amazon's requirements

Requirements

• Magento 2.4.x
• PHP 8.1+
• Amazon Associate Account with PAAPI 5.0 access
• Valid Amazon API credentials (Access Key, Secret Key, Associate Tag)

Installation

1. Copy module files to your Magento installation:

   cp -r app/code/DanWegner/AmazonObserver /path/to/magento/app/code/DanWegner/

2. Enable the module:

   php bin/magento module:enable DanWegner_AmazonObserver
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento cache:flush

Configuration

Admin Configuration

1. Navigate to Admin Panel → Stores → Configuration → Amazon Observer

2. General Settings:

   • Enable/disable the module
   • Enable debug mode for troubleshooting

3. Amazon API Settings:

   • Access Key: Your Amazon API access key
   • Secret Key: Your Amazon API secret key
   • Associate Tag: Your Amazon associate tag (required)
   • Region: Select your Amazon marketplace region
   • Click Test Connection to verify your credentials

4. Synchronization Settings:

   • Enable automatic synchronization
   • Set sync frequency (hourly, daily, etc.)
   • Configure batch size for processing
   • Enable image import
   • Enable category mapping

Amazon API Setup

1. Amazon Associate Account:

   • Sign up for an Amazon Associate account
   • Get approved for the Product Advertising API
   • Note: You need to generate qualifying sales to maintain API access

2. API Credentials:

   • Access Key and Secret Key from AWS IAM
   • Associate Tag from your Amazon Associate account
   • Choose the appropriate region for your marketplace

Development and Testing

API Simulation Mode

The module includes a comprehensive simulation system for development and testing:

# Enable simulation mode (no real API credentials needed)
php bin/magento amazon:simulator:manage --mode=enable

# Generate test data
php bin/magento amazon:simulator:manage --generate-data

# List available test products
php bin/magento amazon:simulator:manage --list-products

# Test API functionality
php bin/magento amazon:simulator:manage --test-api

Available Test Products:

• B08N5WRWNW - Apple iPhone 13 Pro Max
• B07FZ8S74R - Echo Dot (3rd Gen)
• B0932QJ2JZ - Apple MacBook Air M1
• B08XY7G8R3 - Programming Book
• B09123ABC4 - Robot Vacuum

Simulation Features:

• No API rate limits for testing
• Predictable test data for consistent development
• Automatic random product generation for unknown ASINs
• Realistic API response structures
• Works offline without internet connectivity

See SIMULATION_GUIDE.md for detailed usage instructions.

Usage

Command Line Interface

Sync Specific Products by ASIN

# Sync single product
php bin/magento amazon:sync:products B08N5WRWNW

# Sync multiple products
php bin/magento amazon:sync:products B08N5WRWNW B07FZ8S74R B09XXXXX

# Force update existing products
php bin/magento amazon:sync:products B08N5WRWNW --force

Search and Sync by Keywords

# Search for "laptop" and sync up to 10 products
php bin/magento amazon:sync:products --keyword="laptop" --max-results=10

# Search for specific brand products
php bin/magento amazon:sync:products --keyword="Apple iPhone" --max-results=20

Automated Synchronization

The module includes three cron jobs:

• Product Sync: Daily at 2:00 AM - Full product synchronization
• Price Update: Every 6 hours - Update product prices
• Inventory Sync: Every 4 hours - Update stock status

Product Mapping

Products imported from Amazon will have:

• SKU: AMZN_[ASIN] format
• Name: Amazon product title
• Description: Amazon product features as HTML list
• Price: Current Amazon price (converted from display amount)
• Images: Primary product image downloaded and imported
• Stock: Based on Amazon availability status
• Custom Attributes:
  • amazon_asin: Original Amazon ASIN
  • manufacturer: Product brand (if available)

API Rate Limiting

The module respects Amazon PAAPI rate limits:

• New associates: 1 request per second, 8,640 requests per day
• Established associates: Higher limits based on revenue
• Built-in 1-second delay between requests
• Exponential backoff for failed requests

Troubleshooting

Enable Debug Mode

1. Go to Admin → Amazon Observer Configuration
2. Set Debug Mode to Yes
3. Check logs at var/log/amazon_observer.log

Common Issues

"Module is disabled"

• Enable the module in admin configuration
• Check ACL permissions for admin users

"API credentials not configured"

• Verify all API credentials are entered correctly
• Use the "Test Connection" button to validate
• Ensure Associate Tag is from an approved account

"Connection failed"

• Check API credentials
• Verify internet connectivity
• Confirm selected region matches your marketplace
• Check if your Associate account is approved for PAAPI

"Rate limit exceeded"

• Wait for rate limit to reset (usually 24 hours for daily limits)
• Reduce batch sizes in configuration
• Implement longer delays between requests

Log Files

Check these log locations:

• Application logs: var/log/system.log
• Amazon Observer logs: var/log/amazon_observer.log (if custom logging is enabled)
• Exception logs: var/log/exception.log

Development

Module Structure

app/code/DanWegner/AmazonObserver/
├── Api/                           # Service contracts
├── Block/                         # Admin UI blocks
├── Console/Command/               # CLI commands
├── Controller/Adminhtml/          # Admin controllers
├── Cron/                         # Cron job classes
├── etc/                          # Configuration files
├── Helper/                       # Helper classes
├── Model/                        # Business logic models
├── view/adminhtml/               # Admin templates
├── registration.php              # Module registration
└── README.md                     # This file

Extending the Module

To add custom functionality:

1. Custom Attributes: Extend the attribute mapping in ProductSyncService
2. Category Mapping: Implement custom logic in syncProductCategories()
3. Product Filters: Add filters in syncProductsByKeyword()
4. Custom APIs: Extend AmazonApiService for additional endpoints

License

This module is provided as-is for educational and development purposes. Please ensure compliance with Amazon's API terms of service and your Associate agreement.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review Amazon PAAPI documentation
3. Verify your Amazon Associate account status
4. Check Magento logs for detailed error messages

Quick Start with Simulation

For immediate testing without Amazon API credentials:

1. Enable simulation mode:

   php bin/magento amazon:simulator:manage --mode=enable

2. Test product sync:

   php bin/magento amazon:sync:products B08N5WRWNW

3. Test keyword search:

   php bin/magento amazon:sync:products --keyword="iphone" --max-results=5

4. Check results in your Magento admin catalog

Version History

• 1.0.0: Initial release with core functionality
  • Amazon PAAPI 5.0 integration
  • Product synchronization
  • Admin configuration interface
  • CLI commands
  • Automated cron jobs
  • API Simulation System - Complete development/testing environment
  • Test Data Generator - Realistic mock data for development
  • Proxy Architecture - Seamless switching between real and simulated APIs