Feld-Mapping Dokumentation: reybex → Etsy
Übersicht
Diese Dokumentation beschreibt, welche Felder von reybex nach Etsy übertragen werden und wie sie gemappt werden. Die Übertragung erfolgt über die Etsy REST API.
⚠️ WICHTIGER HINWEIS
Diese Dokumentation unterliegt kontinuierlichen Änderungen.
Die Integration zwischen reybex und Etsy befindet sich in ständiger Entwicklung. Daher kann es vorkommen, dass:
- Neue Felder hinzugefügt werden - Um zusätzliche Funktionen zu unterstützen oder neue Etsy-Features zu nutzen
- Felder temporär entfernt werden - Wenn unerwartete Probleme auftreten, die negative Auswirkungen auf die Artikel haben
Empfehlung:
Bitte überprüfen Sie regelmäßig die aktuelle Dokumentation und testen Sie Änderungen in einer Testumgebung, bevor Sie sie in der Produktion einsetzen.
Verwendung dieser Dokumentation
Diese Dokumentation zeigt, welche Felder von reybex nach Etsy übertragen werden. Für jedes Etsy-Feld wird angegeben:
- Welches reybex-Feld die Quelle ist
- Unter welcher Bedingung es übertragen wird (Export-Gruppe)
- Besondere Hinweise zur Übertragung
Wichtige Konzepte
reybex-Artikelstruktur
- Material: Ein Artikel/Produkt in reybex (entspricht Etsy Listing)
- MaterialVariant: Eine Variante eines Artikels in reybex (z.B. Größe, Farbe)
- MaterialMarktplace: Marktplatz-spezifische Einstellungen für einen Artikel
Etsy-Produktstruktur
- Listing: Das Produktangebot in Etsy
- Inventory: Der Bestand und Preis in Etsy
- Product: Die Variante in Etsy
- REST API:
POST /shops/{shopId}/listingsoderPUT /shops/{shopId}/listings/{listingId}(x-www-form-urlencoded)
1. Produkt-Felder (Listing Level)
Die folgenden Felder werden auf Listing-Ebene in Etsy übertragen:
1.1 Basis-Informationen
| Etsy Feld | reybex Feld | Beschreibung | Bedingung |
|---|---|---|---|
listing.title |
material.name |
Produkttitel | Immer |
listing.description |
material.description oder material.name |
Produktbeschreibung | Immer |
listing.taxonomy_id |
material.categories[0].id |
Kategorie-ID | Immer |
listing.shipping_profile_id |
material.shipping.policyProfile.shippingPolicyId oder automatisch |
Versandprofil-ID | Immer |
listing.who_made |
Immer "i_did" |
Hersteller | Immer |
listing.when_made |
Aktuelles Jahr - 2 bis aktuelles Jahr | Herstellungsjahr | Immer |
listing.is_supply |
Immer "1" |
Ist Zubehör | Immer |
listing.state |
Immer "active" |
Status | Immer |
listing.type |
"download" wenn kein Versandprofil |
Typ | Wenn kein Versandprofil |
1.2 Bilder
| Etsy Feld | reybex Feld | Beschreibung | Bedingung |
|---|---|---|---|
listing.images[] |
material.images.image[] |
Produktbilder | Wenn IMAGE Export-Gruppe |
2. Bestand und Preis (Inventory Level)
Die folgenden Felder werden auf Inventory-Ebene in Etsy übertragen:
2.1 Einfache Artikel (ohne Varianten)
| Etsy Feld | reybex Feld | Beschreibung | Bedingung |
|---|---|---|---|
inventory.products[].sku |
material.sku |
Artikelnummer | Wenn SKU Export-Gruppe |
inventory.products[].offerings[].price |
material.price.value |
Preis | Wenn PRICE Export-Gruppe |
inventory.products[].offerings[].quantity |
material.stock.value |
Bestand | Wenn STOCK Export-Gruppe |
inventory.products[].offerings[].is_enabled |
Immer true |
Aktiviert | Immer |
2.2 Varianten-Artikel
| Etsy Feld | reybex Feld | Beschreibung | Bedingung |
|---|---|---|---|
inventory.products[].sku |
variant.sku oder variant.marketplaceVariantId |
Varianten-SKU | Wenn SKU Export-Gruppe |
inventory.products[].offerings[].price |
variant.price.value |
Varianten-Preis | Wenn PRICE Export-Gruppe |
inventory.products[].offerings[].quantity |
variant.stock |
Varianten-Bestand | Wenn STOCK Export-Gruppe |
inventory.products[].property_values[] |
variant.attributes[] |
Varianten-Attribute | Immer |
inventory.products[].offerings[].is_enabled |
Immer true |
Aktiviert | Immer |
3. Export-Felder-Gruppen
Die Übertragung wird durch Export-Felder-Gruppen gesteuert:
| Export-Gruppe | Beschreibung | Übertragene Etsy-Felder |
|---|---|---|
| ARTIKEL_DATA | Artikeldaten | title, description, taxonomy_id, shipping_profile_id, who_made, when_made, is_supply, state |
| DESCRIPTION | Beschreibung | description |
| IMAGE | Bilder | images[] |
| PRICE | Preis | offerings[].price |
| STOCK | Bestand | offerings[].quantity |
| SKU | Artikelnummer | products[].sku |
| VARIANT | Varianten | products[].property_values[] |
| CATEGORY | Kategorie | taxonomy_id |
4. Besondere Verhaltensweisen
4.1 REST API mit OAuth
Etsy verwendet REST API mit OAuth:
- Listing-Erstellung: POST /shops/{shopId}/listings (x-www-form-urlencoded)
- Listing-Update: PUT /shops/{shopId}/listings/{listingId} (x-www-form-urlencoded)
- Inventory-Update: PUT /listings/{listingId}/inventory (JSON)
- Bilder-Upload: POST /shops/{shopId}/listings/{listingId}/images (multipart/form-data)
- Authentifizierung: OAuth 2.0 (Bearer Token) oder API-Key
4.2 Create vs. Update
- Wenn
marketplaceProductIdvorhanden: Update (PUT) - Wenn
marketplaceProductIdnicht vorhanden: Create (POST) - Nach Create: Listing wird auf
"active"gesetzt
4.3 Inventory-System
- Etsy verwendet separates Inventory-System
- Listing und Inventory werden getrennt aktualisiert
- Inventory enthält Preis, Bestand und Varianten
4.4 Varianten-Matching
- Varianten werden über
marketplaceVariantIdoderskugematcht - Property Values werden aus
variant.attributeserstellt
4.5 Versandprofil
- Wenn
shipping.policyProfile.shippingPolicyIdvorhanden: Verwendet dieses - Sonst: Verwendet erstes Versandprofil aus
listMarketplaceSpecificData - Wenn kein Versandprofil: Setzt
typeauf"download"
4.6 Bilder-Upload
- Bilder werden einzeln hochgeladen
- Sortiert nach
isMain(Hauptbild zuerst) - Verwendet
rankfür Reihenfolge
4.7 Bestand-Update
- Wenn nur
STOCKExport-Gruppe: NursetStockswird aufgerufen - Bestand wird immer überschrieben (nicht als Delta berechnet)
- Negative Werte werden auch übertragen
5. Zusammenfassung: Vollständige Feld-Mappings
Listing-Ebene
| Etsy Feld | reybex Feld | Export-Gruppe | Hinweise |
|---|---|---|---|
title |
material.name |
ARTIKEL_DATA | - |
description |
material.description oder name |
DESCRIPTION | - |
taxonomy_id |
material.categories[0].id |
CATEGORY | - |
shipping_profile_id |
material.shipping.policyProfile.shippingPolicyId oder automatisch |
ARTIKEL_DATA | - |
who_made |
Immer "i_did" |
ARTIKEL_DATA | - |
when_made |
Aktuelles Jahr - 2 bis aktuelles Jahr | ARTIKEL_DATA | - |
is_supply |
Immer "1" |
ARTIKEL_DATA | - |
state |
Immer "active" |
ARTIKEL_DATA | - |
type |
"download" wenn kein Versandprofil |
ARTIKEL_DATA | - |
images[] |
material.images.image[] |
IMAGE | - |
Inventory-Ebene
| Etsy Feld | reybex Feld | Export-Gruppe | Hinweise |
|---|---|---|---|
products[].sku |
material.sku oder variant.sku |
SKU | - |
products[].offerings[].price |
material.price.value oder variant.price.value |
PRICE | - |
products[].offerings[].quantity |
material.stock.value oder variant.stock |
STOCK | - |
products[].property_values[] |
variant.attributes[] |
VARIANT | - |
products[].offerings[].is_enabled |
Immer true |
- | - |
6. API-Endpunkte
- Listing-Erstellung:
POST /shops/{shopId}/listings(x-www-form-urlencoded) - Listing-Update:
PUT /shops/{shopId}/listings/{listingId}(x-www-form-urlencoded) - Inventory-Update:
PUT /listings/{listingId}/inventory(JSON) - Bilder-Upload:
POST /shops/{shopId}/listings/{listingId}/images(multipart/form-data) - Kategorien-Abruf:
GET /seller-taxonomy/nodes(JSON) - Versandprofile-Abruf:
GET /shops/{shopId}/shipping-profiles(JSON) - Authentifizierung: OAuth 2.0 (Bearer Token) oder API-Key
Version: 1.0
Erstellt: 2024
Zielgruppe: Externe Nutzer ohne reybex-Kenntnisse