Zamówienia w API resellera

Zbuduj własny sklep: klient płaci tobie, ty wywołujesz POST /orders i dostajesz klucz. Idempotentność po external_order_id i doładowania istniejących kluczy.

Przebieg sprzedaży

1. Twój klient płaci tobie na twojej stronie przez własną kasę (OneProvider nie uczestniczy w tej płatności).
2. Twój serwer otrzymuje potwierdzenie płatności i wywołuje POST /orders.
3. OneProvider rezerwuje limit klucza na twoim saldzie resellera (pieniądze są pobierane w miarę wydawania) i tworzy zamówienie ze statusem completed.
4. Przekazujesz klientowi klucz z odpowiedzi oraz, jeśli chcesz, dashboard_url.

Zamówienie albo wydaje nowy klucz (kind: "new_key"), albo doładowuje istniejący (kind: "topup", gdy przekazano key_id).

Utworzenie zamówienia

To, co należy dostarczyć, określa plan (plan_id, zobacz Kody i plany ) albo bezpośrednio kwota: limit_usd oraz expires_days lub expires_hours. Klienta można przekazać jako customer_id lub customer_external_id (utworzonego wcześniej klienta). Pola charged_amount i charged_currency zapisują, ile klient ci zapłacił; zasilają GET /stats i nie wpływają na obciążenie.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key to obiekt klucza (jak w odpowiedzi na wydanie), sekret jest w key.key. Pojawia się tylko dla nowego klucza, w odpowiedzi na POST /orders (i w jej dokładnym powtórzeniu); GET /orders i GET /orders/{id} go nie zawierają. Zapisz sekret w tej samej transakcji, w której zapisujesz zamówienie. Gdy zamówienie powstaje z planu bez terminu (expires_never), klucz ma expires_at równe null.

Idempotentność po external_order_id

external_order_id to numer zamówienia w twoim systemie. Powtórzenie żądania z tym samym numerem i tymi samymi parametrami nie wydaje drugiego klucza ani nie pobiera pieniędzy dwa razy: dostajesz z powrotem to samo zamówienie i ten sam klucz (z tym samym sekretem, więc odpowiedź zgubioną po drodze można odzyskać, powtarzając wywołanie). Ten sam numer z innymi parametrami daje 409 external_order_id_conflict. Dzięki temu można bezpiecznie ponawiać po przekroczeniu czasu lub zerwanym połączeniu. Zamówienie znajdziesz przez GET /orders?external_order_id=shop-1042.

Doładowanie istniejącego klucza

Przekaż key_id i kwotę (limit_usd lub plan):

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

W odpowiedzi kind ma wartość topup i nie ma sekretu. Kwota jest dodawana do łącznego limitu klucza i jak wszystko musi się zmieścić w pozycji Dostępne (jest rezerwowana i pobierana w miarę wydawania).

Przykład obsługi płatności (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

Obserwuj available_usd i zasubskrybuj webhook balance.low, aby doładować saldo, zanim zamówienie trafi na 409 insufficient_balance. Zobacz Webhooki .