SnapPact Business — Dokumentation

Wie es funktioniert

Ihr erzeugt einen Vertrag über die Business-API und bekommt sofort einen QR-Code zurück. Eure Kundschaft scannt ihn mit der normalen SnapPact-App und unterschreibt dort ganz regulär — Face ID/Touch ID/Fingerabdruck, echte fortgeschrittene elektronische Signatur (FES). Ihr müsst selbst nichts signieren oder prüfen, das übernimmt SnapPact komplett.

Anwendungsfälle

Authentifizierung

Jeder Aufruf braucht den Header X-Business-Key mit eurem Schlüssel (erstellbar hier im Business-Portal unter "API-Zugriff" oder in der SnapPact-App unter Profil → Business → API-Zugriff — beides verwaltet dieselben Schlüssel). Schlüssel niemals im Frontend/Client-seitigen Code eurer eigenen Website verwenden — nur serverseitig aufrufen.

1. Vertrag erstellen

curl -X POST https://api.snappact.ortino.tech/business/contracts \
  -H "X-Business-Key: sk_business_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl-goods-sale",
    "initiatorName": "Muster GmbH",
    "values": {
      "item_description": "iPhone 14 Pro, 256GB, Space Schwarz",
      "price": "1500",
      "known_defects": "Keine bekannten Mängel"
    }
  }'

{
  "contractId": "ctr_...",
  "qrValue": "snappact://handshake/<token>",
  "qrImageUrl": "/business/contracts/ctr_.../qr.png",
  "sessionToken": "<token>",
  "expiresAt": "2026-09-22T18:35:00.000Z"
}

qrValue zeigt auf snappact://handshake/<token> (App-Scan) ODER auf eine Web-Adresse (https://sign.snappact.ortino.tech/h/<token>, scannbar mit der normalen Handy-Kamera, kein App-Download nötig) — je nachdem, ob der Web-Weg für dieses Konto wirksam ist ("Web-Weg"-Einstellung in diesem Portal). Welcher der beiden Fälle gerade gilt, steht nicht in dieser Antwort, aber ihr müsst nichts unterscheiden: beide Werte sind gültige, direkt scannbare QR-Inhalte, die zum selben Vertrag führen.

values ist nur für Felder optional, die laut Vorlage NICHT euch (der initiierenden Seite) als Pflichtfeld zugewiesen sind. Ist ein Feld für euch Pflicht (assignedTo: 'initiator', required: true — bei den meisten Vorlagen der Fall, siehe Beispiel oben mit drei Pflichtfeldern — oder assignedTo: 'either', required: true, siehe unten), lehnt der Server die Anfrage ohne diesen Wert mit 400 required_fields_missing ab (welche Feld-IDs fehlen, steht im Feld fields der Fehlerantwort). Felder, die ausdrücklich der Gegenpartei zugewiesen sind, dürft ihr dagegen nicht vorbefüllen (der Server lehnt das mit 409 value_not_assigned_to_you ab) — die trägt die Gegenpartei selbst in der App ein. Welche Felder eine Vorlage hat und wem sie zugewiesen sind, liefert GET /templates bzw. GET /business/templates mit (siehe "Verfügbare Vorlagen" unten).

2. QR-Code anzeigen

Zwei Wege — beide zeigen denselben Code, beide laufen serverseitig (der Business-Key bleibt dabei dort, nie im Browser eurer Endkund:innen):

• Einfachste Variante: qrImageUrl serverseitig mit eurem X-Business-Key-Header abrufen (fertiges PNG) und selbst an eure Endkund:innen ausliefern — z.B. als data:-URI in die von euch gerenderte Seite einbetten (empfohlen), oder über einen eigenen Bild-Endpoint eurer Website weiterreichen. Achtung, falls ihr Letzteres tut: das PNG enthält den Beitritts-Token im Klartext (als QR-Code) — wer es abrufen kann, kann dem Vertrag beitreten. Ein solcher Endpoint darf also nicht aufzählbar sein (nie eine fortlaufende Bestell-/Kundennummer als Pfad), sondern an die unerratbare contractId gebunden, und sollte nach Ablauf von expiresAt nichts mehr ausliefern.
• Volle Kontrolle: qrValue selbst mit einer eigenen QR-Bibliothek rendern (z.B. npm-Paket qrcode für Node, qrcode.js im Browser, qrcode-Pip-Paket für Python) — braucht keinen weiteren Aufruf an SnapPact.

