docs: migrate module documentation to single source of truth
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
322
app/modules/marketplace/docs/api.md
Normal file
322
app/modules/marketplace/docs/api.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# Letzshop Marketplace Integration
|
||||
|
||||
## Introduction
|
||||
|
||||
This guide covers the Orion platform's integration with the Letzshop marketplace, including:
|
||||
|
||||
- **Product Export**: Generate Letzshop-compatible CSV files from your product catalog
|
||||
- **Order Import**: Fetch and manage orders from Letzshop
|
||||
- **Fulfillment Sync**: Confirm/reject orders, set tracking numbers
|
||||
- **GraphQL API Reference**: Direct API access for advanced use cases
|
||||
|
||||
---
|
||||
|
||||
## Product Export
|
||||
|
||||
### Overview
|
||||
|
||||
The Orion platform can export your products to Letzshop-compatible CSV format (Google Shopping feed format). This allows you to:
|
||||
|
||||
- Upload your product catalog to Letzshop marketplace
|
||||
- Generate feeds in multiple languages (English, French, German)
|
||||
- Include all required Letzshop fields automatically
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### Store Export
|
||||
|
||||
```http
|
||||
GET /api/v1/store/letzshop/export?language=fr
|
||||
Authorization: Bearer <store_token>
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `language` | string | `en` | Language for title/description (`en`, `fr`, `de`) |
|
||||
| `include_inactive` | bool | `false` | Include inactive products |
|
||||
|
||||
**Response:** CSV file download (`store_code_letzshop_export.csv`)
|
||||
|
||||
#### Admin Export
|
||||
|
||||
```http
|
||||
GET /api/v1/admin/letzshop/export?store_id=1&language=fr
|
||||
Authorization: Bearer <admin_token>
|
||||
```
|
||||
|
||||
**Additional Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `store_id` | int | Required. Store ID to export |
|
||||
|
||||
### CSV Format
|
||||
|
||||
The export generates a tab-separated CSV file with these columns:
|
||||
|
||||
| Column | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `id` | Product SKU | `PROD-001` |
|
||||
| `title` | Product title (localized) | `Wireless Headphones` |
|
||||
| `description` | Product description (localized) | `High-quality...` |
|
||||
| `link` | Product URL | `https://shop.example.com/product/123` |
|
||||
| `image_link` | Main product image | `https://cdn.example.com/img.jpg` |
|
||||
| `additional_image_link` | Additional images (comma-separated) | `img2.jpg,img3.jpg` |
|
||||
| `availability` | Stock status | `in stock` / `out of stock` |
|
||||
| `price` | Regular price with currency | `49.99 EUR` |
|
||||
| `sale_price` | Sale price with currency | `39.99 EUR` |
|
||||
| `brand` | Brand name | `TechBrand` |
|
||||
| `gtin` | Global Trade Item Number | `0012345678901` |
|
||||
| `mpn` | Manufacturer Part Number | `TB-WH-001` |
|
||||
| `google_product_category` | Google category ID | `Electronics > Audio` |
|
||||
| `condition` | Product condition | `new` / `used` / `refurbished` |
|
||||
| `atalanda:tax_rate` | Luxembourg VAT rate | `17` |
|
||||
|
||||
### Multi-Language Support
|
||||
|
||||
Products are exported with localized content based on the `language` parameter:
|
||||
|
||||
```bash
|
||||
# French export
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/store/letzshop/export?language=fr"
|
||||
|
||||
# German export
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/store/letzshop/export?language=de"
|
||||
|
||||
# English export (default)
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://api.example.com/api/v1/store/letzshop/export?language=en"
|
||||
```
|
||||
|
||||
If a translation is not available for the requested language, the system falls back to English, then to any available translation.
|
||||
|
||||
### Using the Export
|
||||
|
||||
1. **Navigate to Letzshop** in your store dashboard
|
||||
2. **Click the Export tab**
|
||||
3. **Select your language** (French, German, or English)
|
||||
4. **Click "Download CSV"**
|
||||
5. **Upload to Letzshop** via their merchant portal
|
||||
|
||||
---
|
||||
|
||||
## Order Integration
|
||||
|
||||
For details on order import and fulfillment, see [Letzshop Order Integration](order-integration.md).
|
||||
|
||||
---
|
||||
|
||||
## Letzshop GraphQL API Reference
|
||||
|
||||
The following sections document the Letzshop GraphQL API for direct integration.
|
||||
|
||||
---
|
||||
|
||||
## GraphQL API
|
||||
|
||||
Utilizing this API, you can retrieve and modify data on products, stores, and shipments. Letzshop uses GraphQL, allowing for precise queries.
|
||||
|
||||
**Endpoint**:
|
||||
http://letzshop.lu/graphql
|
||||
Replace YOUR_API_ACCESS_KEY with your actual key or remove the Authorization header for public data.
|
||||
|
||||
## Authentication
|
||||
|
||||
Some data is public (e.g., store description and product prices).
|
||||
For protected operations (e.g., orders or vouchers), an API key is required.
|
||||
|
||||
Request one via your account manager or email: support@letzshop.lu
|
||||
|
||||
|
||||
Include the key:
|
||||
|
||||
|
||||
Authorization: Bearer YOUR_API_ACCESS_KEY
|
||||
|
||||
---
|
||||
|
||||
## Playground
|
||||
|
||||
- Access the interactive GraphQL Playground via the Letzshop website.
|
||||
- It provides live docs, auto-complete (CTRL + Space), and run-time testing.
|
||||
- **Caution**: You're working on production—mutations like confirming orders are real. [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
## Deprecations
|
||||
|
||||
The following GraphQL fields will be removed soon:
|
||||
|
||||
| Type | Field | Replacement |
|
||||
|---------|---------------------|----------------------------------|
|
||||
| Event | latitude, longitude | `#lat`, `#lng` |
|
||||
| Greco | weight | `packages.weight` |
|
||||
| Product | ageRestriction | `_age_restriction` (int) |
|
||||
| Taxon | identifier | `slug` |
|
||||
| User | billAddress, shipAddress | on `orders` instead |
|
||||
| Store | facebookLink, instagramLink, twitterLink, youtubeLink | `social_media_links` |
|
||||
| Store | owner | `representative` |
|
||||
| Store | permalink | `slug` | [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
## Order Management via API
|
||||
|
||||
Using the API, you can:
|
||||
|
||||
- Fetch unconfirmed orders
|
||||
- Confirm or reject them
|
||||
- Set tracking numbers
|
||||
- Handle returns
|
||||
|
||||
All of this requires at least "shop manager" API key access. Multi-store management is supported if rights allow. [1](https://letzshop.lu/en/dev)
|
||||
|
||||
### 1. Retrieve Unconfirmed Shipments
|
||||
|
||||
**Query:**
|
||||
```graphql
|
||||
query {
|
||||
shipments(state: unconfirmed) {
|
||||
nodes {
|
||||
id
|
||||
inventoryUnits {
|
||||
id
|
||||
state
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
``` [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
### 2. Confirm/Reject Inventory Units
|
||||
|
||||
Use inventoryUnit IDs to confirm or reject:
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
confirmInventoryUnits(input: {
|
||||
inventoryUnits: [
|
||||
{ inventoryUnitId: "ID1", isAvailable: true },
|
||||
{ inventoryUnitId: "ID2", isAvailable: false },
|
||||
{ inventoryUnitId: "ID3", isAvailable: false }
|
||||
]
|
||||
}) {
|
||||
inventoryUnits {
|
||||
id
|
||||
state
|
||||
}
|
||||
errors {
|
||||
id
|
||||
code
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
``` [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
### 3. Handle Customer Returns
|
||||
|
||||
Use only after receiving returned items:
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
returnInventoryUnits(input: {
|
||||
inventoryUnits: [
|
||||
{ inventoryUnitId: "ID1" },
|
||||
{ inventoryUnitId: "ID2" }
|
||||
]
|
||||
}) {
|
||||
inventoryUnits {
|
||||
id
|
||||
state
|
||||
}
|
||||
errors {
|
||||
id
|
||||
code
|
||||
}
|
||||
}
|
||||
}
|
||||
``` [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
### 4. Set Shipment Tracking Number
|
||||
|
||||
Include shipping provider and tracking code:
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
setShipmentTracking(input: {
|
||||
shipmentId: "SHIPMENT_ID",
|
||||
code: "TRACK123",
|
||||
provider: THE_SHIPPING_PROVIDER
|
||||
}) {
|
||||
shipment {
|
||||
tracking {
|
||||
code
|
||||
provider
|
||||
}
|
||||
}
|
||||
errors {
|
||||
code
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
``` [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
## Event System
|
||||
|
||||
Subscribe by contacting support@letzshop.lu. Events are delivered via an SNS-like message structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"Type": "Notification",
|
||||
"MessageId": "XXX",
|
||||
"TopicArn": "arn:aws:sns:eu-central-1:XXX:events",
|
||||
"Message": "{\"id\":\"XXX\",\"type\":\"XXX\",\"payload\":{...}}",
|
||||
"Timestamp": "2019-01-01T00:00:00.000Z",
|
||||
"SignatureVersion": "1",
|
||||
"Signature": "XXX",
|
||||
"SigningCertURL": "...",
|
||||
"UnsubscribeURL": "..."
|
||||
}
|
||||
``` [1](https://letzshop.lu/en/dev)
|
||||
|
||||
### Message Payload
|
||||
|
||||
Each event includes:
|
||||
|
||||
- `id`
|
||||
- `type` (e.g., ShipmentConfirmed, UserCreated…)
|
||||
- `payload` (object-specific data) [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
## Event Types & Payload Structure
|
||||
|
||||
A variety of event types are supported. Common ones include:
|
||||
|
||||
- `ShipmentConfirmed`, `ShipmentRefundCreated`
|
||||
- `UserAnonymized`, `UserCreated`, `UserDestroyed`, `UserUpdated`
|
||||
- `VariantWithPriceCrossedCreated`, `...Updated`
|
||||
- `StoreCategoryCreated`, `Destroyed`, `Updated`
|
||||
- `StoreCreated`, `Destroyed`, `Updated`
|
||||
|
||||
Exact payload structure varies per event type. [1](https://letzshop.lu/en/dev)
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
This Markdown file captures all information from the Letzshop development page, formatted for use in your documentation or GitHub.
|
||||
Reference in New Issue
Block a user