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 solde la réservation :

• Un résultat neuf débite les contrôles exécutés.
• Une réponse définitive obtenue sans la sonde de boîte débite toute la réservation : une adresse chez Google, Microsoft ou Yahoo, qui acceptent tous les destinataires et rendent la sonde inutile, ou un domaine qui ne peut manifestement pas recevoir de courrier. Vous payez la réponse, pas une sonde qui ne pouvait pas la changer.
• Un résultat unknown ne débite que les contrôles qui ont répondu et rembourse les sondes de boîte et de catch-all ; si rien n'a répondu, toute la réservation est remboursée.
• Un résultat servi depuis le cache de vérification est gratuit : toute la réservation est remboursée. Un résultat récent de la même adresse est réutilisé s'il a exécuté tous les contrôles demandés, ou s'il s'agit d'une des réponses définitives ci-dessus, qu'aucune sonde de boîte ne pouvait changer.

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 : la série contient les intervalles entiers compris dans ces jours, en finissant par l'intervalle en cours, donc day sur 8 jours renvoie 8 points et month sur 364 jours en renvoie 12.

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. La page hébergée, affichée dans la locale facultative que vous passez (en par défaut, ou fr), demande à l'acheteur d'accepter les conditions générales de vente avant de payer. 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.