Facturation

PricklyMails facture depuis un portefeuille de jetons, pas par requête. Chaque plan accorde une allocation mensuelle de jetons, et chaque contrôle de vérification coûte un nombre fixe de jetons, débités à l'usage.

Le modèle de portefeuille

Une requête de vérification réserve son coût estimé sur votre portefeuille à la soumission. Une fois le job terminé, le worker valide la réservation (débitant exactement les contrôles exécutés) ou la rembourse (par exemple quand un contrôle comme le SMTP est ignoré face à un fournisseur qui bloque RCPT TO). Vous n'êtes jamais facturé que pour les contrôles réellement exécutés.

Config des plans et de la tarification

GET /api/config est public et non authentifié : il renvoie la grille des plans (allocation mensuelle de jetons, prix, limite de débit, nombre de clés max, taille de batch max), la tarification des recharges, et le coût par contrôle, pour que vous puissiez construire une interface de tarification directement depuis le backend plutôt qu'en la codant en dur.

curl https://api.pricklymails.com/api/config

Solde du portefeuille

GET /api/wallet renvoie votre solde actuel : available, reserved (retenu par les jobs en cours), total, et avg_daily_spend (une moyenne sur 30 jours, utile pour estimer l'autonomie restante).

Historique des transactions

GET /api/wallet/transactions liste vos entrées de grand livre, les plus récentes en premier par défaut, paginé (limit par défaut 20, plafond 96 ; offset). Triez avec sort (occurred_at, amount, ou transaction_type) et order (desc ou asc). Chaque entrée porte job_uuid, le job de vérification lié, null pour un crédit ou une recharge.

GET /api/wallet/transactions/grouped renvoie le même grand livre regroupé par vérification : une entrée par job_uuid (un crédit ou une recharge autonome est sa propre entrée) portant le dernier statut du cycle de vie, l'effet net en tokens, et l'historique ordonné des réservations, débits et annulations. Mêmes sort, order et pagination que /api/wallet/transactions.

GET /api/wallet/balance-history renvoie une série de votre solde disponible, remplie à zéro et triée du plus ancien au plus récent, pour un graphique. Accepte granularity (hour, day, week, ou month) et days.

Abonnement

GET /api/subscription renvoie votre plan actif, son statut, le cycle de facturation, la période en cours et l'allocation mensuelle de crédits. Il renvoie un plan Free synthétique avec un HTTP 200 quand vous n'avez jamais souscrit, donc l'endpoint ne renvoie jamais 404.

Checkout et portail de facturation

POST /api/billing/checkout crée une session de paiement Stripe hébergée pour un abonnement à un plan ou une recharge de jetons ponctuelle, et renvoie l'URL de redirection. POST /api/billing/portal crée une session pour le portail client Stripe (gérer les moyens de paiement, consulter les factures). Les deux renvoient 503 Service Unavailable tant que la facturation Stripe n'est pas configurée sur le compte.