Przejdź do treści
Perly
ZacznijZacznij za darmo

Poradniki

Przepis: kredyty API

Sprzedawaj przedpłacone kredyty do API lub funkcji AI i pobieraj jeden za zapytanie. Gdy saldo nie wystarcza — odpowiedź 402 z linkiem do doładowania.

Otwórz jako Markdown

Kupujący z góry opłacają pakiet kredytów; każde zapytanie zużywa kilka. Rozliczenie prowadzi Perly Pay: zużycie to jedno atomowe wywołanie, które nie schodzi poniżej zera, a każdy kupujący ma własną stronę doładowania. Nic nie jest pobierane samo — gdy kredyty się skończą, kupujący doładowuje. Wszystko o kredytach jest w Sell credits; tutaj przepis wokół nich.

Z asystentem: ten przepis realizuje w Twoim projekcie skill sell-credits wtyczki Perly Pay. Działający przykład to examples/api-credits (MIT) w repozytorium wtyczki.

Jak to działa

  1. 1

    Pakiet kredytów

    Produkt i cena z model: "credit_pack", unit_amount w centach i credits. Raz na tryb.

  2. 2

    Twoi użytkownicy to klienci

    Tworzeni raz z external_id (Twoim identyfikatorem użytkownika); potem credits.* przyjmują ten identyfikator.

  3. 3

    Doładowanie

    credits.topUpUrl(userId) to własna strona kupującego: wybiera pakiet i płaci. Każdy opłacony pakiet dodaje kredyty.

  4. 4

    Zużycie za zapytanie

    Najpierw credits.consume(userId, cost, { idempotencyKey }), potem praca. Ponowienie z tym samym kluczem zwraca pierwsze pobranie, więc klucz dla każdego zapytania tworzy Twój serwer i nigdy nie bierze go od wywołującego.

  5. 5

    Brakuje?

    insufficient_credits (409) niczego nie pobiera: odpowiedz 402 ze stroną doładowania, a nie 500.

Spend one request's credits
try {
  await pay.credits.consume(userId, cost, { product: PRODUCT, action: "api", idempotencyKey: `req-${userId}-${requestId}` });
} catch (e) {
  if (e.code !== "insufficient_credits") throw e;
  return reply(402, { top_up: await pay.credits.topUpUrl(userId, { product: PRODUCT }) });
}
// now do the work

Uruchom przykład

  1. 1

    Zainstaluj

    npm install w examples/api-credits (Node 20.12+).

  2. 2

    Klucz

    Skopiuj .env.example do .env i wpisz klucz testowy (sk_test_…) w PERLY_PAY_SECRET_KEY.

  3. 3

    Przygotuj

    npm run setup tworzy produkt i cenę Twoim kluczem i drukuje ich identyfikatory do .env.

  4. 4

    Uruchom

    npm start (lub npm run dev), jak mówi jego README.

  5. 5

    Zapłać bez portfela

    Wywołaj POST /v1/shout (402), otwórz stronę, którą daje POST /top-up, wybierz pakiet, kliknij Simulate payment na fakturze i wywołaj ponownie: 200 i X-Credits-Remaining: 499.

Pułapki

  • Zużycie bez klucza idempotencji: powtórzone zapytanie pobiera dwa razy.
  • Klucz pobrania z tego, co wysyła klient (nagłówek Idempotency-Key): ten sam klucz zwraca pierwsze pobranie jako sukces i klient znowu dostaje pracę bez zapłaty.
  • Sprawdzanie salda, a potem pobieranie w dwóch krokach. consume sam nie schodzi poniżej zera; saldo służy do wyświetlania.
  • Najpierw praca, potem zużycie. Odwrotnie: najpierw zużycie.
  • Testowe identyfikatory z kluczem produkcyjnym. Produkty, ceny i webhooki należą do jednego trybu: przed startem powtórz konfigurację z sk_live_….