3. Status abfragen

curl https://api.snappact.ortino.tech/business/contracts/ctr_... \
  -H "X-Business-Key: sk_business_..."

4. Webhook (optional, spart das Pollen)

Beim Erstellen eines API-Schlüssels eine Webhook-URL hinterlegen — SnapPact schickt dann automatisch einen POST mit { contractId, status, sealedAt, documentHash }, sobald der Vertrag versiegelt ist. Die Benachrichtigung geht an die URL genau des Schlüssels, mit dem der Vertrag erzeugt wurde.

Die URL muss https sein, auf ein öffentlich erreichbares Ziel zeigen und darf keine Zugangsdaten enthalten (https://benutzer:passwort@… wird mit 400 invalid_webhook_url abgelehnt — für eine Absicherung stattdessen die Signatur unten prüfen oder ein Geheimnis in den Pfad legen). Weiterleitungen (30x) werden nicht verfolgt, und nach 5 Sekunden ohne Antwort bricht SnapPact ab.

Signatur prüfen (empfohlen) — jede Zustellung trägt den Header X-SnapPact-Signature: sha256=<hex>. Das ist ein HMAC-SHA256 über den rohen Request-Body (die Bytes genau so, wie sie ankommen — nicht über ein neu serialisiertes JSON-Objekt). Als Geheimnis dient der SHA-256-Hex-Hash eures eigenen Business-Schlüssels: secret = sha256("sk_business_…"). SnapPact gibt dafür bewusst kein zusätzliches Secret aus: diesen Wert könnt ihr aus dem Schlüssel, den ihr ohnehin habt, jederzeit selbst berechnen, während er nirgends über die API ausgeliefert wird.

import crypto from 'node:crypto';

// WICHTIG: den ROHEN Body verwenden, z.B. express.raw({ type: 'application/json' })
app.post('/snappact-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = crypto.createHash('sha256').update(process.env.SNAPPACT_BUSINESS_KEY).digest('hex');
  const erwartet = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const erhalten = req.get('X-SnapPact-Signature') || '';

  const a = Buffer.from(erwartet);
  const b = Buffer.from(erhalten);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const { contractId, status, sealedAt, documentHash } = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(204);
});

Ohne diese Prüfung kann jede und jeder, der die Webhook-URL kennt (z.B. aus einem Proxy-Log), gefälschte Benachrichtigungen schicken, die aussehen wie von SnapPact. Widerruft ihr einen Schlüssel und legt einen neuen an, ändert sich damit auch das Signatur-Geheimnis.

Code-Beispiele

Node.js

const res = await fetch('https://api.snappact.ortino.tech/business/contracts', {
  method: 'POST',
  headers: {
    'X-Business-Key': process.env.SNAPPACT_BUSINESS_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tpl-goods-sale',
    initiatorName: 'Muster GmbH',
    values: {
      item_description: 'iPhone 14 Pro, 256GB, Space Schwarz',
      price: '1500',
      known_defects: 'Keine bekannten Mängel',
    },
  }),
});
const { contractId, qrImageUrl } = await res.json();

Python

import requests

res = requests.post(
    "https://api.snappact.ortino.tech/business/contracts",
    headers={"X-Business-Key": SNAPPACT_BUSINESS_KEY},
    json={
        "templateId": "tpl-goods-sale",
        "initiatorName": "Muster GmbH",
        "values": {
            "item_description": "iPhone 14 Pro, 256GB, Space Schwarz",
            "price": "1500",
            "known_defects": "Keine bekannten Mängel",
        },
    },
)
contract = res.json()

Fehlercodes

Verfügbare Vorlagen

