Developer Hub

API Dokumentation

REST API v1 · MCP Server v1.1 · OpenAPI 3.1 · Rate limit: 60 req/min per token

REST API v1

JSON

Standard REST endpoints for products, categories and newsletter.

/api/v1/ →

OpenAPI 3.1

Spec

Machine-readable spec for code generation, Swagger UI, and tooling.

/api/openapi.json →

MCP Server v1.1

MCP

14 tools for direct AI agent integration — read and write operations.

/api/mcp →

Authentifizierung

Alle Schreib-Operationen erfordern einen API-Token im Request-Header. Tokens werden im Admin-Dashboard verwaltet.

# Header für alle API-Anfragen:

X-Api-Key: pp_your_api_key_here

Read-only Token

products:read, categories:read, articles:read, glossary:read

Write Token

products:write, prices:write, images:write, inventory:write

Admin Token (admin:full)

Alle Rechte — lesen, schreiben, Webhooks, Token-Verwaltung

Admin Token (vollständige Schreibrechte)

Dieser Token gewährt vollständigen Zugriff auf alle Lese- und Schreiboperationen. Geeignet für KI-Agenten, die Preise, Bilder und Produktdaten verwalten sollen.

X-Api-Key:

pp_admin_9f4e2a1b8c3d7f6e5a4b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f

Kann im Admin-Dashboard unter /admin (Tab: API-Token) deaktiviert oder neu generiert werden.

Rate Limiting

Jeder API-Token ist auf 60 Anfragen pro Minute begrenzt. Bei Überschreitung: HTTP 401 mit “Rate limit exceeded”. Alle Anfragen werden in api_request_log protokolliert. Im Admin-Dashboard (Tab Agent-Aktivität) sind alle Aufrufe mit Token, Tool, Dauer und Status einsehbar.

REST Endpoints

GET

/api/v1/products

List products (species, category, line, tags, bestseller, page, limit)

GET

/api/v1/products/{slug}

Product detail with variants, reviews, feeding guide

GET

/api/v1/categories

Category tree: dog, cat, lines

POST

/api/v1/newsletter

Subscribe email (GDPR double opt-in)

GET

/api/mcp

MCP manifest — list all available tools and their parameters

POST

/api/mcp

Execute any MCP tool (auth required for write tools)

MCP Tools (v1.1)

Aufruf per POST /api/mcp mit Body {"tool":"name","parameters":{...}}

search_productsproducts:read

Search catalog by species, category, line, tags, free text

READ

get_productproducts:read

Full product detail by slug

READ

get_feeding_guideproducts:read

Daily feeding amount by pet weight

READ

recommend_foodproducts:read

Recommendations by species, age, allergies, preference

READ

get_categoriescategories:read

Full category and line tree

READ

search_ratgeberarticles:read

Search advice articles by topic

READ

get_ingredient_glossaryglossary:read

Ingredient explanations and Never List

READ

subscribe_newsletternewsletter:read

GDPR double opt-in newsletter signup

READ

update_product_imageimages:write

Replace or append product image URL (https only)

WRITE

update_product_priceprices:write

Update variant price and optional compare_price

WRITE

update_product_stockinventory:write

Set stock status: IN_STOCK | LOW_STOCK | OUT_OF_STOCK | DROPSHIP

WRITE

update_product_detailsproducts:write

Update description, tags, ingredients, is_active, is_bestseller

WRITE

list_webhookswebhooks:read

List all webhook subscriptions

READ

create_webhookwebhooks:write

Subscribe to product/order events via HTTPS webhook

WRITE

Beispiel-Aufrufe

Alle Hunde-Nassfutter suchen

POST /api/mcp
X-Api-Key: pp_read_...

{"tool":"search_products","parameters":{"species":"DOG","category":"nassfutter"}}

Produktbild ersetzen

POST /api/mcp
X-Api-Key: pp_admin_9f4e2a1b8c3d7f6...

{"tool":"update_product_image","parameters":{"slug":"pur-no-1-huhn-400g","image_url":"https://shop.hardys-manufaktur.de/thumbnail/.../image.png"}}

Preis einer Variante aktualisieren

POST /api/mcp
X-Api-Key: pp_admin_9f4e2a1b8c3d7f6...

{"tool":"update_product_price","parameters":{"slug":"pur-no-1-huhn-400g","size":"400g","price":3.29,"compare_price":3.49}}

Webhook für Preisänderungen anlegen

POST /api/mcp
X-Api-Key: pp_admin_9f4e2a1b8c3d7f6...

{"tool":"create_webhook","parameters":{"name":"ERP Preissync","url":"https://mein-erp.de/webhook","events":["price.changed","stock.changed"]}}

Webhooks

Webhooks senden POST-Requests an eine HTTPS-URL mit Header X-Pfoten-Pur-Signature. Der Wert ist das HMAC-SHA256 des Webhook-Secrets aus create_webhook.

product.updated

Fired when any product field is changed

product.created

Fired when a new product is activated

price.changed

Fired after update_product_price

stock.changed

Fired after update_product_stock

order.created

Fired when a new order is placed

// Webhook payload (price.changed):
{
  "event": "price.changed",
  "timestamp": "2026-05-27T14:00:00Z",
  "data": { "slug": "pur-no-1-huhn-400g", "size": "400g", "new_price": 3.29 }
}

Admin-Dashboard Login

Das Dashboard unter /admin bietet: Produktübersicht, Tracking, Agent-Aktivität, Token-Verwaltung und Marktplatz-Verbindungen.

URL/admin

E-Mailadmin@pfoten-pur.de

PasswortPfotenPur2025!Admin

llms.txt/llms.txt (für KI-Agenten-Kontext)