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 / TypeScript | PHP | |
|---|---|---|
| Paket | @garanify/sdk | garanify/sdk |
| Laufzeit | Node.js 18+, Deno, Bun, Edge; ESM und CommonJS | PHP 8.1+, jeder PSR-18-Client (z. B. Guzzle) |
| Typen | aus der OpenAPI-Datei erzeugt | PHPDoc-Shapes, Antworten als Arrays |
| Abhängigkeiten | keine | psr/http-client, psr/http-factory |
| Status | Fertig 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/guzzleEinrichten
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
| Ressource | Methoden |
|---|---|
me() | Schlüssel, Shop, Tarif, livemode |
shops | create, retrieve, update |
license | retrieve, link, unlink |
keys | list, create, rotate, revoke |
products | list, listAll, retrieve, upsert, delete, bulkUpsert, resolve, preview, renderGaran |
rules | list, replace |
evidence | export (CSV) |
render | garan, notice (ohne Schlüssel) |
public | shop, product (Publishable Key) |
webhooks | retrieve, set, delete, test, deliveries, retry |
meta | health, 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 EtikettSeitenweise 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,429und5xx, standardmäßig zweimal mit wachsender Wartezeit. Bei429wartet der ClientRetry-Afterab (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]);