Alle öffentlichen Vorlagen samt ID über GET /templates abrufbar (keine Authentifizierung nötig). Nicht jede davon ist für Business-Verträge nutzbar: Community-Vorlagen (badge: 'community') kann ihre Autor:in jederzeit umschreiben — da ihr selbst nie unterschreibt und die Gegenpartei allein abschliesst, würde sie so an einen Text gebunden, den weder ihr noch SnapPact geprüft habt. POST /business/contracts lehnt Community-Vorlagen deshalb mit 404 template_not_found ab, ausser es sind eure eigenen. Nutzbar sind SnapPact-eigene, geprüfte Vorlagen, "business-only"-Vorlagen und eure eigenen Vorlagen. Genau diese Menge liefert die Business-Liste (GET /business/templates, siehe unten), die auch das QR-Code-Werkzeug im Portal anbietet. Jede Vorlage enthält fields mit id, label, type, required und assignedTo ('initiator'/'counterparty'/'either') — genau diese Liste bestimmt, welche Werte ihr in values mitschicken müsst bzw. dürft (siehe Schritt 1 oben; 'either' gehört bei Business-Verträgen euch).

curl https://api.snappact.ortino.tech/business/templates \
  -H "X-Business-Key: sk_business_..."

GET /business/templates (mit eurem X-Business-Key) liefert genau die Vorlagen, aus denen ihr Verträge anlegen könnt — auch eure eigenen, noch nicht veröffentlichten Vorlagen-Entwürfe sowie kuratierte "business-only"-Vorlagen (für jedes Business-Konto nutzbar, im öffentlichen Marktplatz nicht sichtbar), aber keine fremden Community-Vorlagen. Nützlich, um die Feldliste einer Vorlage programmatisch abzufragen, statt sie hier in der Doku nachzuschlagen. Das Feld origin sagt, woher eine Vorlage stammt: 'snappact' (SnapPact-eigene, geprüfte Vorlage), 'business_only' (kuratierte Business-Vorlage) oder 'own' (eure eigene Vorlage, Entwurf oder selbst veröffentlicht); badge enthält zusätzlich die Kennzeichnung der Vorlage selbst.

Vorlagen über die API befüllen (je Feldtyp)

Jedes Feld einer Vorlage (aus GET /templates bzw. GET /business/templates) hat ein type — das bestimmt, welche Art von Wert in values[fieldId] erwartet wird. Wichtig zu wissen: in Contract.values ist jeder Wert technisch ein String (auch eine Zahl oder ein Datum) — der Server prüft die meisten Typen NICHT auf ein bestimmtes Format (nur Länge und ob sie zur richtigen Seite gehören, siehe "Vertrag erstellen" oben). Die untenstehenden Formate sind deshalb Empfehlungen, damit euer Wert in der SnapPact-App genauso aussieht, wie es eure Kundschaft erwartet — mit einer einzigen Ausnahme, die wirklich streng geprüft wird: lineItems.

values: {
  positions: JSON.stringify([
    { description: "Beratung", quantity: 2, unit: "Std.", unitPrice: 150 },
    { description: "Material", quantity: 1, unitPrice: 45.50 },
  ])
}

Einstellungen im Detail

Jede Einstellung im Portal — was sie bewirkt, wann ihr sie ändern solltet, und warum sie so und nicht anders funktioniert.

Web-Weg verstehen

Der "Web-Weg" ist SnapPacts Bezeichnung dafür, dass eure Kundschaft einen Vertrag im Browser ansehen und (nach Anmeldung) ausfüllen kann, ohne vorher die SnapPact-App installiert zu haben — gedacht für den Fall, dass jemand euren QR-Code scannt und die App noch gar nicht kennt.

Ob der Web-Weg für einen konkreten Vertrag wirksam ist, hängt von einer einzigen, klaren Regel ab:

• Der Firmenname ist freigegeben (siehe "Einstellungen im Detail" oben), UND
• entweder der Konto-Schalter ("Web-Weg für dieses Konto aktivieren") ist an, oder der verwendete Schlüssel hat eine ausdrückliche Übersteuerung auf "an".
• Eine Schlüssel-Übersteuerung auf "aus" schaltet den Web-Weg für diesen einen Schlüssel immer ab, egal was der Konto-Schalter sagt.

Ohne Web-Weg (z.B. Name noch nicht freigegeben, oder Schalter aus) landet eure Kundschaft beim Scannen des QR-Codes direkt in der SnapPact-App (sofern installiert) — der bisherige, unveränderte Weg.

Diese Funktion wird schrittweise freigeschaltet. Meldet euch bei SnapPact, wenn ihr den Web-Weg für euer Konto nutzen möchtet.