Die Public API ist für Server-zu-Server-Integrationen mit Shops, E-Commerce-Backends, WordPress/WooCommerce-Plugins und externen Produktionsabläufen vorgesehen.
Erstelle API-Zugangsdaten in den E-Commerce-Einstellungen. Das Access Token wird nur einmal angezeigt. Speichere es daher sofort im sicheren Geheimnisspeicher deines Backends.
Bewahre Access Key und Access Token auf deinem Server auf. Authentifizierte Endpunkte lehnen vom Browser ausgehende Aufrufe mit Origin- oder Referer-Headern ab.
Zugangsdaten können auf Berechtigungsbereiche beschränkt werden. Prüfe mit GET /auth/check den aktiven Shop, die Tarifmöglichkeiten und die für die Zugangsdaten zurückgegebenen Berechtigungsbereiche.
Die folgende Hilfsfunktion wird in den weiteren Beispielen verwendet. Sie nutzt einfaches fetch und läuft in Node.js 18+ oder jeder Serverlaufzeit, die fetch bereitstellt.
Die folgende Tabelle entspricht den in backend-public-api/app.js eingebundenen öffentlichen Routen. Pfade enthalten das öffentliche Proxy-Präfix für externe Integrationen.
Methode
Endpunkt
Beschreibung
Zugriff
GET
/public-api/healthz
Statusprüfung des Dienstes.
öffentlich
GET
/public-api/v1/auth/check
Validiert Zugangsdaten und gibt Shop, Berechtigungsbereiche und Tarifmöglichkeiten zurück.
beliebige authentifizierte Zugangsdaten
GET
/public-api/v1/customer-orders
Gibt eine paginierte und filterbare Liste von Kundenbestellungen zurück.
orders:read
GET
/public-api/v1/customer-orders/:id
Gibt eine einzelne Kundenbestellung mit konfigurierten Produktpositionen zurück.
orders:read
POST
/public-api/v1/customer-orders/batch
Gibt bis zu 100 Bestellungen anhand ihrer IDs zurück.
orders:read
PATCH
/public-api/v1/customer-orders/:id/status
Aktualisiert den Bestellstatus.
orders:write
PATCH
/public-api/v1/customer-orders/:orderId/quantity
Aktualisiert die Mengen ausgewählter Bestellpositionen.
Mit den Kundenbestellendpunkten kann ein externer Shop konfigurierte Positionen lesen, Mengen aktualisieren, Bestellungen durch Abwicklungsstatus führen und aufgegebene Bestellungen entfernen.
Parameter
Erforderlich
Details
name
nein
Durchsucht Designnamen und numerische Bestell-IDs.
category_id
nein
Filtert nach Produktkategorie-ID.
order_status
nein
Einer der zulässigen Bestellstatus.
offset
nein
Standard 0. Muss >= 0 sein.
limit
nein
Standard 9 für diesen Controller, maximal 50.
order_by
nein
id, created_at oder design_name.
direction
nein
ASC oder DESC.
Beispielanfrage (fetch)
const params =newURLSearchParams({limit:'20',offset:'0',order_status:'shopping_cart',order_by:'created_at',direction:'DESC'});const orders =awaitalterFetch(`/customer-orders?${params.toString()}`);const order =awaitalterFetch('/customer-orders/123');const batch =awaitalterFetch('/customer-orders/batch',{method:'POST',body:JSON.stringify({customerOrderIds:[123,124,125]})});
Zulässige Werte
Status
Beschreibung
shopping_cart
Warenkorbablauf; der Kunde kann die Konfiguration weiterhin bearbeiten.
editable
Die Bestellung bleibt für den Kunden bearbeitbar.
paid
Die Bestellung ist bezahlt und bereit zur Abwicklung.
Erstelle auf deinem Server ein kurzlebiges Einbettungstoken und übergib es an das iframe bzw. die Laufzeit. Diese ruft anschließend die Initialisierung mit einem Bearer-Token auf.
Parameter
Erforderlich
Details
runtimeBindingId
empfohlen
Bevorzugte Kennung für aktive Laufzeitzuordnungen.
Die Importendpunkte des Generators erlauben nur lesende Anfragen zwischen Servern. Sie erfordern die üblichen API-Header, den Scope embed:session:create und einen aktiven Tarif. Die Importautorisierung erstellt keine Editorsitzung und verbraucht deren monatliches Kontingent nicht. Beim Öffnen des Editors gilt derselbe Zähler monthlyEmbedTokenLimit wie für die anderen eingebetteten Werkzeuge.
Generatormodelle finden und importieren
Über /model-generator/models können Sie verfügbare Modelle mit Generator auflisten. Der Deskriptor generator legt projectId, revision, configurationId, templateRevision, productId und productModel3dId fest. Rufen Sie seinen importPath auf, um genau diese Quellrevision abzurufen. Die Manifeste der Produkt-Assets enthalten ebenfalls generators sowie den Deskriptor generator jedes Modells. Vorlagen können anhand ihrer Konfiguration und Revision separat importiert werden.
Katalogfilter
Endpunkt
Details
/model-generator/models
Modellliste: name (oder q), categoryId, scope (all, own, global), limit (1–50) und offset.
/model-generator/catalog
Vorlagenkatalog: generatorType, productId, audience, q, templateKey, configurationId, limit und offset.
/model-generator/projects
Projektliste: configurationId, q, scope (all, own, global), limit und offset. Der öffentliche Proxy setzt scope standardmäßig auf all.
/model-generator/image-libraries/:kind/assets
Textur- und Hintergrundbibliotheken: kind ist texture oder background; q, category und mapType filtern die verfügbaren Assets.
Ein Projektimport enthält document, revision, template und ein Manifest files. Jede Datei liefert einen path unter /v1/model-generator/; stellen Sie beim Herunterladen von Alter Product /public-api voran. Kopieren Sie die benötigten Dateien in Ihren eigenen Speicher und ersetzen Sie die Quellverweise durch lokale Verweise. Importieren Sie Schaufensterpuppen und Texturbibliotheken über ihre Katalogendpunkte; public-files ist auf erlaubte Ressourcenpfade beschränkt, und Vorlagen müssen die Zugriffsprüfung für ihre Konfiguration und Revision bestehen.
Beispielanfrage (fetch)
// Server-side: uses the alterFetch helper and authHeaders defined above.const catalog =awaitalterFetch('/model-generator/models?'+newURLSearchParams({scope:'all',limit:'24',offset:'0'}));const selected = catalog.items[0];if(!selected?.generator)thrownewError('Select an available generator model');const importPath = selected.generator.importPath;if(!importPath.startsWith('/v1/model-generator/projects/')){thrownewError('Invalid generator import path');}const bundle =awaitalterFetch(importPath.slice('/v1'.length));for(const file of bundle.files){if(!file.path.startsWith('/v1/model-generator/')){thrownewError('Invalid generator file path');}const response =awaitfetch('https://alterproduct.com/public-api'+ file.path,{headers: authHeaders,redirect:'error'});if(!response.ok)thrownewError(`File download failed: ${response.status}`);const bytes =newUint8Array(await response.arrayBuffer());// Persist bytes in your local storage; record the mapping from// file.sourceHref / file.href to the resulting local file reference.}// Persist bundle.document, bundle.template and revision metadata locally.// Import the related product asset and its textures/mockups as needed:const product =awaitalterFetch('/assets/products/'+ selected.generator.productId);const mannequins =awaitalterFetch('/model-generator/mannequins');console.log({ product, mannequins });
Editorsitzung und lokale Speicherung
Erstellen Sie die Editorsitzung mit tool: model-generator, einer positiven numerischen toolId zur Identifizierung des lokalen Generatorprojekts (nicht dessen UUID oder der WooCommerce-Produkt-ID) und dem erlaubten Ursprung des Shops. Übergeben Sie für dieses Werkzeug weder designId, orderId, runtimeBindingId noch Warenkorbfelder. Die UUID des Generatorprojekts ist ein separater Bezeichner. Übermitteln Sie das zurückgegebene Token über den Iframe-Handshake; der Runtime-Bootstrap liefert den Generatorkontext mit storageMode: wordpress_local.
// Server-side, after authorizing the merchant's access to this local project.const localProjectId =42;// Local generator project ID, not its UUID or WC product ID.const session =awaitalterFetch('/embed/session',{method:'POST',body:JSON.stringify({tool:'model-generator',toolId: localProjectId,origin:'https://yourstore.com'})});// The iframe receives session.token through ALTER_CUSTOMIZER_SESSION_READY.// Do not put API credentials or the token in the iframe URL.const bootstrapResponse =awaitfetch('https://alterproduct.com/public-api/v1/runtime/bootstrap',{headers:{Authorization:`Bearer ${session.token}`}});if(!bootstrapResponse.ok)thrownewError('Generator bootstrap failed');const context =await bootstrapResponse.json();console.log(context);
// Host page: WordPress returns a numeric toolId and a UUID in id.const url =newURL('https://alterproduct.com/app/model-generator');url.search=newURLSearchParams({embedded:'1',lng:'en',parentOrigin:window.location.origin,toolId:String(localProject.toolId),serverProjectId: localProject.id}).toString();// Optional: serverProjectRevision pins an existing saved revision.iframe.src= url.toString();// Install the authenticated handshake and storage bridge described below.// Setting iframe.src alone does not authorize the editor or provide storage.
Iframe-Nachrichten der WordPress-Brücke
Das WordPress-Plugin stellt die Speicherbrücke bereit und prüft Administrator- oder WooCommerce-Manager-Berechtigungen. Es validiert Iframe-Ursprung, Quellfenster, nonce, Anfrage-ID und erlaubte Projektpfade. Die Brücke leitet lokale Lese- und Schreibvorgänge an /wp-json/alter-wc/v1/model-generator weiter. API-Zugangsdaten bleiben auf dem Server. Eine eigene Integration muss eine gleichwertige authentifizierte Speicherverarbeitung bereitstellen; die öffentliche Generator-API speichert keine Projekte bei Alter Product.
Typ
Beschreibung
ALTER_CHILD_HELLO / ALTER_PARENT_ACK
Das Iframe startet den Handshake mit einer nonce; die übergeordnete Seite bestätigt dieselbe nonce.
Das Iframe fordert eine Bearbeitungssitzung für model-generator an; die übergeordnete Seite liefert das autorisierte Token.
ALTER_MODEL_GENERATOR_REQUEST
Das Iframe sendet requestId, nonce und request mit method, path, data und responseType.
ALTER_MODEL_GENERATOR_RESPONSE
Die übergeordnete Seite antwortet mit derselben requestId und nonce sowie status, data, headers und gegebenenfalls error.
// Messages after ALTER_CHILD_HELLO / ALTER_PARENT_ACK agree on the nonce.// Iframe -> parent:const sessionRequest ={type:'ALTER_CUSTOMIZER_INIT_SESSION',nonce: handshakeNonce,payload:{tool:'model-generator',alterProductId: localProject.toolId,mode:'edit'}};// Parent -> iframe, after the server authorizes the merchant and issues a token:const sessionReady ={type:'ALTER_CUSTOMIZER_SESSION_READY',nonce: handshakeNonce,token: session.token,tool:'model-generator',cartKey:`model-generator:${localProject.id}`,mode:'edit',localSession:false,adminSession:true};// Send only to the validated iframe's exact origin and source window.// An authorized token and successful bootstrap are still required.
Beim Speichern werden expectedRevision, templateRevision, document und Artefaktverweise übermittelt. Dadurch entsteht eine unveränderliche Revision; ein veralteter Wert für expectedRevision führt zu HTTP 409. WordPress speichert Metadaten in seiner Datenbank und Dateien im Uploads-Verzeichnis. JSON wird minifiziert und mit gzip komprimiert, wenn dies die Dateigröße verringert.
// Example message from the iframe; savedSnapshot and artifact IDs come// from the generator. The host checks origin/source/nonce/project permissions.const message ={type:'ALTER_MODEL_GENERATOR_REQUEST',requestId: crypto.randomUUID(),nonce: handshakeNonce,request:{method:'POST',path:`/pattern-generator/projects/${projectUuid}/revisions`,data:{expectedRevision: loadedRevision,name: projectName, templateRevision,document: savedSnapshot,references:{artifactIds: savedArtifactIds }},responseType:'json'}};
Gespeichertes Modell im Design verwenden veröffentlicht eine vollständige gespeicherte Revision in einem verknüpften Produktdesign. Kunden sehen sie anschließend im bestehenden Customizer, Configurator oder Viewer mit den üblichen Produktzuordnungen und Abonnementprüfungen. Der Generatoreditor bleibt ein Werkzeug für Händler. Bestellverknüpfungen behalten das gespeicherte Projekt und dessen Revision bei, sodass spätere Änderungen frühere Bestellungen nicht unbemerkt verändern.
Designimporte stellen bei Alter gehostete Designs und ihre Dateien für externe Produktions- oder Migrationsabläufe bereit. Die API prüft die Berechtigung des Business-Tarifs.
Öffentliche Vorschaudateien sind für Browser geeignet. Geschützte Dateien erfordern eine signierte URL oder API-Zugangsdaten mit files:read. Schriftarten und Währungen sind öffentlich lesbare Endpunkte.
Laufzeitzuordnungen verbinden externe Shop-Produkte mit Alter Product Designs und Laufzeittypen. Sie werden hauptsächlich von WordPress/WooCommerce-Integrationen und erweiterten Shop-Backends verwendet.
Parameter
Erforderlich
Details
designId
nein
ID eines Alter Product Designs, das dem Shop gehört.
externalProductId
ja für die Synchronisierung
Externe Produkt-ID, z. B. eine WooCommerce-Produkt-ID.
runtimeType
ja für die Synchronisierung
viewer, configurator oder customizer.
status
nein
draft, active, inactive, archived oder legacy_active.
awaitalterFetch('/runtime-bindings/sync-from-wordpress',{method:'POST',body:JSON.stringify({bindings:[{externalProductId:'wc_123',runtimeType:'viewer',status:'active',externalDesign:{externalDesignKey:'wp-design-381',productId:4,title:'WooCommerce local design',manifestUrl:'https://yourstore.com/wp-content/uploads/alter/381/manifest.json',assetBaseUrl:'https://yourstore.com/wp-content/uploads/alter/381/',manifestHash:'a3b1...',sourceMeta:{pluginVersion:'1.2.0'}}}]})});
Der WordPress-Verbindungsendpunkt löst einen einmaligen Übergabecode ein und gibt API-Zugangsdaten an das Plugin zurück. Er ist kein allgemeiner Endpunkt zum Erstellen von Zugangsdaten.
Die meisten Controller-Fehler werden als Antwort mit code vereinheitlicht. Authentifizierungs-Middleware und Anfragelimiter können stattdessen eine Antwort mit error zurückgeben.
// Controller error{"code":"assetCatalog.invalidType"}// Auth middleware or rate limit{"error":"Unauthorized"}{"error":"Too Many Requests"}