API Reference

Base URL

https://enricha.dev/v1

Alle Endpoints sind unter dem /v1-Prefix erreichbar. Die OpenAPI-Spezifikation ist maschinenlesbar verfuegbar:

OpenAPI Spec (JSON)

Authentifizierung

Die API nutzt Bearer Token Authentication. Sende deinen API Key im Authorization-Header:

Authorization: Bearer enr_dein_api_key

API Keys werden mit POST /v1/auth/keys erstellt. Kein Account, kein Passwort noetig.

Endpoints

POST /v1/auth/keys

Erstellt einen neuen API Key und Customer-Account.

Rate Limit: 5 pro Stunde pro IP-Adresse.

Request Body (alle Felder optional):

Feld	Typ	Beschreibung
`email`	string \| null	E-Mail fuer Account-Recovery (optional)
`name`	string \| null	Name (optional)

Response 200:

{
"api_key": "enr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"key_prefix": "enr_a1b2c3d4",
"message": "Save this key now — it will not be shown again."
}

Der vollstaendige API Key wird nur einmal angezeigt.

POST /v1/enrich

Enrichment-Pipeline: GPC-Klassifikation + GDM-Attributgenerierung + DQX-Validierung.

Auth: Bearer Token erforderlich. Kosten: 1 Enrichment pro Call (Cache-Hits sind kostenlos). Rate Limit: 60 Requests/Minute pro API Key (konfigurierbar).

Request Body:

Feld	Typ	Pflicht	Beschreibung
`product_name`	string	Ja	Produktname (1-500 Zeichen)
`description`	string	Nein	Produktbeschreibung (max 2000)
`brand`	string	Nein	Markenname (max 255)
`net_content`	string	Nein	Nettofuellmenge, z.B. “750ml”
`ingredients`	string	Nein	Zutatenliste (max 5000)
`category_hint`	string	Nein	Kategorie-Hinweis, z.B. “Wein”
`ean`	string	Nein	EAN/GTIN Barcode (max 20)
`target_market`	string	Nein	ISO 3166-1 numerisch (Default: “276” = Deutschland)
`market_stage`	string	Nein	”list_order”, “move_store” oder “sell” (Default: “sell”)

Response 200:

{
"enrichment_id": "550e8400-e29b-41d4-a716-446655440000",
"gpc": {
  "brick_code": "10000266",
  "brick_name": "Wein - Still",
  "hierarchy": [
    {"code": "50000000", "name": "Food/Beverage/Tobacco"},
    {"code": "50200000", "name": "Getraenke"},
    {"code": "50202200", "name": "Wein"},
    {"code": "10000266", "name": "Wein - Still"}
  ],
  "confidence": 0.94,
  "alternatives": [
    {"brick_code": "10000268", "brick_name": "Schaumwein", "confidence": 0.05}
  ],
  "strategy": "two_pass"
},
"attributes": {
  "mandatory": [
    {
      "attribute_name": "descriptionShort",
      "display_name": "Trade Item Description",
      "value": "Riesling Spaetlese 2024",
      "data_type": "text",
      "source": "input_mapped",
      "confidence": 1.0,
      "requirement": "mandatory"
    }
  ],
  "optional": []
},
"dqx": {
  "score": 85,
  "passed": true,
  "errors": [],
  "warnings": [
    {
      "rule_id": "ENR-004",
      "message": "Recommended optional attribute missing",
      "severity": "warning",
      "attribute": "countryOfOrigin"
    }
  ],
  "gdsn_rules_applied": 22
},
"metadata": {
  "enrichments_used": 1,
  "enrichments_remaining": 99,
  "processing_time_ms": 2340,
  "model_version": "mistral-small-latest",
  "tokens_used": 1240,
  "reference_data_version": "2026-Q1",
  "gdm_version": "2.16",
  "gdsn_version": "3.1.35",
  "cache_hit": false
}
}

Attribute Sources:

Source	Beschreibung	Confidence
`input_mapped`	Deterministisch aus Input extrahiert	1.0
`ai_inferred`	Vom LLM generiert	0.0 - 1.0

Hinweis: Der DQX-Score ist enrichas Qualitaetsindikator auf Basis einer Teilmenge offizieller GDSN-Regeln — kein offizielles GS1-DQX-Assessment.

DQX Rule IDs:

Prefix	Beschreibung
`ENR-001`	Pflichtattribut fehlt
`ENR-002`	Pflichtattribut leer
`ENR-003`	Wert nicht in Code-Liste
`ENR-004`	Empfohlenes optionales Attribut fehlt
`ENR-005`	Niedrige Confidence (Hinweis, kein Abzug)
`ENR-006`	Cross-Attribut-Inkonsistenz
`GDSN-*`	Offizielle GS1 GDSN-Validierungsregel

GET /v1/enrichments

Aktueller Enrichment-Saldo und Kaufhistorie.

Auth: Bearer Token erforderlich.

Response 200:

{
"balance": 95,
"total_used": 5,
"total_purchased": 100,
"last_purchase": "2026-04-01T14:30:00Z"
}

GET /v1/usage

Enrichment-Nutzungsstatistiken nach Zeitraum.

Auth: Bearer Token erforderlich.

Response 200:

{
"today": {"enrichments_count": 12, "enrichments_used": 12},
"week": {"enrichments_count": 45, "enrichments_used": 45},
"month": {"enrichments_count": 180, "enrichments_used": 180},
"all_time": {"enrichments_count": 320, "enrichments_used": 320},
"avg_dqx_score": 82.5
}

GET /v1/health

System-Status (keine Authentifizierung noetig).

Response 200:

{
"status": "healthy",
"checks": {
  "database": "ok",
  "reference_data": {
    "version": "2026-Q1",
    "gpc_count": 6450,
    "gdm_count": 10100,
    "code_list_count": 20591
  },
  "llm_provider": {
    "status": "configured",
    "adapter": "OpenAICompatAdapter"
  }
}
}

POST /v1/webhooks/lemonsqueezy

Lemon Squeezy Payment-Webhook (intern). Verifiziert via HMAC-SHA256.

Rate Limiting

Alle authentifizierten Endpoints sind rate-limited (Standard: 60 Requests/Minute pro API Key).

Response Headers:

Header	Beschreibung
`X-RateLimit-Limit`	Erlaubte Requests pro Minute
`X-RateLimit-Remaining`	Verbleibende Requests
`X-RateLimit-Reset`	Sekunden bis Reset
`Retry-After`	Sekunden bis Retry (nur bei 429)

Allgemeine Response Headers

Header	Beschreibung
`X-Request-ID`	Eindeutige Request-ID (UUID) fuer Debugging

Fehlerformat

Alle Fehler folgen einem einheitlichen Format. Details unter Error Codes.