Leitfaden zur Partner Open API

Sobald Sie als QCode-Partner freigegeben sind, verwalten Sie Ihr Reseller-Konto programmatisch mit einem Access Token: Guthaben und Nutzung abfragen, die von Ihnen weiterverkauften Sub-API-Keys erstellen und aktivieren bzw. deaktivieren. Behandelt Voraussetzung, Bewerbung, Authentifizierung, Endpunkt-Referenz, Rate Limits und Sicherheit.

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. 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 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 an.

Das Onboarding umfasst eine vorausbezahlte Aufladung und eine Partnerstufe (A–E, jeweils mit anderem Rabattfaktor); Details finden Sie auf der Seite Partnerprogramm. 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 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¶

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/.

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.

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:

# 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": "..."}

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
• Fragen? → Live-Chat auf der Website oder E-Mail an hi@qcode.cc.