Skip to main content

API-Referenz

🚀 Einführung​

Die PunchFlow API bietet eine vollständige RESTful-Schnittstelle für die Integration von PunchOut-Funktionalität in Ihre B2B-E-Commerce-Umgebung.

Base URL​

https://api.punchflow.de/api/v1

Authentifizierung​

PunchFlow verwendet Bearer Token-Authentifizierung für alle API-Anfragen:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.punchflow.de/api/v1/merchants

API-Schlüssel erhalten​

  1. Registrieren Sie sich unter app.punchflow.de
  2. Navigieren Sie zu Einstellungen → API-Schlüssel
  3. Generieren Sie einen neuen API-Schlüssel
Sicherheitshinweis

Behandeln Sie API-Schlüssel wie Passwörter. Teilen Sie sie niemals öffentlich und rotieren Sie sie regelmäßig.

Rate Limiting​

  • Globales Standard-Limit: 100 Anfragen pro Minute und Zugangsschlüssel (konfigurierbar)
  • Endpoint-spezifische Limits: Sensible Aktionen wie Checkout sind zusätzlich strenger abgesichert (z. B. 3 öffentliche Checkout-Versuche pro IP und Stunde)

Header-Informationen:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1700000000

Antwortstruktur​

Die Endpunkte liefern individuelle, in den Pydantic-Schemas definierten Antworten. Häufige Muster:

Erfolgreiche Antwort (Beispiel Checkout)​

{
  "success": true,
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "error": null
}

Fehlerantwort​

  • Eigene Fehler der API folgen dem Schema des jeweiligen Endpunkts, z. B.:
{
  "success": false,
  "error": "Checkout-Session konnte nicht erstellt werden"
}
  • Validierungsfehler von FastAPI/Pydantic verwenden das Standardschema:
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

HTTP Status Codes​

CodeBedeutung
200OK - Anfrage erfolgreich
201Created - Ressource erstellt
204No Content - Erfolgreich ohne Antwort
400Bad Request - Ungültige Anfrage
401Unauthorized - Authentifizierung erforderlich
403Forbidden - Keine Berechtigung
404Not Found - Ressource nicht gefunden
429Too Many Requests - Rate Limit erreicht
500Internal Server Error - Serverfehler

Versionierung​

Die API verwendet URL-basierte Versionierung:

  • Aktuelle Version: v1
  • Legacy-Support: 12 Monate nach Release neuer Version

Beispiel-Implementierungen​

JavaScript/TypeScript​

// Direkte API-Nutzung mit fetch
const response = await fetch('https://api.punchflow.de/api/v1/merchants', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const merchants = await response.json();

Python​

import requests

# Direkte API-Nutzung
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.punchflow.de/api/v1/merchants',
    headers=headers
)

merchants = response.json()

PHP​

// Direkte API-Nutzung mit cURL
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.punchflow.de/api/v1/merchants',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$merchants = json_decode($response, true);
curl_close($curl);

Test-Umgebung​

Für Tests verwenden Sie dieselbe API mit Test-API-Keys:

https://api.punchflow.de/api/v1

Test-Features:

  • Test-API-Keys für sichere Tests
  • Test-Shops für Validierung
  • Keine echten Transaktionen mit Test-Keys
  • Vollständige API-Funktionalität

Webhooks​

Konfigurieren Sie Webhooks für Echtzeit-Events:

Verfügbare Events​

  • punchout.session.created
  • punchout.session.completed
  • order.created
  • order.updated
  • merchant.connected
  • merchant.disconnected

Webhook-Payload​

{
  "event": "punchout.session.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "session_id": "sess_123456",
    "merchant_id": "merch_789",
    // Event-spezifische Daten
  },
  "signature": "sha256=..."
}

Signatur-Verifizierung​

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

Pagination​

Listen-Endpoints unterstützen Pagination:

GET /v1/merchants?page=2&limit=50

Response-Header:

X-Total-Count: 250
X-Page-Count: 5
Link: <.../merchants?page=3&limit=50>; rel="next",
      <.../merchants?page=1&limit=50>; rel="prev",
      <.../merchants?page=5&limit=50>; rel="last"

Fehlerbehandlung​

Retry-Strategie​

Bei 5xx-Fehlern empfehlen wir Exponential Backoff:

    1. Versuch: Nach 1 Sekunde
    1. Versuch: Nach 2 Sekunden
    1. Versuch: Nach 4 Sekunden
  • Maximum: 3 Versuche

Idempotenz​

Verwenden Sie Idempotenz-Keys für kritische Operationen:

curl -H "Idempotency-Key: unique_key_123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -X POST https://api.punchflow.de/api/v1/orders

Support & Hilfe​

API-Status​

Überprüfen Sie den aktuellen API-Status:

Entwickler-Support​

Postman Collection​

Importieren Sie unsere Postman-Collection für schnelles Testen: Download Collection

Nächste Schritte​

Last updated on by Jannih