Zum Inhalt
Perly
StartenKostenlos starten

Anleitungen

Rezept: API-Credits

Verkaufen Sie vorausbezahlte Credits für eine API oder eine AI-Funktion und buchen Sie pro Anfrage einen ab. Reicht das Guthaben nicht, gibt es eine 402 mit Aufladelink.

Als Markdown ansehen

Käufer bezahlen ein Credit-Paket im Voraus; jede Anfrage verbraucht ein paar. Die Buchhaltung führt Perly Pay: Ein Verbrauch ist ein atomarer Aufruf, der nie ins Minus geht, und jeder Käufer hat eine eigene Aufladeseite. Nichts wird von selbst abgebucht – gehen die Credits aus, lädt der Käufer auf. Alles über Credits steht unter Sell credits; hier geht es um das Rezept drumherum.

Mit einem Assistenten: Dieses Rezept setzt der Skill sell-credits des Perly-Pay-Plugins in Ihrem Projekt um. Ein lauffähiges Beispiel ist examples/api-credits (MIT) im Repository des Plugins.

So funktioniert es

  1. 1

    Ein Credit-Paket

    Ein Produkt und ein Preis mit model: "credit_pack", unit_amount in Cent und credits. Einmal pro Modus.

  2. 2

    Ihre Nutzer sind Kunden

    Einmal mit external_id (Ihre Nutzer-ID) angelegt; danach nehmen credits.* diese ID an.

  3. 3

    Aufladen

    credits.topUpUrl(userId) ist die eigene Seite des Käufers: Er wählt ein Paket und zahlt. Jedes bezahlte Paket fügt Credits hinzu.

  4. 4

    Verbrauch pro Anfrage

    Erst credits.consume(userId, cost, { idempotencyKey }), dann die Arbeit. Eine Wiederholung mit demselben Schlüssel liefert die erste Abbuchung zurück, daher erzeugt Ihr Server den Schlüssel pro Anfrage und nimmt ihn nie vom Aufrufer.

  5. 5

    Zu wenig?

    insufficient_credits (409) bucht nichts ab: Antworten Sie mit 402 und der Aufladeseite, nicht mit 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

Beispiel starten

  1. 1

    Installieren

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

  2. 2

    Schlüssel

    Kopieren Sie .env.example nach .env und tragen Sie einen Testschlüssel (sk_test_…) in PERLY_PAY_SECRET_KEY ein.

  3. 3

    Vorbereiten

    npm run setup legt mit Ihrem Schlüssel Produkt und Preis an und gibt ihre IDs für .env aus.

  4. 4

    Starten

    npm start (oder npm run dev), wie seine README sagt.

  5. 5

    Ohne Wallet bezahlen

    Rufen Sie POST /v1/shout auf (402), öffnen Sie die Seite, die POST /top-up liefert, wählen Sie ein Paket, klicken Sie auf der Rechnung auf Simulate payment und rufen Sie erneut auf: 200 und X-Credits-Remaining: 499.

Fallstricke

  • Verbrauch ohne Idempotenzschlüssel: Eine wiederholte Anfrage bucht doppelt ab.
  • Den Abbuchungsschlüssel aus dem nehmen, was der Client sendet (Header Idempotency-Key): Derselbe Schlüssel liefert die erste Abbuchung als Erfolg zurück, und der Client bekommt die Arbeit erneut ohne Bezahlung.
  • Erst das Guthaben prüfen, dann in zwei Schritten abbuchen. consume geht selbst nie ins Minus; das Guthaben ist zum Anzeigen da.
  • Erst die Arbeit, dann der Verbrauch. Umgekehrt: erst der Verbrauch.
  • Test-IDs mit einem Live-Schlüssel. Produkte, Preise und Webhooks gehören zu einem Modus: Wiederholen Sie die Einrichtung vor dem Start mit sk_live_….