Zum Inhalt springen
Garanify

SDKs für Node.js und PHP

Zwei offizielle Clients mit denselben Ressourcen und Methoden wie die Referenz. Beide wiederholen fehlgeschlagene Anfragen, setzen Idempotenzschlüssel, prüfen Webhook-Signaturen und melden Fehler mit Code und Request-Id.

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.

Node.js / TypeScriptPHP
Paket@garanify/sdkgaranify/sdk
LaufzeitNode.js 18+, Deno, Bun, Edge; ESM und CommonJSPHP 8.1+, jeder PSR-18-Client (z. B. Guzzle)
Typenaus der OpenAPI-Datei erzeugtPHPDoc-Shapes, Antworten als Arrays
Abhängigkeitenkeinepsr/http-client, psr/http-factory
StatusFertig und getestet, noch nicht veröffentlicht.

Installieren

# noch nicht auf npm; bis dahin aus dem Repository
npm install ./packages/sdk-js
# noch nicht auf Packagist; bis dahin als Path-Repository
composer config repositories.garanify path ./packages/sdk-php
composer require garanify/sdk:@dev guzzlehttp/guzzle

Einrichten

Der Client braucht nur den Schlüssel. Die Shop-ID holt er einmal über GET /v1/me; bei Publishable Keys liest er sie aus dem Schlüssel. Ohne baseUrl gilt https://api.garanify.com (Hosting in Vorbereitung).

import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({
  apiKey: process.env.GARANIFY_SECRET_KEY, // gfy_sk_… or gfy_sk_test_…
  baseUrl: process.env.GARANIFY_BASE_URL,  // optional, z. B. http://localhost:8788
  maxRetries: 2,
  timeout: 10_000,
});

const me = await garanify.me();
console.log(me.shop, me.plan, me.livemode);
<?php
use Garanify\Garanify;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$factory = new HttpFactory();
$garanify = new Garanify(getenv('GARANIFY_SECRET_KEY'), [ // gfy_sk_… or gfy_sk_test_…
    'baseUrl' => getenv('GARANIFY_BASE_URL') ?: Garanify::DEFAULT_BASE_URL,
    'maxRetries' => 2,
    'httpClient' => new Client(['timeout' => 10]),
    'requestFactory' => $factory,
    'streamFactory' => $factory,
]);

$me = $garanify->me();
echo $me['shop'], ' ', $me['plan'], ' ', $me['livemode'] ? 'live' : 'test';

Ressourcen

RessourceMethoden
me()Schlüssel, Shop, Tarif, livemode
shopscreate, retrieve, update
licenseretrieve, link, unlink
keyslist, create, rotate, revoke
productslist, listAll, retrieve, upsert, delete, bulkUpsert, resolve, preview, renderGaran
ruleslist, replace
evidenceexport (CSV)
rendergaran, notice (ohne Schlüssel)
publicshop, product (Publishable Key)
webhooksretrieve, set, delete, test, deliveries, retry
metahealth, languages, modules, webhookEvents

Jede Referenzseite zeigt den passenden Aufruf in beiden SDKs. Der Build prüft, dass jede dort genannte Methode im SDK existiert.

Produkte und Etiketten

const product = await garanify.products.upsert('WCR870', {
  name: 'Washing machine W1',
  brand: 'Miele',
  mpn: 'WCR 870 WPS', // Modellkennung auf dem Etikett, nie die EAN
  garan: { years: 10 },
});
console.log(product.status); // 'label'

const why = await garanify.products.resolve('WCR870', { lang: 'de' });
console.log(why.reason.code);

const svg = await garanify.products.renderGaran('WCR870', { lang: 'de' }); // offizielles SVG, null ohne Etikett
<?php
$product = $garanify->products->upsert('WCR870', [
    'name' => 'Washing machine W1',
    'brand' => 'Miele',
    'mpn' => 'WCR 870 WPS', // Modellkennung auf dem Etikett, nie die EAN
    'garan' => ['years' => 10],
]);
echo $product['status']; // label

$why = $garanify->products->resolve('WCR870', 'de');
echo $why['reason']['code'];

$html = $garanify->products->renderGaran('WCR870', ['format' => 'html', 'lang' => 'de']); // null ohne Etikett

Seitenweise lesen

Listen sind cursor-basiert (nextCursor). listAll holt alle Seiten nacheinander.

for await (const p of garanify.products.listAll({ status: 'invalid' })) {
  console.log(p.sku, p.errors.map((e) => e.code));
}
<?php
foreach ($garanify->products->listAll(['status' => 'invalid']) as $p) {
    echo $p['sku'], ': ', implode(', ', array_column($p['errors'], 'code')), PHP_EOL;
}

Fehler

Jede Antwort ab 400 wird zu GaranifyError (PHP: GaranifyException) mit status, dem stabilen code aus Fehler und Codes, errors und requestId. Netzwerkfehler haben Status 0 und den Code network_error (Node.js zusätzlich timeout).

import { Garanify, GaranifyError } from '@garanify/sdk';

try {
  await garanify.products.upsert('X', { garan: { years: 'ten' } });
} catch (e) {
  if (!(e instanceof GaranifyError)) throw e;
  console.log(e.status, e.code, e.errors, e.requestId);
  // 422 'validation_failed' [{ path: '/garan/years', message: '…' }] 'req_…'
}
<?php
use Garanify\GaranifyException;

try {
    $garanify->products->upsert('X', ['garan' => ['years' => 'ten']]);
} catch (GaranifyException $e) {
    echo $e->status, ' ', $e->errorCode, ' ', $e->requestId;
    // 422 validation_failed req_…
}

Wiederholungen und Idempotenz

  • Wiederholt werden Netzwerkfehler, Zeitüberschreitungen, 408, 429 und 5xx, standardmäßig zweimal mit wachsender Wartezeit. Bei 429 wartet der Client Retry-After ab (höchstens 60 s).
  • GET, PUT, DELETE und Vorschauen sind immer wiederholbar. POSTs, die etwas anlegen, bekommen automatisch einen Idempotency-Key, der über alle Versuche gleich bleibt.
  • Mit einem eigenen Schlüssel werden auch Wiederholungen über Prozesse hinweg sicher. Mehr unter Limits.
const importId = 'run-42';
const page = 1;
const batch = [{ sku: 'WCR870', brand: 'Miele', mpn: 'WCR 870 WPS', garan: { years: 10 } }];
await garanify.products.bulkUpsert(batch, { idempotencyKey: `import-${importId}-${page}` });
<?php
$batch = [['sku' => 'WCR870', 'brand' => 'Miele', 'mpn' => 'WCR 870 WPS', 'garan' => ['years' => 10]]];
$garanify->products->bulkUpsert($batch, ['idempotencyKey' => "import-{$importId}-{$page}"]);

Mehrere Shops

Agenturen sprechen mit demselben Secret Key andere Shops des Kontos an.

const other = garanify.withShop('shp_7Rb2Kc9mQx4Z');
await other.products.list({ limit: 50 });
<?php
$other = $garanify->withShop('shp_7Rb2Kc9mQx4Z');
$other->products->list(['limit' => 50]);

Testmodus und Webhooks

Mit einem Testschlüssel (gfy_sk_test_…) arbeitet das SDK gegen einen Test-Shop; garanify.testMode (PHP: isTestMode()) sagt, welcher Schlüssel aktiv ist. Siehe Testmodus. Die Signaturprüfung für Webhooks steht unter Webhooks.