docs: add Letzshop Admin Management guide
New comprehensive guide covering: - Products tab (viewing, import, export) - Orders tab overview - Exceptions tab overview - Jobs tab (all job types: import, export, historical, sync) - Settings tab configuration - API endpoints reference - Best practices and troubleshooting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
252
docs/guides/letzshop-admin-management.md
Normal file
252
docs/guides/letzshop-admin-management.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Letzshop Admin Management Guide
|
||||
|
||||
Complete guide for managing Letzshop integration from the Admin Portal at `/admin/marketplace/letzshop`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Vendor Selection](#vendor-selection)
|
||||
- [Products Tab](#products-tab)
|
||||
- [Orders Tab](#orders-tab)
|
||||
- [Exceptions Tab](#exceptions-tab)
|
||||
- [Jobs Tab](#jobs-tab)
|
||||
- [Settings Tab](#settings-tab)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Letzshop Management page provides a unified interface for managing Letzshop marketplace integration for all vendors. Key features:
|
||||
|
||||
- **Multi-Vendor Support**: Select any vendor to manage their Letzshop integration
|
||||
- **Product Management**: View, import, and export products
|
||||
- **Order Processing**: View orders, confirm inventory, set tracking
|
||||
- **Exception Handling**: Resolve product matching exceptions
|
||||
- **Job Monitoring**: Track import, export, and sync operations
|
||||
- **Configuration**: Manage CSV URLs, credentials, and sync settings
|
||||
|
||||
---
|
||||
|
||||
## Vendor Selection
|
||||
|
||||
At the top of the page, use the vendor autocomplete to select which vendor to manage:
|
||||
|
||||
1. Type to search for a vendor by name or code
|
||||
2. Select from the dropdown
|
||||
3. The page loads vendor-specific data for all tabs
|
||||
4. Your selection is saved and restored on next visit
|
||||
|
||||
**Cross-Vendor View**: When no vendor is selected, the Orders and Exceptions tabs show data across all vendors.
|
||||
|
||||
---
|
||||
|
||||
## Products Tab
|
||||
|
||||
The Products tab displays Letzshop marketplace products imported for the selected vendor.
|
||||
|
||||
### Product Listing
|
||||
|
||||
- **Search**: Filter by title, GTIN, SKU, or brand
|
||||
- **Status Filter**: Show all, active only, or inactive only
|
||||
- **Pagination**: Navigate through product pages
|
||||
|
||||
### Product Table Columns
|
||||
|
||||
| Column | Description |
|
||||
|--------|-------------|
|
||||
| Product | Image, title, and brand |
|
||||
| Identifiers | GTIN and SKU codes |
|
||||
| Price | Product price with currency |
|
||||
| Status | Active/Inactive badge |
|
||||
| Actions | View product details |
|
||||
|
||||
### Import Products
|
||||
|
||||
Click the **Import** button to open the import modal:
|
||||
|
||||
1. **Import Single Language**: Select a language and enter the CSV URL
|
||||
2. **Import All Languages**: Imports from all configured CSV URLs (FR, DE, EN)
|
||||
|
||||
Import settings (batch size) are configured in the Settings tab.
|
||||
|
||||
### Export Products
|
||||
|
||||
Click the **Export** button to export products to the Letzshop pickup folder:
|
||||
|
||||
- Exports all three languages (FR, DE, EN) automatically
|
||||
- Files are placed in `exports/letzshop/{vendor_code}/`
|
||||
- Filename format: `{vendor_code}_products_{language}.csv`
|
||||
- The export is logged and appears in the Jobs tab
|
||||
|
||||
Export settings (include inactive products) are configured in the Settings tab.
|
||||
|
||||
---
|
||||
|
||||
## Orders Tab
|
||||
|
||||
The Orders tab displays orders from Letzshop for the selected vendor (or all vendors if none selected).
|
||||
|
||||
### Order Listing
|
||||
|
||||
- **Search**: Filter by order number, customer name, or email
|
||||
- **Status Filter**: All, Pending, Confirmed, Shipped, Declined
|
||||
- **Date Range**: Filter by order date
|
||||
|
||||
### Order Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| View | Open order details modal |
|
||||
| Confirm | Confirm all items in order |
|
||||
| Decline | Decline all items in order |
|
||||
| Set Tracking | Add tracking number and carrier |
|
||||
|
||||
### Order Details Modal
|
||||
|
||||
Shows complete order information including:
|
||||
|
||||
- Order number and date
|
||||
- Customer name and email
|
||||
- Shipping address
|
||||
- Order items with confirmation status
|
||||
- Tracking information (if set)
|
||||
|
||||
---
|
||||
|
||||
## Exceptions Tab
|
||||
|
||||
The Exceptions tab shows product matching exceptions that need resolution. See the [Order Item Exceptions documentation](../implementation/order-item-exceptions.md) for details.
|
||||
|
||||
### Exception Types
|
||||
|
||||
When an order is imported and a product cannot be matched by GTIN:
|
||||
|
||||
1. The order is imported with a placeholder product
|
||||
2. An exception is created for resolution
|
||||
3. The order cannot be confirmed until exceptions are resolved
|
||||
|
||||
### Resolution Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| Resolve | Assign the correct product to the order item |
|
||||
| Bulk Resolve | Resolve all exceptions for the same GTIN |
|
||||
| Ignore | Mark as ignored (still blocks confirmation) |
|
||||
|
||||
---
|
||||
|
||||
## Jobs Tab
|
||||
|
||||
The Jobs tab provides a unified view of all Letzshop-related operations for the selected vendor.
|
||||
|
||||
### Job Types
|
||||
|
||||
| Type | Icon | Color | Description |
|
||||
|------|------|-------|-------------|
|
||||
| Product Import | Cloud Download | Purple | Importing products from Letzshop CSV |
|
||||
| Product Export | Cloud Upload | Blue | Exporting products to pickup folder |
|
||||
| Historical Import | Clock | Orange | Importing historical orders |
|
||||
| Order Sync | Refresh | Indigo | Syncing orders from Letzshop API |
|
||||
|
||||
### Job Information
|
||||
|
||||
Each job displays:
|
||||
|
||||
- **ID**: Unique job identifier
|
||||
- **Type**: Import, Export, Historical Import, or Order Sync
|
||||
- **Status**: Pending, Processing, Completed, Failed, or Partial
|
||||
- **Records**: Success count / Total processed (failed count)
|
||||
- **Started**: When the job began
|
||||
- **Duration**: How long the job took
|
||||
|
||||
### Filtering
|
||||
|
||||
- **Type Filter**: Show specific job types
|
||||
- **Status Filter**: Show jobs with specific status
|
||||
|
||||
### Job Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| View Errors | Show error details (for failed jobs) |
|
||||
| View Details | Show complete job information |
|
||||
|
||||
---
|
||||
|
||||
## Settings Tab
|
||||
|
||||
The Settings tab manages Letzshop integration configuration for the selected vendor.
|
||||
|
||||
### CSV Feed URLs
|
||||
|
||||
Configure the URLs for Letzshop product CSV feeds:
|
||||
|
||||
- **French (FR)**: URL for French product data
|
||||
- **German (DE)**: URL for German product data
|
||||
- **English (EN)**: URL for English product data
|
||||
|
||||
### Import Settings
|
||||
|
||||
- **Batch Size**: Number of products to process per batch (100-5000)
|
||||
|
||||
### Export Settings
|
||||
|
||||
- **Include Inactive**: Whether to include inactive products in exports
|
||||
|
||||
### API Credentials
|
||||
|
||||
Configure Letzshop API access:
|
||||
|
||||
- **API Key**: Your Letzshop API key (encrypted at rest)
|
||||
- **Test Connection**: Verify API connectivity
|
||||
|
||||
### Sync Settings
|
||||
|
||||
- **Auto-Sync Enabled**: Enable automatic order synchronization
|
||||
- **Sync Interval**: How often to sync orders (in minutes)
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Products
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/admin/products` | GET | List marketplace products with filters |
|
||||
| `/admin/products/stats` | GET | Get product statistics |
|
||||
| `/admin/vendors/{id}/export/letzshop` | GET | Download CSV export |
|
||||
| `/admin/vendors/{id}/export/letzshop` | POST | Export to pickup folder |
|
||||
|
||||
### Jobs
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/admin/letzshop/vendors/{id}/jobs` | GET | List jobs for vendor |
|
||||
| `/admin/marketplace-import-jobs` | POST | Create import job |
|
||||
|
||||
### Orders
|
||||
|
||||
See [Letzshop Order Integration](letzshop-order-integration.md) for complete order API documentation.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Product Management
|
||||
|
||||
1. **Regular Imports**: Schedule regular imports to keep product data current
|
||||
2. **Export Before Sync**: Export products before Letzshop's pickup schedule
|
||||
3. **Monitor Jobs**: Check the Jobs tab for failed imports/exports
|
||||
|
||||
### Order Processing
|
||||
|
||||
1. **Check Exceptions First**: Resolve exceptions before confirming orders
|
||||
2. **Verify Tracking**: Ensure tracking numbers are valid before submission
|
||||
3. **Monitor Sync Status**: Check for failed order syncs in Jobs tab
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
1. **Products Not Appearing**: Verify CSV URL is accessible and valid
|
||||
2. **Export Failed**: Check write permissions on exports directory
|
||||
3. **Orders Not Syncing**: Verify API credentials and test connection
|
||||
Reference in New Issue
Block a user