Zum Inhalt springen
Garanify

Pflicht­angaben per API einbinden

Mit der Garanify API registrieren Sie Shop und Produkte und zeigen die Mitteilung zur gesetzlichen Gewährleistung und das GARAN-Etikett auf jeder Website. Die Grafiken sind immer die offiziellen Dateien der Kommission.

Die API ist gebaut und getestet. Das Hosting unter api.garanify.com ist in Vorbereitung; bis dahin läuft sie lokal. Schlüssel gibt es auf Anfrage.

In fünf Schritten von null zum Etikett, zuerst im Testmodus. Keine Rechtsberatung.

1. Testschlüssel holen

Jeder Shop hat eine Shop-ID, einen Secret Key für Ihren Server und einen Publishable Key für den Browser. Ein Test-Shop (gfy_sk_test_…) hat alle Funktionen ohne Lizenz und ist vom Live-Shop getrennt. Solange die Selbstbedienung im Kundenkonto noch fehlt, schicken wir Ihnen Schlüssel auf Anfrage an hello@qadsoft.dev. Den Secret Key sehen Sie nur einmal. Mehr unter Testmodus.

{
  "shop": "shp_4kq8Zt2mWc9x",
  "secretKey": "gfy_sk_test_…",
  "publishableKey": "gfy_pk_test_4kq8Zt2mWc9x_…"
}

2. SDK installieren

Die SDKs für Node.js und PHP wiederholen fehlgeschlagene Anfragen, setzen Idempotenzschlüssel und prüfen Webhook-Signaturen. Ohne SDK geht alles mit curl. Den Secret Key legen Sie als Umgebungsvariable GARANIFY_SECRET_KEY ab, nie im Frontend oder im Repository.

export GARANIFY_SECRET_KEY=gfy_sk_test_…
curl https://api.garanify.com/v1/me -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
# noch nicht auf npm; bis dahin aus dem Repository
npm install ./packages/sdk-js

export GARANIFY_SECRET_KEY=gfy_sk_test_…
# noch nicht auf Packagist; bis dahin als Path-Repository
composer config repositories.garanify path ./packages/sdk-php
composer require garanify/sdk:@dev guzzlehttp/guzzle

export GARANIFY_SECRET_KEY=gfy_sk_test_…

3. Produkt registrieren

Ein PUT auf die SKU legt das Produkt an oder ersetzt es. Die Modellkennung auf dem Etikett ist die MPN, sonst die SKU, nie die EAN. Das GARAN-Etikett erscheint nur bei einer Herstellergarantie über 2 Jahre mit Marke und Modell.

curl -X PUT "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Washing machine W1","brand":"Miele","mpn":"WCR 870 WPS","categories":["Household > Washing machines"],"garan":{"years":10}}'
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const product = await garanify.products.upsert('WCR870', {
  name: 'Washing machine W1',
  brand: 'Miele',
  mpn: 'WCR 870 WPS',
  categories: [
    'Household > Washing machines'
  ],
  garan: {
    years: 10
  }
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$product = $garanify->products->upsert('WCR870', [
    'name' => 'Washing machine W1',
    'brand' => 'Miele',
    'mpn' => 'WCR 870 WPS',
    'categories' => [
        'Household > Washing machines',
    ],
    'garan' => [
        'years' => 10,
    ],
]);
import os, requests

res = requests.put(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    json={
        "name": "Washing machine W1",
        "brand": "Miele",
        "mpn": "WCR 870 WPS",
        "categories": [
            "Household > Washing machines",
        ],
        "garan": {
            "years": 10,
        },
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()

4. Ergebnis prüfen

Die Auflösung sagt, welches Etikett gilt und warum, so wie in den Admin-Oberflächen der Plugins.

curl "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870/resolve?lang=de" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const resolution = await garanify.products.resolve('WCR870', {
  lang: 'de'
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$resolution = $garanify->products->resolve('WCR870', 'de');
import os, requests

res = requests.get(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/products/WCR870/resolve?lang=de",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()

5. Im Shop anzeigen

Eine Zeile auf der Produktseite. Das Snippet lädt das Etikett aus der API und fügt Mitteilung und Etikett nach dem Kaufen-Knopf ein. Headless oder serverseitig gerendert geht es auch ohne Snippet, siehe Einbetten mit der API. Wenn alles passt, wiederholen Sie die Schritte 3 bis 5 mit den Live-Schlüsseln.

<script src="https://cdn.garanify.com/garanify.min.js" defer
        data-garanify-key="gfy_pk_test_4kq8Zt2mWc9x_…"
        data-sku="WCR870"></script>

Grundlagen

  • Base-URL https://api.garanify.com (Hosting in Vorbereitung), alle Pfade beginnen mit /v1.
  • JSON in UTF-8, Zeiten in ISO 8601 (UTC). Fehler als application/problem+json.
  • Die vollständige Beschreibung steht in der OpenAPI-3.1-Datei; daraus entsteht auch die Referenz.
  • Free zeigt die Mitteilung unbegrenzt und das GARAN-Etikett für bis zu 25 Produkte. Pro und Agentur: unbegrenzt, Regeln, Massen-Upsert.