From 6e0eb679d9659b07521d24466feb7a7ddb4cf840 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sat, 20 Dec 2025 22:56:54 +0100 Subject: [PATCH] docs: add Letzshop Admin Management guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/guides/letzshop-admin-management.md | 252 +++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 253 insertions(+) create mode 100644 docs/guides/letzshop-admin-management.md diff --git a/docs/guides/letzshop-admin-management.md b/docs/guides/letzshop-admin-management.md new file mode 100644 index 00000000..6ad505c7 --- /dev/null +++ b/docs/guides/letzshop-admin-management.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index cb8fccf4..7aa57ae8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -198,6 +198,7 @@ nav: - CSV Import: guides/csv-import.md - Marketplace Integration: guides/marketplace-integration.md - Letzshop: + - Admin Management: guides/letzshop-admin-management.md - Order Integration: guides/letzshop-order-integration.md - Marketplace API: guides/letzshop-marketplace-api.md