Shop API Documentation

🔐 Authentication

Some endpoints require API key authentication. You can provide your API key in two ways:

Option 1: Header Authentication

X-API-Key: your-api-key-here

Option 2: Query Parameter

?api_key=your-api-key-here

How to obtain an API key:

GET /api No Auth

Returns this API documentation

View as JSON

GET /api/orders Auth Required

Get orders for the authenticated user. status may be awaiting_tracking (carrier shipment rows, no tracking yet) or ready_for_pickup for Abholung when JTL marks it prepared — see docs/frontend-order-status.md (primary client: Socket.IO getOrders).

Example Response:

{ "success": true, "orders": [ { "orderId": "ORD-2024-001", "status": "awaiting_tracking", "created_at": "2024-01-15T10:30:00Z", "items": [...] } ] }

cURL Example:

curl -H "X-API-Key: your-api-key" __DYNAMIC_HOST__/api/orders

GET /api/categories No Auth

Get all shop categories with only ID and name

Example Response:

{ "success": true, "categories": [ { "id": 209, "name": "Home" }, { "id": 689, "name": "Cannabis Seeds" } ] }

Try it →

GET /api/categories/:categoryId/products No Auth

Get product list for a category (only ID and name)

Parameters:

categoryId - Category ID (number)

Example Response:

{ "success": true, "products": [ { "id": 12345, "name": "Product Name" }, { "id": 12346, "name": "Another Product" } ] }

Example URL:

/api/categories/689/products

Try it →

GET /api/products/:productId No Auth

Get product information

Parameters:

productId - Product ID

Example Response:

{ "success": true, "product": { "categoryId": 689, "id": 12345, "name": "Product Name", "gtin": "1234567890123", "vat": 19, "price": 29.99, "available": 1, "articleNumber": "ART-12345" } }

Example URL:

/api/products/12345

Note: Replace 12345 with an actual product ID from the category products endpoint

GET /api/categoryPic/:kBild.jpg No Auth

Get category picture as JPEG image (130x130px with white background for transparency)

Parameters:

kBild - Category picture ID (number)

Response:

JPEG image file (130×130 pixels)

Caching:

Cache-Control: public, max-age=31536000, immutable Content-Type: image/jpeg Expires: 1 year from request

Example URL:

/api/categoryPic/11819.jpg

Note: Pictures are cached for 1 year. Use the kBild values from category data.

HEAD Request for Checking Existence:

HEAD /api/categoryPic/11819.jpg

Use HEAD to check if a picture exists without downloading the image data.

Conditional Requests with ETag:

GET /api/categoryPic/11819.jpg
If-None-Match: "11819-12345"

If the ETag matches, server returns 304 Not Modified (no image data).

Try it →

🔍 HEAD Requests & ETags

HEAD requests work like GET but return only headers (no body). Perfect for checking if resources exist without downloading them.

Why HEAD is useful:

Check if images exist before displaying them
Get image size without downloading
Test API endpoints
Reduce bandwidth for existence checks

ETags enable smart caching:

Unique identifier for each image version
Browser sends "If-None-Match" header
Server returns 304 if image hasn't changed
Saves bandwidth by not re-downloading same content

Example HEAD request:

curl -I https://your-domain.com/api/categoryPic/11819.jpg

💻 Node.js Code Example

Here's a complete Node.js example showing how to loop through all categories and their products:

Complete Example (loop-products.js):

const https = require('https');
const http = require('http');

const API_BASE_URL = '__DYNAMIC_HOST__/api';

// Create HTTP agents with more conservative connection pooling
const httpsAgent = new https.Agent({
    keepAlive: true,
    keepAliveMsecs: 30000,
    maxSockets: 5,
    maxFreeSockets: 2,
    timeout: 30000,
    freeSocketTimeout: 30000
});

const httpAgent = new http.Agent({
    keepAlive: true,
    keepAliveMsecs: 30000,
    maxSockets: 5,
    maxFreeSockets: 2,
    timeout: 30000,
    freeSocketTimeout: 30000
});

// Helper function to get the appropriate agent
function getAgent(url) {
    return url.startsWith('https:') ? httpsAgent : httpAgent;
}

// Wrapper function for fetch with agent
async function fetchWithAgent(url, options = {}) {
    return fetch(url, {
        ...options,
        agent: getAgent(url)
    });
}

