Überblick
Zur Beschleunigung Ihrer Backend-Integration in Node.js/TypeScript-, Python-, PHP- und Shell-Umgebungen — ergänzend zu den Entwickler-Tools im Dashboard unter /settings/workspace/integrations/link-generator, /settings/workspace/developer/embed-sdk, /settings/workspace/developer/sdks, /settings/workspace/developer/query-helper und /settings/workspace/developer/qr-generator — bietet dieser Leitfaden bewährte Produktivmuster für idempotente Pass-Upserts (POST /api/v1/passes/upsert-by-external-id), parametrisierte Download-Links (PARAMETERIZED_PASS_LINK / CREATE_PASS_URL), Cursor-basierte Paginierung sowie zeitkonstante HMAC-SHA256-Webhook-Verifizierung.
Wichtig: Synchronisieren Sie einen Geschäftsdatensatz per Upsert über
(templateId, externalId). Der zurückgegebene Pass steht unterdata.pass, das Ergebnis unterdata.action(CREATEDoderUPDATED). Senden Sie beiPOST /api/v1/passeseinenIdempotency-Key-Header, damit Wiederholungen denselben Erstellungsauftrag verwenden. Der Upsert-Endpunkt wertet diesen Header nicht aus.
Ablauf für idempotentes Upsert & Cursor-Paginierung
Produktivmuster für mehrere Programmiersprachen
1. Node.js / TypeScript: Idempotenter Pass-Upsert-Helper
interface IUpsertPassPayload {
templateId: string;
externalId: string;
attributes: Record<string, string | number | boolean>;
expirationDate?: string;
}
export async function upsertWalletPass(payload: IUpsertPassPayload) {
const response = await fetch('https://api.passinstance.com/api/v1/passes/upsert-by-external-id', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.PASSINSTANCE_API_KEY ?? '',
},
body: JSON.stringify(payload),
});
const body = await response.json();
if (!response.ok || !body.success) {
throw new Error(`Passinstance API error [${body.errorCode ?? response.status}]: ${body.message}`);
}
return body.data.pass as { id: string; serialNumber: string; externalId?: string; passAccessUrl: string };
}
2. Python: Idempotentes Upsert & HMAC-Webhook-Prüfung
import hmac
import hashlib
import os
import requests
API_BASE_URL = "https://api.passinstance.com/api/v1"
API_KEY = os.environ["PASSINSTANCE_API_KEY"]
def upsert_pass_by_external_id(template_id: str, external_id: str, attributes: dict) -> dict:
response = requests.post(
f"{API_BASE_URL}/passes/upsert-by-external-id",
headers={
"x-api-key": API_KEY,
"Content-Type": "application/json",
},
json={
"templateId": template_id,
"externalId": external_id,
"attributes": attributes,
},
timeout=10,
)
response.raise_for_status()
return response.json()["data"]["pass"]
def verify_webhook_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
if not signature_header or not signature_header.startswith("sha256="):
return False
digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
expected = f"sha256={digest}"
return hmac.compare_digest(signature_header, expected)
3. PHP: Pass ausstellen/aktualisieren & Webhooks verifizieren
<?php
function upsertPassinstancePass(string $templateId, string $externalId, array $attributes): array {
$payload = json_encode([
'templateId' => $templateId,
'externalId' => $externalId,
'attributes' => $attributes,
], JSON_THROW_ON_ERROR);
$ch = curl_init('https://api.passinstance.com/api/v1/passes/upsert-by-external-id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'x-api-key: ' . getenv('PASSINSTANCE_API_KEY'),
],
]);
$raw = curl_exec($ch);
curl_close($ch);
return json_decode($raw, true, 512, JSON_THROW_ON_ERROR)['data']['pass'];
}
function verifyPassinstanceWebhook(string $rawBody, string $signatureHeader, string $secret): bool {
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
return hash_equals($expected, $signatureHeader);
}
4. cURL: Schnelle CLI-Referenz
curl -X POST "https://api.passinstance.com/api/v1/passes/upsert-by-external-id" \
-H "Content-Type: application/json" \
-H "x-api-key: pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1" \
-d '{
"templateId": "6f2c5130-2f2a-4f40-8c68-f7192c5b4f43",
"externalId": "cust_9012",
"attributes": {
"memberName": "Clara Oswald",
"points": 1250,
"tier": "GOLD"
}
}'
Paginierung von Offline-Scanner-Snapshots
GET /api/v1/scans/offline-dataset erfordert x-scanner-key und liefert den Scanner-Snapshot innerhalb einer Antwort mit success, data und metadata. Verwenden Sie auf allen Seiten denselben Wert für snapshotAt.
| Parameter / Antwortfeld | Typ | Beschreibung |
|---|---|---|
limit | number | Pässe pro Seite (Standard 500, Maximum 1000). |
cursor | string | Verwenden Sie data.nextCursor der vorherigen Antwort; bei der ersten Anfrage weglassen. |
snapshotAt | string (ISO 8601) | Übernehmen Sie data.snapshotAt der ersten Antwort als obere Snapshot-Grenze für weitere Seiten. |
data.passes | Array | Pass-Snapshots im Geltungsbereich der Scanner-Konfiguration. |
data.hasMore | boolean | Rufen Sie weitere Seiten ab, solange dieser Wert true ist. |
data.nextCursor | string | Bei data.hasMore === true als cursor verwenden; auf der letzten Seite fehlt dieses Feld. |
Entdecken Sie Live-OpenAPI-Schemas unter /docs, testen Sie mit unserer Bruno-Collection unter Testen & Debugging oder entwerfen Sie Pass-Vorlagen mit KI unter Ersten Wallet-Pass erstellen.
