So verbinden Sie Ihre App oder Ihr ERP mit der QuoteCrest API

In Teil 1 haben wir einen QuoteCrest-Arbeitsbereich konfiguriert — Stripe, Buchhaltungssync, Steuersätze, Geschäftsbedingungen und eine Artikelbibliothek. Jetzt verbinden wir diesen Arbeitsbereich mit Ihrer eigenen Anwendung oder Ihrem ERP, damit Angebote durch Ihre bestehenden Systeme fließen statt durch einen Browser-Tab.

Die QuoteCrest REST API stellt Teams im Business-Plan die volle App-Oberfläche zur Verfügung: Angebote und Positionen, Kunden, die Artikelbibliothek, Steuersätze, Vorlagen für Geschäftsbedingungen, Zahlungen, den KI-Angebotsgenerator und Auslöser für den Buchhaltungssync. Die vollständige Referenz finden Sie unter quotecrest.com/api-docs; dieser Beitrag ist die geführte Tour von null bis zum ersten API-Aufruf.

Schritt 1: Eine OAuth-Anwendung registrieren

Gehen Sie in QuoteCrest zu Einstellungen → Entwickler und klicken Sie auf Anwendung registrieren. Sie brauchen drei Dinge:

Name — wird Ihrem Team auf dem Autorisierungsbildschirm angezeigt („ERP Sync", „Acme Field App").
Redirect URI — wohin QuoteCrest Benutzer nach der Autorisierung schickt. Muss HTTPS sein (localhost ist für die Entwicklung erlaubt). Eine URI pro Zeile.
Scopes — read für Lesezugriff, write zum Erstellen und Aktualisieren. Fordern Sie nur an, was Sie brauchen.

Lassen Sie Vertraulicher Client für serverseitige Apps aktiviert, die ein Geheimnis schützen können. Bei der Erstellung erhalten Sie eine Client ID und — genau einmal — ein Client Secret. Kopieren Sie das Secret sofort; es wird gehasht gespeichert und kann nicht erneut angezeigt werden.

Schritt 2: Mit OAuth 2.0 + PKCE autorisieren

QuoteCrest verwendet den Authorization Code Grant mit PKCE, verpflichtend für jeden Client. Der Ablauf:

1. Code Verifier und Challenge erzeugen. Eine zufällige Zeichenkette und ihr SHA-256-Hash, base64url-codiert:

code_verifier  = random 43-128 char string
code_challenge = base64url( sha256(code_verifier) )

2. Den Benutzer zum Autorisierungsbildschirm schicken:

GET https://quotecrest.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &response_type=code
    &scope=read+write
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Der Benutzer meldet sich an, sieht, was Ihre App tun darf, und stimmt zu. QuoteCrest leitet mit einem ?code=-Parameter zurück zu Ihrer redirect_uri.

3. Den Code gegen Tokens eintauschen:

curl -X POST https://quotecrest.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/callback \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=CODE_VERIFIER

Sie erhalten ein access_token (2 Stunden gültig), ein refresh_token und die gewährten Scopes. Access Tokens sind an ein Team gebunden — das Team des Benutzers, der autorisiert hat. Refresh Tokens rotieren bei jeder Verwendung: Jeder Refresh liefert ein neues Paar, und das alte Refresh Token wird ungültig — speichern Sie das neueste Paar daher atomar.

Schritt 3: Ihren ersten Aufruf machen

Jede Anfrage sendet das Token als Bearer-Header. Beginnen Sie mit /me — der Endpunkt liefert das autorisierte Team, seine Standardwerte (Zahlungsbedingungen, Angebotsablauf, Preismodus) und die Scopes Ihres Tokens:

curl https://quotecrest.com/api/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Listen-Endpunkte paginieren mit page und per_page (maximal 100) und liefern einen meta-Block mit Gesamtzahlen.

Schritt 4: Der zentrale ERP-Flow

Eine typische Integration spiegelt, was ein Mensch in der App tut — Kunden anlegen, Angebot erstellen, versenden und auf Annahme und Zahlung achten.

Einen Kunden anlegen:

curl -X POST https://quotecrest.com/api/v1/clients \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": {"name": "Meridian Property Group", "email": "ops@meridian.example"}}'

Ein Angebot erstellen — Team-Standardwerte (Bedingungsvorlage, Ablauf, Zahlungsbedingungen, Preismodus) gelten automatisch für alles, was Sie weglassen:

curl -X POST https://quotecrest.com/api/v1/quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quote": {"title": "Lobby renovation", "client_id": 42, "payment_percentage": 30}}'

Positionen hinzufügen in einem Aufruf mit bulk_create, dann versenden:

curl -X POST https://quotecrest.com/api/v1/quotes/7/line_items/bulk_create ...
curl -X POST https://quotecrest.com/api/v1/quotes/7/send \
  -H "Authorization: Bearer ACCESS_TOKEN"

send schickt dem Kunden per E-Mail seinen Portal-Link; verwenden Sie stattdessen publish, wenn Ihre App den Link selbst zustellt. Das Feld portal_url des Angebots ist die kundenseitige Seite, und GET /api/v1/quotes/7/pdf liefert die gerenderte PDF für Ihre eigene Dokumentenablage.

Annahme und Zahlung verfolgen Sie per Polling des Angebots (status, payment_status, payment_due) oder durch Auflisten von /api/v1/payments — jede Zahlung enthält Betrag, Gebühren und Nettobetrag. Wird ein Angebot mit aktivierter Auto-Synchronisierung angenommen, landet die Rechnung ohne weiteren API-Aufruf in QuickBooks oder Xero; einen Katalogabruf können Sie außerdem jederzeit mit POST /api/v1/integrations/quickbooks/sync (oder xero) auslösen.

Oder überspringen Sie den manuellen Aufbau komplett. Ein einziger Aufruf des KI-Angebotsgenerators verwandelt eine Auftragsbeschreibung in Alltagssprache in einen vollständigen Entwurf — Titel, Leistungsumfang und bepreiste Positionen, die Ihre Artikelbibliothek und Kategorien nutzen:

curl -X POST https://quotecrest.com/api/v1/ai_quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Replace 12 windows in a two-story office, energy-efficient double glazing", "client_id": 42}'

Fehler, Limits und gutes Benehmen

401 — Token fehlt, ist abgelaufen oder widerrufen. Refresh durchführen und erneut versuchen.
403 plan_required — das Team ist nicht im Business-Plan. 403 feature_disabled — ein Feature-Flag (z. B. KI-Generierung) ist für das Team deaktiviert.
402 insufficient_credits — das KI-Guthaben des Teams ist aufgebraucht.
422 — Validierungsfehler, mit Details im Response-Body.
429 — Rate Limit erreicht. Allgemeiner API-Verkehr ist pro IP begrenzt; die KI-Generierung ist auf 10 Anfragen pro Minute und Team begrenzt. Warten Sie ab und versuchen Sie es nach der angegebenen Verzögerung erneut.

Zwei Gewohnheiten halten Ihre Integration langweilig (im guten Sinne): Behandeln Sie das Client Secret und Refresh Tokens wie Passwörter — nur serverseitig, verschlüsselt gespeichert — und bauen Sie Ihre Synchronisierung idempotent auf, indem Sie vor dem Erstellen prüfen, ob ein Datensatz bereits existiert, denn Ihre Benutzer können Dinge jederzeit direkt in QuoteCrest bearbeiten.

Die vollständige Endpunkt-Referenz, Schemas und Fehlerformate finden Sie unter quotecrest.com/api-docs. Wenn Sie etwas auf Basis der API bauen, würden wir wirklich gern davon hören.