# Leitfaden zur Partner Open API Mit der **Partner Open API** von QCode verwalten Sie Ihr Reseller-Konto programmatisch: Sie fragen Guthaben und Nutzung ab und erstellen und verwalten die Sub-API-Keys, die Sie weiterverkaufen. So können Sie Bereitstellung, Abgleich und Key-Ausgabe in Ihre eigenen Systeme integrieren, statt das Web-Panel manuell zu bedienen. > ⚠️ **Voraussetzung: Sie müssen zuerst als Partner freigegeben sein.** > Diese API steht **ausschließlich freigegebenen QCode-Partnern** zur Verfügung. Wenn Sie noch kein Partner sind, [bewerben Sie sich zuerst](https://qcode.cc/partner-program). Nach der Freigabe können Sie ein Access Token erzeugen und die API aufrufen. --- ## 1. Was diese API leistet Als QCode-Partner haben Sie ein Reseller-Konto (vorausbezahltes Guthaben, stufenabhängiger Rabattfaktor) und können mehrere **Sub-API-Keys** erstellen, die Sie an Ihre eigenen Kunden oder Ihr Team weiterverkaufen – jeweils mit eigenem Kontingent. Die Open API stellt diese Panel-Funktionen als REST-Endpunkte bereit: - **Lesen** – Kontoguthaben und Nutzung, tägliche Ausgaben der letzten 7 / 30 Tage, Liste aller Sub-API-Keys mit den Kosten pro Key. - **Schreiben** – einen Sub-API-Key erstellen (Klartext wird einmalig zurückgegeben), einen Sub-API-Key aktivieren / deaktivieren, Kontingent und Parallelität eines Keys aktualisieren. Ideal für Partner, die Key-Ausgabe und Abgleich in ihr eigenes Abrechnungssystem einbinden, Keys für nachgelagerte Kunden automatisch bereitstellen oder die Nutzung für das Monitoring abrufen möchten. --- ## 2. Partner werden (Voraussetzung) Diese API ist **erst nutzbar, wenn Ihr Partnerzugang freigegeben ist**. - **Noch kein Partner** → Auf der Seite [Partnerprogramm](https://qcode.cc/partner-program) finden Sie Stufen und Preise. Bewerben Sie sich anschließend über den Abschnitt „So bewerben Sie sich“ (E-Mail an `hi@qcode.cc`). Nach der Freigabe wird Ihr Konto als Partner-Konto aktiviert. - **Bereits Partner** → Melden Sie sich im [Partner-Dashboard](https://qcode.cc/reseller/dashboard) an. > Das Onboarding umfasst eine vorausbezahlte Aufladung und eine Partnerstufe (A–E, jeweils mit anderem Rabattfaktor); Details finden Sie auf der Seite [Partnerprogramm](https://qcode.cc/partner-program). Ein Aufruf dieser API mit einem nicht aktivierten Konto liefert `403`. --- ## 3. Schnellstart: Access Token abrufen Nach der Freigabe: 1. Melden Sie sich bei [qcode.cc](https://qcode.cc) an und öffnen Sie das **Partner-Dashboard**. 2. Öffnen Sie **„Open API / Access Token“**. 3. Klicken Sie auf **Generate token**, um ein Token wie `rsk_xxxxxxxx` zu erhalten. > 🔑 **Das Token wird nur einmal vollständig angezeigt, beim Erzeugen bzw. Zurücksetzen.** Kopieren Sie es und bewahren Sie es sicher auf (wir speichern nur den Hash). Bei Verlust oder Kompromittierung klicken Sie auf derselben Seite auf **Reset**, um es zu erneuern; das **alte Token wird sofort ungültig**. --- ## 4. Authentifizierung & Base-URL | Element | Wert | |---|---| | Base-URL (empfohlen) | `https://api.r.qcode.cc` | | Alternative | `https://qcode.cc` (gleiche API) | | Authentifizierung | Header `Authorization: Bearer rsk_xxxxxxxx` | | Schreib-Body | JSON, mit `Content-Type: application/json` | ```bash curl https://api.r.qcode.cc/api/v1/reseller/balance \ -H "Authorization: Bearer rsk_xxxxxxxx" ``` --- ## 5. Endpunkt-Referenz Alle Endpunkte liegen unter dem Präfix `/api/v1/reseller/`. | Methode | Pfad | Beschreibung | |---|---|---| | GET | `/api/v1/reseller/me` | Kontoübersicht (Stufe, Region, Währung, Status) | | GET | `/api/v1/reseller/balance` | Guthaben und Nutzung (in Ihrer Abrechnungswährung) | | GET | `/api/v1/reseller/usage?range=7d` | Tägliche Ausgabenreihe (`range` = `7d` / `30d`) | | GET | `/api/v1/reseller/keys` | Ihre Sub-API-Keys auflisten + Kosten pro Key | | GET | `/api/v1/reseller/keys/{id}` | Details zu einem einzelnen Key | | POST | `/api/v1/reseller/keys` | Sub-Key erstellen (**Klartext wird einmalig zurückgegeben**) | | POST | `/api/v1/reseller/keys/{id}/enable` | Key aktivieren | | POST | `/api/v1/reseller/keys/{id}/disable` | Key deaktivieren | | PATCH | `/api/v1/reseller/keys/{id}` | Kontingent / Parallelität aktualisieren | --- ## 6. Erstellen eines Sub-API-Keys Limits sind in **Anbieter-USD** angegeben. `daily_cost_limit_usd` und `total_cost_limit_usd` müssen **größer als 0** sein. Senden Sie einen `Idempotency-Key`-Header, um Wiederholungen sicher zu gestalten (damit ein Timeout-Retry nicht zwei Keys erzeugt). Der Klartext-Key `cr_…` wird **nur einmal** zurückgegeben — speichern Sie ihn und übergeben Sie ihn an Ihren Kunden. ```bash curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys \ -H "Authorization: Bearer rsk_xxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: unique-per-create" \ -d '{"description":"client-a","daily_cost_limit_usd":5,"total_cost_limit_usd":100,"concurrency_limit":5}' # → {"ok":true,"data":{"id":"...","name":"...","api_key":"cr_...","warnings":[]}} ``` Aktivieren / Deaktivieren, Kontingent aktualisieren: ```bash # disable curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys/{id}/disable \ -H "Authorization: Bearer rsk_xxxxxxxx" # change daily limit curl -X PATCH https://api.r.qcode.cc/api/v1/reseller/keys/{id} \ -H "Authorization: Bearer rsk_xxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"daily_cost_limit_usd":10}' ``` --- ## 7. Rate Limits Dies sind Management-Endpunkte mit geringer Frequenz; die Rate Limits reduzieren die Auswirkung eines geleakten Tokens: - Pro Token: **60 / Minute**, **1000 / Tag**. - Erstellen von Keys (`POST /keys`): **5 / Stunde** pro Token. - Überschreiten eines Limits gibt HTTP **429** mit einem `Retry-After`-Header (Sekunden) zurück. --- ## 8. Antworten & Fehler - Erfolg: `{"ok": true, "data": { ... }}` - Fehler: der entsprechende HTTP-Status + `{"detail": "..."}` | Status | Bedeutung | |---|---| | 401 | Ungültiges oder fehlendes Token | | 403 | Konto nicht aktiv (Partnerzugang nicht genehmigt / gesperrt) | | 404 | Key nicht gefunden oder gehört Ihnen nicht | | 422 | Validierungs- / Kontingentfehler | | 429 | Rate Limit erreicht | --- ## 9. Sicherheit - Behandeln Sie das Zugriffstoken wie ein Passwort: bewahren Sie es serverseitig auf, nur über HTTPS, **niemals** in ein Repo committen oder im Browser offenlegen. - Falls ein Token durchsickert → setzen Sie es umgehend im Panel **zurück** (altes Token wird ungültig) und deaktivieren Sie bei Bedarf betroffene Sub-Keys. - Setzen Sie sinnvolle `total` / `daily` Limits für jeden Sub-Key, den Sie erstellen, um den Verlust zu begrenzen, falls ein einzelner Key leakt. - Die `cr_…` Sub-Keys, die Sie ausgeben, belasten Ihr Kontoguthaben — verwalten und rechnen Sie sie sorgfältig ab. --- ## 10. Vollständiges Referenzhandbuch & Support - Nach der Freischaltung ist die Seite **„API Docs“** im Partner Dashboard (`/reseller/api-docs`) die maßgebliche, versionierte Entwicklerreferenz. - Noch kein Partner? → [Informationen zum Partnerprogramm und Bewerbung](https://qcode.cc/partner-program) - Fragen? → Live-Chat auf der Website oder E-Mail an `hi@qcode.cc`.