← Residual ReachBlog ↗
Documentation

API Reference

Residual Reach expose une API REST sécurisée par JWT Supabase. Toutes les routes authentifiées nécessitent un cookie de session valide.

Base URL — https://reach.residual-labs.fr
Auth — Supabase JWT (cookie session)
Format — JSON / FormData

⚠️ Authentification

Les routes marquées Auth required nécessitent d'être connecté via Supabase Auth. Le cookie de session (sb-hhxxeozkpytdabhtvezy-auth-token) est automatiquement envoyé par le navigateur. Pour une intégration serveur-à-serveur, utilisez un Bearer token Supabase dans l'en-tête Authorization.

Campagnes

POST/api/campaigns/[id]/runAuth required

Lance le pipeline complet (audit + génération IA + envoi SMTP) pour une campagne.

Réponse
{ ok: boolean, runId: string }
POST/api/campaigns/[id]/crawlAuth required

Déclenche le scraping Apify (Pages Jaunes / Google Maps) pour alimenter une campagne en prospects.

Corps
{ limit?: number }  // défaut: 50
Réponse
{ ok: boolean, runId: string }
POST/api/campaigns/[id]/followupAuth required

Lance la relance automatique J+5 pour les prospects au statut "envoyé" sans réponse.

Réponse
{ ok: boolean, runId: string }

Clés API (BYOK)

POST/api/keysAuth required

Enregistre ou met à jour une clé API chiffrée (AES-256-GCM) pour un fournisseur (groq, apify, smtp).

Corps
{ provider: "groq"|"apify"|"smtp", key: string, smtpConfig?: { host, port, user } }
Réponse
{ ok: boolean }
DELETE/api/keysAuth required

Supprime la clé chiffrée d'un fournisseur.

Corps
{ provider: "groq"|"apify"|"smtp" }
Réponse
{ ok: boolean }

Facturation (Stripe)

POST/api/stripe/checkoutAuth required

Crée une session Stripe Checkout pour souscrire à un plan (starter, growth, agency).

Corps
{ plan: "starter"|"growth"|"agency" }  // FormData
Réponse
302 → Stripe Checkout URL
POST/api/stripe/portalAuth required

Crée une session Stripe Customer Portal pour gérer l'abonnement, la carte bancaire et les factures.

Réponse
302 → Stripe Portal URL
POST/api/stripe/webhook

Reçoit les événements Stripe signés (checkout.completed, subscription.updated/deleted, invoice.paid).

Corps
Stripe-Signature header requis
Réponse
{ received: true }

Webhooks entrants

POST/api/webhooks/resend

Reçoit les événements Resend (bounce, spam complaint) et ajoute automatiquement l'email à la blacklist globale.

Corps
Svix-Signature header requis (whsec_...)
Réponse
{ ok: true }
POST/api/webhooks/audit

Reçoit les résultats d'audit de Residual Audit (audit.completed) et met à jour les prospects en base.

Corps
X-Audit-Signature header requis (HMAC-SHA256)
Réponse
{ ok: true }

RGPD

GET/optout?email=...

Affiche la page de désinscription RGPD pour le prospect identifié par son email.

Réponse
HTML — formulaire de confirmation
POST/api/optout

Marque un prospect comme "refusé" et l'ajoute à la blacklist globale.

Corps
{ email: string }
Réponse
{ ok: boolean }

Sécurité des webhooks

Tous les webhooks entrants vérifient la signature cryptographique de l'émetteur avant traitement :

  • StripeHMAC-SHA256 via stripe.webhooks.constructEvent() · stripe.js
  • ResendSvix (HMAC-SHA256, tolerance 5min) · whsec_... secret
  • Residual AuditHMAC-SHA256 · AUDIT_WEBHOOK_SECRET

Rate limits

POST /api/campaigns/[id]/runLimité par quota mensuel (plan Stripe)
POST /api/campaigns/[id]/crawlLimité par concurrence Trigger.dev
POST /api/keys10 req/min par utilisateur
POST /api/stripe/checkout5 req/min par utilisateur
POST /api/optoutIllimité (RGPD)
Residual ReachBlogÀ proposMentions légalesConfidentialité