Reseller-API: Codes und Tarife
Chargen einlösbarer Codes ausgeben und widerrufen, Codes in Schlüssel einlösen und Tarife verwalten mit der OneProvider-Reseller-API. Mit Beispielen.
Chargen einlösbarer Codes ausstellen, widerrufen, einen Code in einen Schlüssel einlösen und Ihre Tarife über die Reseller-API verwalten.
Alle Modelle, Funktionen und Preise Dokumentationsindex für KI-Agenten:https://oneprovider.dev/docs/llms.txt Code-Chargen
Eine Charge wird mit POST /code-batches erstellt (Scope codes; der Header Idempotency-Key ist erforderlich): label, count bis zu 200, amount_usd bis zu 5000 pro Code. Optional: key_expires_days oder key_expires_hours (wie lange der Schlüssel nach der Aktivierung des Codes lebt, Standard 90 Tage) oder key_expires_never: true (ein unbefristeter Schlüssel, das Limit gilt weiter; nicht zusammen mit einer Lebensdauer) sowie codes_valid_until (bis wann ein Code aktiviert werden kann, ISO 8601, in der Zukunft und höchstens 2 Jahre voraus; danach werden die nicht aktivierten Codes automatisch widerrufen, und die Reserve wird freigegeben).
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'Eine Charge reserviert nur ihre Kosten (count × amount_usd) auf dem Reseller-Guthaben: Sie muss in „Verfügbar“ passen, es wird aber nichts abgebucht. Wird ein Code aktiviert, wird er zu einem Schlüssel, dessen Limit reserviert bleibt, und das Geld wird beim Verbrauch abgebucht. Das Widerrufen nicht aktivierter Codes gibt die Reserve frei. Chargenobjekt: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, key_expires_never, codes_valid_until, created_at (key_expires_hours und key_expires_days sind sowohl bei einer Charge ohne Schlüssellaufzeit als auch bei einer Charge mit der Standardlaufzeit von 90 Tagen null: key_expires_never unterscheidet sie). GET /code-batches/{id} enthält außerdem activations: wer welchen Code wann aktiviert hat (code_tail, redeemed_at, key_id), die neuesten zuerst, höchstens 1000; die Antwort auf das Widerrufen enthält außerdem revoked_now und refunded_usd.
# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"Codeobjekt: code, status (active, used, revoked: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Status eines einzelnen Codes: GET /codes/{code}.
Einen Code über die API einlösen
Wenn Sie einen Code selbst in einen Schlüssel verwandeln, rufen Sie POST /codes/{code}/redeem auf (der Header Idempotency-Key ist erforderlich). Den Kunden können Sie als customer_id oder customer_external_id übergeben.
curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'Die Antwort 201 enthält den Schlüssel und sein Secret (eine Wiederholung desselben Aufrufs mit demselben Idempotency-Key liefert denselben Schlüssel). Ein auf anderem Weg bereits eingelöster Code ergibt 409 code_used, ein widerrufener 409 code_revoked; customer_id zusammen mit customer_external_id ist 400 invalid, ein gesperrter Kunde ist 409 customer_blocked.
Tarife
Ein Tarif ist Ihr Preis für Kunden: wie viele USD der Schlüssel erhält, wie viel der Kunde Ihnen zahlt, in welcher Währung und für wie lange. Tarife sind die Grundlage für POST /orders (der Parameter plan_id). Das Maximum sind 20 Tarife (409 plan_limit). Zum Lesen von Tarifen braucht es den Scope read, zum Ändern den Scope plans.
| Feld | Beschreibung |
|---|---|
name | Name, bis zu 40 Zeichen. |
balance_usd | Der Betrag, den der Schlüssel erhält. |
price, currency | Ihr Preis für den Kunden und seine Währung: USD, RUB, XTR oder USDT. |
expires_days / expires_hours | Lebensdauer des Schlüssels: 1 bis 365 Tage oder 1 bis 8760 Stunden (eines von beiden; Standard 30 Tage). Die Antwort enthält expires_hours (die maßgebliche Angabe); expires_days ist null, wenn die Lebensdauer keine ganze Zahl von Tagen ist. |
expires_never | true: Die Schlüssel des Tarifs laufen nie ab (das Guthabenlimit gilt weiter). Nicht zusammen mit expires_days oder expires_hours (400 invalid). Die Antwort hat dann expires_hours und expires_days gleich null. |
sort, active | Anzeigereihenfolge und das Aktiv-Flag. |
curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"GET /pricing liefert die einzuhaltenden Grenzen: minimaler und maximaler Schlüsselbetrag, maximale Lebensdauer, maximaler Codebetrag, Chargengröße, die Zahl der Tarife und Tokens, die Zahl der aktiven Schlüssel (key_limit) und plan_currencies (die Währungen der Tarife). Ein Tarif lässt sich mit einem Idempotency-Key (optional) erstellen: Eine Wiederholung liefert denselben Tarif statt eines zweiten. Ein PATCH, der die Lebensdauer nicht erwähnt, lässt sie unverändert. Löschen, Preiserhöhung und Währungswechsel werden abgelehnt, solange ein Bot-Kauf zu diesem Tarif offen ist (409 plan_in_use).