// Concurrency control utility
async function processInBatches(items, batchSize, processor) {
    const results = [];
    for (let i = 0; i < items.length; i += batchSize) {
        const batch = items.slice(i, i + batchSize);
        console.log(\`🔄 Processing batch \${Math.floor(i/batchSize) + 1}/\${Math.ceil(items.length/batchSize)} (\${batch.length} items)\`);
        
        const batchResults = await Promise.all(batch.map(processor));
        results.push(...batchResults);
        
        // Small delay between batches to be nice to the server
        if (i + batchSize < items.length) {
            await new Promise(resolve => setTimeout(resolve, 250));
        }
    }
    return results;
}

async function getAllCategoriesAndProducts() {
    try {
        console.log('🔍 Fetching categories...');
        const categoriesResponse = await fetchWithAgent(\`\${API_BASE_URL}/categories\`);
        const categoriesData = await categoriesResponse.json();
        if (!categoriesData.success) throw new Error('Failed to fetch categories');
        
        console.log(\`📁 Found \${categoriesData.categories.length} categories\`);
        
        // Process categories in batches of 3 to avoid overwhelming the server
        const results = await processInBatches(
            categoriesData.categories, 
            3, 
            async (category) => {
                console.log(\`📂 \${category.name} (ID: \${category.id})\`);
                try {
                    const productsResponse = await fetchWithAgent(\`\${API_BASE_URL}/categories/\${category.id}/products\`);
                    const productsData = await productsResponse.json();
                    
                    if (productsData.success && productsData.products.length > 0) {
                        console.log(\`   📦 \${productsData.products.length} products:\`);
                        
                        // Process product details in smaller batches of 5
                        const productsWithDetails = await processInBatches(
                            productsData.products,
                            5,
                            async (product) => {
                                try {
                                    const details = await fetchWithAgent(\`\${API_BASE_URL}/products/\${product.id}\`);
                                    const detailsData = await details.json();
                                    return {
                                        product,
                                        details: detailsData.success ? detailsData.product : null
                                    };
                                } catch (error) {
                                    console.error(\`   ❌ Error fetching details for \${product.name}: \${error.message}\`);
                                    return { product, details: null };
                                }
                            }
                        );
                        
                        // Display results
                        productsWithDetails.forEach(({ product, details }) => {
                            console.log(\`   - \${product.name} (ID: \${product.id})\`);
                            if (details) {
                                console.log(\`     €\${details.price}\`);
                            }
                        });
                        
                        return { category, products: productsWithDetails };
                    } else {
                        console.log('   📦 No products found');
                        return { category, products: [] };
                    }
                } catch (error) {
                    console.error(\`   ❌ Error fetching products for \${category.name}: \${error.message}\`);
                    return { category, products: [] };
                }
            }
        );
        
        console.log('\\n✅ Finished');
        console.log(\`📊 Processed \${results.length} categories with \${results.reduce((sum, r) => sum + r.products.length, 0)} total products\`);
        
        // Clean up agents
        httpsAgent.destroy();
        httpAgent.destroy();
        
        return results;
    } catch (error) {
        console.error('❌ Error:', error.message);
        // Clean up agents on error
        httpsAgent.destroy();
        httpAgent.destroy();
    }
}

getAllCategoriesAndProducts();

Simple Version (basic-loop.js):

const fetch = require('node-fetch'); // npm install node-fetch (Node.js < 18)

async function simpleLoop() {
    const categories = await fetch('__DYNAMIC_HOST__/api/categories').then(r => r.json());
    for (const category of categories.categories) {
        console.log(\`Category: \${category.name}\`);
        const products = await fetch(\`__DYNAMIC_HOST__/api/categories/\${category.id}/products\`)
            .then(r => r.json());
        if (products.success) {
            products.products.forEach(p => console.log(\`  - \${p.name}\`));
        }
    }
}
simpleLoop();

Installation & Usage:

# For Node.js versions < 18, install node-fetch
npm install node-fetch

# Run the example
node loop-products.js

With Authentication (for orders):

const fetch = require('node-fetch');
const API_KEY = 'your-api-key-here'; // Get from website settings

async function getOrdersExample() {
    try {
        const response = await fetch('__DYNAMIC_HOST__/api/orders', {
            headers: { 'X-API-Key': API_KEY }
        });
        const data = await response.json();
        if (data.success) {
            console.log('Orders:', data.orders);
        } else {
            console.error(data.error);
        }
    } catch (error) {
        console.error('Request failed:', error.message);
    }
}
getOrdersExample();