orion/docs/guides/letzshop-admin-management.md

# Letzshop Admin Management Guide

Complete guide for managing Letzshop integration from the Admin Portal at `/admin/marketplace/letzshop`.

## Table of Contents

- [Overview](#overview)
- [Store Selection](#store-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 stores. Key features:

- **Multi-Store Support**: Select any store 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

---

## Store Selection

At the top of the page, use the store autocomplete to select which store to manage:

1. Type to search for a store by name or code
2. Select from the dropdown
3. The page loads store-specific data for all tabs
4. Your selection is saved and restored on next visit

**Cross-Store View**: When no store is selected, the Orders and Exceptions tabs show data across all stores.

---

## Products Tab

The Products tab displays Letzshop marketplace products imported for the selected store.

### 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/{store_code}/`
- Filename format: `{store_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 store (or all stores 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 store.

### 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 if any)
- **Started**: When the job began
- **Duration**: How long the job took

#### Records Column Meaning

| Job Type | Records Shows |
|----------|---------------|
| Product Import | Products imported / Total products |
| Product Export | Files exported / Total files (3 languages) |
| Historical Import | Orders imported / Total orders |
| Order Sync | Orders synced / Total orders |

### 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 store.

### 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/letzshop/stores/{id}/export` | GET | Download CSV export |
| `/admin/letzshop/stores/{id}/export` | POST | Export to pickup folder |

### Jobs

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/admin/letzshop/stores/{id}/jobs` | GET | List jobs for store |
| `/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