docs: add Letzshop marketplace API documentation

Document the Letzshop GraphQL API including: - GraphQL endpoint and authentication - Order management and event system - Data structures and example queries 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-12 22:37:43 +01:00
parent 2b899d5a52
commit 66d359b7f8
1 changed files with 221 additions and 0 deletions
--- a/docs/guides/letzshop-marketplace-api.md
+++ b/docs/guides/letzshop-marketplace-api.md
@@ -0,0 +1,221 @@
+
+# Letzshop Development Documentation
+
+## Introduction
+
+Welcome to the Letzshop Development page. Here you’ll find details on:
+
+- GraphQL API
+- Authentication
+- Playground
+- Deprecations
+- Order management
+- Event system
+- Data structures [1](https://letzshop.lu/en/dev)
+
+---
+
+## GraphQL API
+
+Utilizing this API, you can retrieve and modify data on products, vendors, 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., vendor 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         |
+| Vendor  | facebookLink, instagramLink, twitterLink, youtubeLink | `social_media_links` |
+| Vendor  | owner               | `representative`                |
+| Vendor  | 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-vendor 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`  
+- `VendorCategoryCreated`, `Destroyed`, `Updated`  
+- `VendorCreated`, `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.