Skip to content
Helpcentrum-gids · Ontwikkelaarstools
2 min leestijdGecontroleerd 2026-11-16

Integratiehulpmiddelen

Gebruik SDK-tokens, geparametriseerde dynamische Wallet-URL's, AI-.pkpass-workflows en OpenAPI-definities.

In deze gids

Overzicht

Om de backend-integratie in Node.js/TypeScript-, Python-, PHP- en shell-omgevingen te versnellen — naast de ontwikkelaarshulpmiddelen in het Dashboard op /settings/workspace/integrations/link-generator, /settings/workspace/developer/embed-sdk, /settings/workspace/developer/sdks, /settings/workspace/developer/query-helper en /settings/workspace/developer/qr-generator — biedt deze handleiding productiepatronen voor idempotente pas-upserts (POST /api/v1/passes/upsert-by-external-id), geparametriseerde downloadlinks (PARAMETERIZED_PASS_LINK / CREATE_PASS_URL), cursorgebaseerde paginering en constante-tijd HMAC-SHA256-webhookverificatie.

Belangrijk: Synchroniseer een bedrijfsrecord via upsert op (templateId, externalId). De geretourneerde pas staat in data.pass en het resultaat in data.action (CREATED of UPDATED). Stuur bij POST /api/v1/passes een Idempotency-Key-header zodat herhaalde pogingen dezelfde aanmaakaanvraag gebruiken. Het upsert-endpoint verwerkt deze header niet.

Stroom voor idempotente upsert en cursorpaginering

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: IDEMPOTENTE UPSERT & CURSORPAGINERINGSPATROON
DEELNEMENDE SYSTEEMACTOREN
P1 Uw backendapplicatie
P2 Passinstance REST API (/api/v1)
STAP 1 VERZOEK / ACTIE POST/passes/upsert-by-external-id
›
{ templateId, externalId, attributes }
›
Match (templateId + externalId)
›
Maak aan indien nieuw OF patch & push indien bestaand
STAP 2 ANTWOORD 200 OK data: { pass, action }
STAP 3 VERZOEK / ACTIE GET/scans/offline-dataset
›
?limit=250
STAP 4 ANTWOORD 200 OK { data: { passes, nextCursor: "c_1" } }
STAP 5 VERZOEK / ACTIE GET/scans/offline-dataset
›
?limit=250&cursor=c_1&snapshotAt=...
STAP 6 ANTWOORD 200 OK { data: { passes, hasMore: false } }

Productiecodepatronen in meerdere talen

1. Node.js / TypeScript: Hulpfunctie voor idempotente pas-upsert

TYPESCRIPT
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: Idempotente upsert en HMAC-webhookverificateur

PYTHON
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: Een pas uitgeven en bijwerken + webhooks verifiëren

PHP
<?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: Snelle CLI-referentie

BASH
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"
    }
  }'

Paginering van offline scannersnapshots

GET /api/v1/scans/offline-dataset vereist x-scanner-key en retourneert de snapshot in een antwoord met success, data en metadata. Gebruik op alle pagina’s dezelfde snapshotAt.

Parameter / AntwoordveldTypeBeschrijving
limitnumberPassen per pagina (standaard 500, maximaal 1000).
cursorstringGebruik data.nextCursor uit het vorige antwoord; laat dit weg bij de eerste aanvraag.
snapshotAtstring (ISO 8601)Gebruik data.snapshotAt uit het eerste antwoord als bovengrens van de snapshot voor volgende pagina’s.
data.passesArrayPassnapshots binnen het bereik van de scannerconfiguratie.
data.hasMorebooleanHaal meer pagina’s op zolang deze waarde true is.
data.nextCursorstringGebruik als cursor wanneer data.hasMore true is; dit veld ontbreekt op de laatste pagina.

Verken live OpenAPI-schema's op /docs, test met onze Bruno-collectie in Testen en debuggen, of ontwerp passjablonen met AI in Uw eerste wallet-pas maken.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.