Installer FastRestful sur votre ordinateur

Une première installation complète pour une personne qui n'a jamais exécuté une application Django ou Node. Suivez les étapes dans l'ordre. Chaque étape se termine par une vérification qui vous confirme qu'elle a fonctionné avant de passer à la suivante.

Avant de commencer

Vous n'avez pas besoin de Docker, Redis, de stockage cloud ni d'un compte de paiement pour la démo locale. SQLite et un cache en mémoire simplifient le premier lancement.

1. Vérifiez vos outils

Exécutez ces commandes dans votre terminal. Si un outil manque, installez-le d'abord puis rouvrez le terminal.

python3.11 --version
node --version
npm --version
git --version

Vous devez voir Python 3.11, Node 22.13 ou une version plus récente, ainsi qu'une version de npm. Si python3.11 est introuvable, installez Python 3.11 depuis python.org. Si Node est antérieur à 22.13, installez la version LTS actuelle depuis nodejs.org.

2. Téléchargez le code

git clone <your-fastrestful-repository> fastrestful
cd fastrestful
npm ci

npm ci installe les versions exactes des dépendances frontend à partir du fichier de verrouillage. Cela peut prendre quelques minutes. Vous devez obtenir un dossier node_modules et aucun message d'erreur.

3. Créez l'environnement backend

Un environnement virtuel isole les paquets Python de FastRestful du reste de votre ordinateur.

cd backend
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Sous Windows PowerShell, activez avec .venv\Scripts\Activate.ps1 au lieu de source .venv/bin/activate. Lorsque l'environnement est actif, votre invite commence généralement par (.venv).

4. Créez le fichier de configuration du backend

Copiez le fichier d'exemple, puis générez deux secrets et collez-les dans backend/.env.

cp .env.example .env
python3.11 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
python3.11 -c "import secrets; print(secrets.token_urlsafe(64))"

1. Ouvrez backend/.env dans n'importe quel éditeur de texte.
2. Collez la première sortie dans FIELD_ENCRYPTION_KEY=. Cette clé chiffre les clés API et les secrets des fournisseurs.
3. Collez la deuxième sortie dans DJANGO_SECRET_KEY=.
4. Laissez DJANGO_DEBUG=True, DATABASE_URL=sqlite:///db.sqlite3 et FRONTEND_URL=http://localhost:5055 pour le développement local.

5. Créez la base de données et les données de démonstration

Vérifiez que l'environnement virtuel est toujours actif et que vous vous trouvez dans backend/.

python3.11 manage.py migrate
python3.11 manage.py seed_demo
python3.11 manage.py seed_apis
python3.11 manage.py seed_docs
python3.11 manage.py seed_engagement

migrate crée les tables de la base de données. Les commandes d'amorçage créent une place de marché de démonstration, des produits API, du contenu de documentation et des profils communautaires. Cela génère un fichier local backend/db.sqlite3.

6. Démarrez le backend

# inside backend/, with the virtual environment active
python3.11 manage.py runserver 127.0.0.1:5056

Laissez ce terminal ouvert. Le backend est prêt lorsqu'il affiche Starting development server at http://127.0.0.1:5056/. Vérifiez-le dans un autre terminal avec :

curl http://127.0.0.1:5056/api/health/live

7. Démarrez le frontend

Ouvrez le second terminal et revenez à la racine du dépôt. Le backend doit rester en cours d'exécution dans le terminal 1.

cd /path/to/fastrestful
npm run dev -- --port 5055 --host 127.0.0.1

Le serveur de développement Vite redirige les routes Django (/api/v1, /api/health, /api/schema, /api/docs, /admin, /static, /media) vers le backend sur le port 5056. Les pages produit publiques telles que /api/{slug} sont toujours servies par le frontend.

8. Ouvrez l'application et connectez-vous

Ouvrez ces adresses dans votre navigateur :

Connectez-vous au plan de contrôle avec admin / Admin12345!.

Liste de vérification du premier lancement

• Le site public se charge et le catalogue de la place de marché est visible.
• Le plan de contrôle s'ouvre et vous pouvez vous connecter en tant que admin.
• Paramètres du site, Forfaits de la plateforme et la section de contenu du site s'ouvrent sans erreur.
• Un compte consommateur peut créer une application et une clé API.
• Une requête via la passerelle apparaît dans les journaux de requêtes.

Que faire ensuite

• Suivez Démarrage rapide : votre première requête via la passerelle pour effectuer un appel API compté.
• Lisez Configuration pour comprendre quels paramètres importent en premier.
• Connectez les paiements avec Passerelles de paiement, étape par étape lorsque vous êtes prêt à encaisser de l'argent réel.
• Consultez Déploiement avant de mettre l'application sur un serveur public.

Problèmes d'installation courants

Démarrage rapide : votre première requête via la passerelle

Passez d'une installation locale neuve à un appel API compté. Vous allez vous abonner à une API de démonstration, créer une clé, envoyer une requête et consulter l'événement d'utilisation ainsi que le journal de la requête.

1. Connectez-vous et choisissez un espace de travail

Ouvrez http://127.0.0.1:5055 et connectez-vous avec admin / Admin12345!, ou créez un nouveau compte. Un espace de travail (organisation) regroupe vos applications, clés, abonnements et factures.

L'espace de travail actif est transmis dans l'en-tête X-Organization pour les appels API. La console du navigateur le définit automatiquement. Lorsque vous appelez l'API vous-même, vous devez l'inclure, sauf si la requête utilise une clé API au lieu d'une session navigateur.

2. Abonnez-vous à un produit

Ouvrez la place de marché, choisissez un produit disposant d'une version en production et sélectionnez un forfait. Le produit SignalStack préchargé dispose d'une version 2.4.0 en production et de trois forfaits.

Si le forfait est gratuit, l'activation est immédiate. S'il est payant, FastRestful ouvre le fournisseur de paiement configuré. Une redirection du navigateur ne donne jamais accès à elle seule : l'abonnement ne s'active qu'après le règlement de la première facture par un webhook signé du fournisseur.

3. Créez une application et une clé

Dans la console consommateur, créez une application puis générez une clé API. La clé brute n'est affichée qu'une fois : copiez-la immédiatement dans un gestionnaire de mots de passe ou dans un fichier local .env.

fr_live_<random-secret>

# Store it in a secret manager or local .env file.
# Never commit it to a repository or paste it into a public issue.

Les portées sont full, execute ou read. Choisissez la portée la plus restrictive qui fonctionne. Si vous perdez la clé, révoquez-la et générez-en une nouvelle ; l'ancienne clé cesse immédiatement de fonctionner.

4. Envoyez une requête via la passerelle

Remplacez fr_live_… par la clé que vous venez de créer. Cet exemple utilise le produit SignalStack préchargé et son alias de chemin.

curl --request GET \
  --url 'http://127.0.0.1:5055/api/v1/signal-stack/v2/deliveries?limit=10' \
  --header 'X-API-Key: fr_live_…' \
  --header 'Idempotency-Key: quickstart-001'

Lorsque le routage par hôte produit est activé, la même requête utilise https://{product-slug}.{FASTRESTFUL_API_HOST_SUFFIX}/.... Les deux points d'entrée partagent le même abonnement, quota, limite de débit, idempotence, comptage et pipeline de journalisation des requêtes.

5. Inspectez le résultat

• Événement d'utilisation : enregistré côté serveur avec le statut et la latence.
• Compteur mensuel : incrémenté pour l'application du quota et le dépassement.
• Journal de requête : aperçus expurgés de la requête et de la réponse, visibles par le consommateur et le fournisseur.
• Tableau de bord : requêtes, taux de réussite, dépenses, latence, principales API et activité récente.

Ouvrez le tableau de bord consommateur et le journal des requêtes. Vous devez voir la requête que vous venez d'effectuer. Sinon, recherchez une trace d'erreur dans le terminal qui exécute le backend.

6. Publiez une version (facultatif)

Dans le studio fournisseur, ouvrez l'atelier d'un produit, importez un contrat OpenAPI dans une version brouillon, harmonisez la documentation des endpoints, lancez le diff, soumettez pour révision et promouvez. Une version en production exige un contrat OpenAPI pris en charge et non vide, ainsi qu'un catalogue d'endpoints parfaitement correspondant.

Pour le cycle de vie complet, consultez Produits API et versions.

Si la requête échoue

La configuration, sans surcharge

La plupart des installations ne nécessitent qu'un petit ensemble de paramètres pour fonctionner. Commencez par le minimum ci-dessous, puis ajoutez les intégrations que vous utilisez réellement. Les longs tableaux plus bas sont des références, pas une liste de vérification.

Où se trouvent les paramètres

Paramètres locaux minimaux

Après avoir copié .env.example, ce sont les seules valeurs à modifier pour la démo locale :

DJANGO_DEBUG=True
DJANGO_SECRET_KEY=<generated-random-value>
FIELD_ENCRYPTION_KEY=<generated-fernet-key>
DATABASE_URL=sqlite:///db.sqlite3
FRONTEND_URL=http://localhost:5055
CORS_ALLOWED_ORIGINS=http://localhost:5055,http://127.0.0.1:5055
CSRF_TRUSTED_ORIGINS=http://localhost:5055,http://127.0.0.1:5055

Générez les deux clés avec les commandes de Installation → Créer le fichier de configuration du backend.

Paramètres de production minimaux

La production ajoute PostgreSQL, Redis, un vrai nom d'hôte et des origines HTTPS. Remplacez chaque valeur d'exemple par vos propres valeurs.

DJANGO_DEBUG=False
DJANGO_SECRET_KEY=<50-plus-random-characters>
DJANGO_ALLOWED_HOSTS=api.example.com,www.example.com
DATABASE_URL=postgresql://user:password@db-host:5432/fastrestful
REDIS_URL=redis://redis-host:6379/0
FRONTEND_URL=https://www.example.com
CORS_ALLOWED_ORIGINS=https://www.example.com
CSRF_TRUSTED_ORIGINS=https://www.example.com
FIELD_ENCRYPTION_KEY=<fernet-key>

Comment modifier les paramètres en toute sécurité

1. Modifiez une intégration à la fois.

   Configurez, testez et vérifiez avant de passer au fournisseur suivant. Les défaillances deviennent ainsi évidentes.

2. Modifiez backend/.env sur le serveur.

   Ne modifiez pas les fichiers d'un conteneur en cours d'exécution qui sera remplacé. Stockez les secrets dans le coffre à secrets de votre plateforme de déploiement lorsque c'est possible.

3. Redémarrez le backend et les workers.

   Les modifications d'environnement sont lues au démarrage du processus. Redémarrez Gunicorn, le worker Celery et Celery beat après avoir modifié .env.

4. Reconstruisez le frontend pour les modifications de NEXT_PUBLIC_*.

   Les valeurs publiques du frontend sont compilées dans le build. Redémarrer le frontend ne suffit pas.

5. Lancez l'action de test du fournisseur.

   Utilisez le paiement de test, l'e-mail de test ou le journal de livraison des webhooks avant d'envoyer du trafic réel.

Référence de l'environnement principal

Environnement du frontend

Passerelle et routage par hôte

Authentification et SSO

E-mail et newsletter

Les paramètres SMTP de la newsletter peuvent aussi être stockés dans le studio newsletter et remplacer l'expéditeur défini dans l'environnement pour les campagnes. Voir Studio newsletter.

Référence des paiements et versements

Administration → Passerelles de paiement stocke les mêmes identifiants dans la base de données. Un enregistrement en base remplace champ par champ les valeurs de l'environnement, et sa désactivation coupe le fournisseur partout même si les clés d'environnement restent définies.

Stockage des médias et des spécifications

Liens courts

SHORTLINK_BASE_URL définit l'origine publique des liens courts, par exemple https://go.example.com. Si elle est vide, elle se replie sur NEWSLETTER_TRACKING_BASE_URL, puis sur FRONTEND_URL. La commande checklinks peut être planifiée via cron ou Celery beat.

Priorité et rechargements

• Les valeurs d'environnement fournissent les valeurs par défaut du déploiement ; les enregistrements de passerelle de l'administration les remplacent champ par champ.
• Les modifications de l'environnement backend nécessitent un redémarrage du processus. Certains paramètres mis en cache (indicateur de maintenance, langue source) sont vidés automatiquement lors de l'enregistrement du modèle.
• Les variables publiques du frontend sont intégrées au moment du build. Reconstruisez après avoir modifié les valeurs NEXT_PUBLIC_*.
• Après avoir modifié lib/i18n/*.json, exécutez npm run export:i18n et redémarrez le backend afin que son bundle source mis en cache soit à jour.

Déploiement

Faites passer FastRestful d'une démo SQLite locale à un déploiement en production avec PostgreSQL, Redis, du stockage objet, un serveur WSGI, TLS et un frontend statique. La plateforme est conçue pour être auto-hébergée.

Avant de déployer

• Un nom de domaine et un accès DNS pour les hôtes du frontend et de l'API.
• Une base de données PostgreSQL 16 et une instance Redis 7.
• La terminaison HTTPS, sur votre proxy ou en périphérie.
• Une DJANGO_SECRET_KEY générée et une FIELD_ENCRYPTION_KEY sauvegardée.
• Un plan pour le stockage des médias : le disque local n'est acceptable que pour un essai sur un seul serveur ; utilisez un stockage compatible S3 pour les déploiements réels.
• Une destination de sauvegarde en dehors du serveur d'application.

Ordre recommandé

1. Déployez le backend et la base de données.

   Assurez-vous que /api/health/ready répond avant de toucher au frontend.

2. Déployez le frontend.

   Pointez-le vers l'origine de l'API et ajoutez l'origine du frontend aux paramètres CORS et CSRF.

3. Configurez l'e-mail et le stockage.

   Utilisez Intégrations externes. Vérifiez un e-mail de test et un téléversement de test.

4. Ne connectez les paiements que lorsque vous êtes prêt à vendre.

   Utilisez Passerelles de paiement, étape par étape et effectuez d'abord le paiement de test.

5. Activez la licence et planifiez les signaux de vie.

   Utilisez Licences et mises à jour officielles.

6. Mettez en place les sauvegardes et la supervision.

   Utilisez Sauvegardes et mises à niveau et Observabilité.

Topologie recommandée

Internet
  │
  ├── app.example.com ──► frontend (static/CDN or Node runtime)
  │                           │
  │                           └── /api/* ──► reverse proxy ──► Gunicorn / Django
  │
  ├── api.example.com ──► reverse proxy ──► Gunicorn / Django
  ├── *.api.example.com ──► wildcard product gateway
  │
  ├── PostgreSQL 16 (primary)
  ├── Redis 7 (cache + Celery broker)
  ├── S3 + CloudFront (media, optional specs)
  └── Celery worker + beat (billing, moderation, email, availability)

Vous pouvez servir le frontend et l'API depuis une même origine ou les séparer. En cas de séparation, définissez NEXT_PUBLIC_API_URL sur l'origine de l'API, ajoutez l'origine du frontend à CORS_ALLOWED_ORIGINS et CSRF_TRUSTED_ORIGINS, et définissez FRONTEND_URL sur l'origine publique du frontend.

Docker Compose

Le dépôt inclut un fichier Compose avec PostgreSQL, l'API, Redis et des profils optionnels worker/beat.

export DJANGO_SECRET_KEY="$(openssl rand -base64 64 | tr -d '\n')"
export FIELD_ENCRYPTION_KEY="$(python3.11 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export DJANGO_ALLOWED_HOSTS="api.example.com,.api.example.com"
export CORS_ALLOWED_ORIGINS="https://app.example.com"
export CSRF_TRUSTED_ORIGINS="https://app.example.com"
export FRONTEND_URL="https://app.example.com"
export POSTGRES_PASSWORD="$(openssl rand -hex 24)"

docker compose up --build -d
docker compose --profile scheduler up --build -d

Exécutez les migrations et les amorçages dans le conteneur de l'API une fois la base de données opérationnelle :

docker compose exec api python manage.py migrate --noinput
docker compose exec api python manage.py seed_demo
docker compose exec api python manage.py seed_apis
docker compose exec api python manage.py seed_docs
docker compose exec api python manage.py collectstatic --noinput

Installation manuelle en production

Backend

cd /srv/fastrestful/backend
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gunicorn>=22.0 boto3 django-storages  # optional: S3 media

cp .env.example .env
# Fill production values, then:
python3.11 manage.py migrate --noinput
python3.11 manage.py collectstatic --noinput
python3.11 manage.py check --deploy

Gunicorn + systemd

[Unit]
Description=FastRestful Django API
After=network.target postgresql.service redis.service

[Service]
User=fastrestful
Group=fastrestful
WorkingDirectory=/srv/fastrestful/backend
EnvironmentFile=/srv/fastrestful/backend/.env
ExecStart=/srv/fastrestful/backend/.venv/bin/gunicorn \
  config.wsgi:application \
  --bind 127.0.0.1:8000 \
  --workers 3 \
  --timeout 60
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now fastrestful
sudo systemctl status fastrestful

Proxy inverse Nginx

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 8m;

    location /static/ {
        alias /srv/fastrestful/backend/staticfiles/;
        expires 30d;
        access_log off;
    }

    location /media/ {
        alias /srv/fastrestful/backend/media/;
        expires 7d;
        access_log off;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 65s;
    }
}

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

Hôte produit générique

server {
    listen 443 ssl http2;
    server_name *.api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;  # product slug comes from this host
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Ajoutez un enregistrement DNS générique, émettez un certificat générique avec un défi DNS-01 et incluez l'hôte générique dans DJANGO_ALLOWED_HOSTS. Définissez FASTRESTFUL_API_HOST_SUFFIX=api.example.com.

Build et hébergement du frontend

export NEXT_PUBLIC_API_URL="https://api.example.com"
export NEXT_PUBLIC_SITE_URL="https://app.example.com"
export NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_..."
npm run build

Déployez la sortie de build sur votre hébergeur statique ou un environnement d'exécution compatible Node. Le build est autonome et ne nécessite pas de plan de contrôle de site managé. Si vous utilisez Cloudflare, liez D1/Images uniquement lorsque le déploiement a besoin de ces fonctionnalités.

Fichiers statiques et médias

• Statique : exécutez collectstatic, servez /static/ depuis Nginx ou votre CDN.
• Médias locaux : servez /media/ depuis Nginx pour les petits déploiements.
• Médias de production : utilisez S3 + CloudFront avec OAC, gardez le bucket privé, définissez MEDIA_STORAGE=s3 et ne définissez pas MEDIA_S3_ACL sauf si vous servez directement depuis S3.
• Spécifications : laissez SPEC_STORAGE=db pour une petite installation ; utilisez S3 pour les archives de contrats plus volumineuses.

Contrôles de santé

Mises à niveau et sauvegardes

# 1. Back up PostgreSQL and media
pg_dump --format=custom "$DATABASE_URL" > fastrestful-$(date +%F).dump

# 2. Pull code and install dependencies
git pull --ff-only
pip install -r backend/requirements.txt
npm ci

# 3. Apply migrations and rebuild assets
python3.11 backend/manage.py migrate
npm run build

# 4. Restart API and workers
sudo systemctl restart fastrestful
sudo systemctl restart fastrestful-worker fastrestful-beat

# 5. Verify
curl -f https://api.example.com/api/health/ready

Critères de mise en production

• DJANGO_DEBUG=False, secret d'au moins 50 caractères, clé Fernet valide.
• PostgreSQL, Redis, origines HTTPS et hôtes autorisés explicites.
• Identifiants administrateur modifiés ; utilisateurs de démonstration supprimés ou désactivés.
• Webhooks de paiement et de versement enregistrés avec le secret signé correct.
• Identifiants SMTP et fournisseur testés ; domaine expéditeur authentifié.
• S3/CloudFront configurés si les téléversements de médias sont activés.
• Worker de planification + beat en cours d'exécution ou équivalents cron installés.
• Sauvegardes testées par restauration dans un environnement distinct.
• La supervision couvre la disponibilité, le taux de 5xx, la latence de la passerelle, les échecs de webhooks et la profondeur des files d'attente.
• Pages légales, conditions, confidentialité et contact du support vérifiés par l'opérateur.

Opérations

Le règlement planifié, l'envoi des notifications, les contrôles de disponibilité, la rétention de la télémétrie, les sondes de santé et les commandes d'exploitation qui maintiennent FastRestful en bonne santé.

Planification Celery

celery -A config worker -l info -Q billing,celery
celery -A config beat -l info

Sans broker, Celery s'exécute immédiatement dans le processus. En production, définissez REDIS_URL ou CELERY_BROKER_URL et exécutez le worker et beat en tant que services distincts.

Commandes d'exploitation

python3.11 manage.py generate_invoices --period 2026-10
python3.11 manage.py generate_payouts --period 2026-10
python3.11 manage.py prune_telemetry --request-log-days 90 --usage-event-days 365
python3.11 manage.py check_api_availability
python3.11 manage.py checklinks --limit 200 --timeout 6

Mode maintenance

Activez Opérations de la plateforme → Mode maintenance dans les paramètres du site. Le frontend renvoie une page 503 aux couleurs de la marque, les appels API des clients et de la passerelle renvoient une réponse maintenance_mode lisible par machine avec Retry-After: 300, et la documentation/Swagger sont suspendus.

L'administration des équipes, les sondes de santé, les callbacks du fournisseur d'identité et les webhooks signés de paiement/versement restent disponibles afin que la plateforme puisse récupérer en toute sécurité et que les fournisseurs ne soient pas abandonnés.

Supervision

• Sonde de disponibilité pour la base de données + le cache partagé.
• Taux de 5xx de l'API et latence p95 par namespace.
• Taux d'erreur amont de la passerelle et événements d'ouverture de circuit.
• File des échecs de webhooks et exceptions de versement.
• Profondeur de la file Celery et signal de vie de beat.
• Taux de rejet/plainte des e-mails et taux de désinscription.
• Croissance du stockage des médias et taux de succès du cache CDN.
• Connexions PostgreSQL, requêtes lentes, disque et réussite des sauvegardes.

Sauvegardes

Notes de mise à l'échelle

• Exécutez plusieurs instances Gunicorn/Django derrière un équilibreur de charge ; conservez les sessions et le cache sur Redis.
• Exécutez les workers Celery séparément des processus web et mettez à l'échelle indépendamment les files de facturation et par défaut.
• Les limites de débit de la passerelle utilisent le cache partagé ; une panne de cache renvoie un 503 réessayable plutôt que de laisser passer.
• Utilisez le pooling de connexions PostgreSQL si le nombre de workers augmente.
• Déplacez les médias vers S3/CloudFront avant que le trafic ne rende la gestion du disque local pénible.
• Définissez explicitement la rétention de la télémétrie ; les journaux de requêtes et les événements d'utilisation ne sont pas censés croître indéfiniment.

Sécurité

Les comportements critiques pour la sécurité dans FastRestful : la garde des clés, l'isolation des locataires, la protection SSRF de la passerelle, la politique d'origine du navigateur, le stockage des secrets, les preuves d'audit et la liste de durcissement pour la production.

Garde des clés API

• Les clés brutes ne sont renvoyées qu'une seule fois lors de la création ou de la rotation. Elles ne sont plus jamais affichées par les sérialiseurs ni par l'administration.
• Formes stockées : un préfixe de recherche, un hachage SHA-256 pour une comparaison à temps constant et une copie chiffrée avec Fernet pour l'utilisation côté serveur par la passerelle.
• La rotation révoque l'ancienne clé et en émet une nouvelle en un seul appel. Une clé révoquée ne peut pas servir à en émettre d'autres.
• Les portées restreignent l'accès : full, execute ou read. Les mises à jour ne peuvent que restreindre une portée, jamais l'élargir.
• Une clé est liée à son application et à son abonnement ; elle ne peut pas franchir les applications ni les espaces de travail.

Isolation des locataires

• X-Organization sélectionne le locataire actif. Les permissions côté serveur revérifient l'appartenance pour chaque objet.
• Les lectures fournisseur sont à double portée : un fournisseur voit ses propres produits, abonnements, factures et journaux ; un consommateur ne voit que son propre espace de travail.
• Les champs de propriété sont immuables via l'API.
• Les sérialiseurs publics sont explicites, et non des listes blanches d'un modèle privé. Les métriques opérationnelles et les champs privés restent exclus des réponses anonymes.
• Les superutilisateurs peuvent lire tous les locataires pour le support, mais les écritures nécessitent toujours la portée propriétaire correcte, sauf opérations explicites de la plateforme.

Sécurité de la passerelle

• Les amonts doivent utiliser HTTPS, résoudre vers des adresses publiques, rester sur l'hôte d'origine et éviter les motifs de traversée.
• Les redirections ne sont pas suivies. Les réponses DNS sont vérifiées et l'IP publique sélectionnée est épinglée au moyen de la connexion TLS pour empêcher le rebinding.
• Les délais d'expiration, les plafonds de corps, les plafonds de téléversement et les nouvelles tentatives bornées sont appliqués avant le transfert.
• Les secrets des fournisseurs sont ajoutés uniquement côté serveur ; ils n'atteignent jamais le navigateur.
• Les clés d'idempotence sont stockées sous forme de hachages de jetons avec une empreinte de requête et une réponse expurgée, jamais les corps de requête bruts.
• Les aperçus de réponse sont limités en longueur et expurgent Set-Cookie, Authorization et X-API-Key.
• Une panne du cache partagé renvoie un 503 réessayable avant la réservation de quota ; la passerelle ne laisse pas passer.

Sécurité du navigateur et des origines

• La production impose HTTPS, HSTS, des cookies sécurisés et une politique de référent stricte.
• CORS_ALLOWED_ORIGINS et CSRF_TRUSTED_ORIGINS doivent désigner exactement le frontend public.
• Les cookies CSRF sont lisibles par le frontend car la session Django partagée est utilisée pour les écritures de l'administration et de la console ; ne les exposez jamais en cross-origin.
• Les actifs CSS/JS personnalisés sont du contenu opérateur de confiance. Utilisez un nonce CSP, prévisualisez avant activation et consultez l'historique des révisions.
• Le mode maintenance maintient disponibles les callbacks des fournisseurs et les routes du fournisseur d'identité.

Gestion des secrets

Durcissement de l'authentification

• Activez l'authentification à deux facteurs obligatoire pour les équipes et, en option, pour tous les comptes dans les paramètres du site.
• Utilisez OIDC ou SAML pour l'identité d'entreprise ; la connexion par mot de passe peut rester comme solution de repli.
• Gardez les jetons d'accès de courte durée (15 minutes) et les jetons de rafraîchissement rotatifs sur liste noire après rotation.
• Les invitations sont hachées, à usage unique, liées à l'e-mail et expirent au bout de sept jours.
• L'accès administrateur nécessite is_staff ; l'espace de travail admin n'est pas un rôle du personnel de la plateforme.
• Les réponses de réinitialisation de mot de passe ne révèlent pas si un compte existe.

Audit et preuves

• Les actions d'administration, les décisions de modération, les changements d'état de facturation, la réconciliation des versements, les modifications de paramètres et la récupération de compte génèrent des événements d'audit.
• Les reçus d'événements du fournisseur sont en ajout seul et rejettent les conflits de charge utile, ce qui rend les nouvelles tentatives sûres.
• Les écritures du grand livre sont en ajout seul. Les remboursements après versement créent des écritures de récupération et d'annulation de frais.
• Les tâches d'export d'audit prennent en charge la conservation et la revue sans accès direct à la base de données.

Liste de contrôle de production

DJANGO_DEBUG=0 \
DATABASE_URL=postgresql://… \
REDIS_URL=redis://… \
FRONTEND_URL=https://app.example.com \
DJANGO_ALLOWED_HOSTS=api.example.com,.api.example.com \
CORS_ALLOWED_ORIGINS=https://app.example.com \
CSRF_TRUSTED_ORIGINS=https://app.example.com \
DJANGO_SECRET_KEY=<50+ chars> \
FIELD_ENCRYPTION_KEY=<fernet key> \
python3.11 manage.py check --deploy

• Comptes de démonstration et données d'initialisation supprimés de la production.
• Double authentification obligatoire pour le personnel ; SSO testé de bout en bout.
• Webhooks de paiement vérifiés avec le secret signé du fournisseur.
• Compartiment média privé ; OAC CDN configuré ; aucun accès en écriture générique.
• Sauvegardes chiffrées et testées en restauration.
• Les journaux excluent les secrets et masquent les charges utiles des consommateurs.
• Dépendances et images de conteneurs mises à jour selon un calendrier.
• Contact incident et procédure de divulgation des vulnérabilités publiés.

Licences & mises à jour officielles

FastRestful est un code source sous licence vendu par Dakidarts. Connectez la clé d'achat à LicenseHub pour vérifier les versions officielles signées, installer une version plus récente ou revenir à une version antérieure. La passerelle en cours d'exécution continue de fonctionner si LicenseHub est temporairement inaccessible.

Ce que fait le centre de mises à jour

Partie 1 — Activer votre licence

1. Acheter FastRestful et ouvrez le tableau de bord Dakidarts.

   Accédez à Tableau de bord → Licences et copiez la clé complète. Elle commence par DK-FRST-….

2. Ouvrez le centre de mises à jour.

   Connectez-vous en tant que membre du personnel et ouvrez https://your-domain/admin/updates/. La barre latérale l'appelle Mises à jour logicielles.

3. Collez la clé de licence.

   Utilisez la clé complète, y compris les tirets. Elle est chiffrée au repos et seule une forme masquée est affichée après activation.

4. Confirmez l'URL de LicenseHub.

   La valeur par défaut est https://dakidarts.com. Conservez-la, sauf si Dakidarts vous indique une autre origine. HTTPS est requis en dehors du débogage local.

5. Choisissez l'environnement.

   Production consomme un siège de production. Préproduction et Développement consomment des sièges hors production. Choisissez celui qui correspond à cette installation.

6. Ajoutez éventuellement le domaine de production.

   Par exemple api.example.com. Cela vous aide à identifier l'installation dans le portail client.

7. Choisissez un canal de publication.

   Commencez par Stable. N'utilisez Beta ou Preview que sur un environnement de test jetable.

8. Cliquez sur Activer la licence.

   L'activation crée ou réutilise un installation_id persistant et associe un siège. La page affiche ensuite l'édition, les fenêtres de mise à jour et de support, le nombre d'activations et le dernier battement de cœur.

Si l'activation échoue, l'erreur s'affiche sur la page. Les causes les plus fréquentes sont une clé expirée, une limite de sièges ou une clé copiée avec un espace final.

Partie 2 — Installer une mise à jour depuis l'administration

1. Effectuez une sauvegarde.

   Sauvegardez PostgreSQL, les médias, .env et tout fichier personnalisé. Vérifiez que la sauvegarde se restaure correctement avant d'en avoir besoin.

2. Ouvrez Admin → Mises à jour logicielles.

   La page affiche la version en cours d'exécution, la version installée et l'état de la connexion.

3. Cliquez sur Rechercher des mises à jour.

   LicenseHub renvoie toutes les versions couvertes par votre fenêtre de mise à jour : versions plus récentes, actuelle et antérieures.

4. Cliquez sur Télécharger & préparer pour la version cible.

   FastRestful télécharge chaque artefact, vérifie le SHA-256, vérifie la signature du manifeste Ed25519 et extrait le lot dans FASTRESTFUL_UPDATE_DIR/<version>/bundle/.

5. Cliquez sur Installer.

   L'administration démarre un processus de travail détaché afin que les migrations ou une compilation ne dépassent pas le délai d'expiration de la requête web. La page s'actualise pendant l'exécution.

6. Attendez l'état « installé » et la bannière de redémarrage.

   Le processus en cours d'exécution utilise encore l'ancien code jusqu'au redémarrage. La page affiche Installé … · redémarrage requis.

7. Redémarrez les services.

   Redémarrez Gunicorn ou votre serveur d'application, le worker et le beat Celery, ainsi que le processus frontend s'il s'exécute sur le même hôte. Utilisez votre gestionnaire de services, pas la page d'administration. Exemples de commandes systemd :

   exemple systemdCopier

   sudo systemctl restart fastrestful
   sudo systemctl restart fastrestful-worker fastrestful-beat
   # restart your frontend process too if it runs on this host

8. Vérifiez.

   Confirmez la version dans le centre de mises à jour, ouvrez /api/health/ready et effectuez une requête de test via la passerelle.

Partie 3 — Mettre à jour depuis la ligne de commande

Utilisez cette méthode lorsque l'administration est indisponible ou lorsque vous préférez installer depuis une session de terminal.

cd /srv/fastrestful/backend
source .venv/bin/activate

python3.11 manage.py fastrestful_update status
python3.11 manage.py fastrestful_update check
python3.11 manage.py fastrestful_update download --release-version 1.2.0
python3.11 manage.py fastrestful_update install --release-version 1.2.0

L'installation en CLI est synchrone et affiche le journal capturé de l'installateur. L'installation depuis l'administration est asynchrone. Les deux vérifient les mêmes artefacts signés avant d'exécuter l'installateur.

Maintenir le bail de licence à jour

Le bail du certificat est de 24 heures. Un battement de cœur toutes les six heures laisse une marge pour les pannes temporaires. Une vérification quotidienne suffit pour la découverte des versions.

17 */6 * * * cd /srv/fastrestful/backend && /srv/fastrestful/.venv/bin/python manage.py license_heartbeat --check-updates >> /var/log/fastrestful-license.log 2>&1

Un battement de cœur échoué enregistre l'erreur dans l'administration mais n'arrête pas la passerelle.

Partie 4 — Revenir à une version antérieure

1. Ouvrez la liste des versions.

   Les versions antérieures couvertes par votre fenêtre de mise à jour apparaissent à côté de la version actuelle.

2. Cliquez sur Installer une version antérieure pour la version cible.

   Le centre de mises à jour marque l'installation avec cette version. Il s'agit d'une installation de version normale, pas d'une réinitialisation destructive.

3. Redémarrez les services.

   Le processus redémarré reprend l'arborescence source antérieure.

4. Vérifiez la base de données.

   Si la version plus récente a appliqué une migration irréversible, restaurez la sauvegarde de la base de données antérieure à la mise à jour. Conservez ensemble la sauvegarde de la base de données et celle des sources.

Partie 5 — Canaux et environnements

Le canal est stocké sur la connexion et envoyé à chaque vérification. Modifiez-le sur la page de mise à jour ou lors de l'activation.

Partie 6 — Déploiements Docker et basés sur des images

L'installateur par défaut met à jour une copie de travail des sources. Dans un conteneur, les modifications du système de fichiers ne sont pas durables lorsque le conteneur est recréé. Choisissez plutôt l'une de ces options :

• Compilez et déployez une nouvelle image à partir de la version téléchargée dans votre pipeline habituel.
• Définissez un FASTRESTFUL_UPDATE_INSTALL_SCRIPT personnalisé qui récupère la nouvelle image ou déclenche le déploiement de votre plateforme.
• Utilisez fastrestful_update download pour récupérer et vérifier la version, puis appliquez-la en dehors du conteneur en cours d'exécution.

Partie 7 — Configuration

Partie 8 — Dépannage

Partie 9 — Notes de sécurité

• Seul le personnel disposant de licensing.change_licenseconnection peut ouvrir le centre de mises à jour.
• La protection CSRF est appliquée à chaque action.
• La clé d'achat est chiffrée au repos et n'est jamais affichée après l'activation.
• Les téléchargements utilisent des jetons LicenseHub à durée limitée. Les artefacts sont vérifiés par SHA-256 et par la signature du manifeste Ed25519 avant extraction ou exécution.
• L'extraction des archives rejette les chemins absolus, les traversées de répertoire, les liens symboliques et les liens physiques.
• Gardez le répertoire de mise à jour privé. Ne le servez pas depuis Nginx ou un stockage objet.
• Une panne de LicenseHub ou une fenêtre de mise à jour expirée ne met pas hors ligne une passerelle en cours d'exécution. La révocation bloque les téléchargements officiels ; elle n'arrête pas à distance une installation perpétuelle existante.

Pour les mainteneurs de versions

Les versions officielles sont des artefacts LicenseHub privés. Un lot peut contenir une archive source ou plusieurs artefacts (source, migrations, frontend, documentation). Tous les artefacts sont extraits dans le même répertoire bundle/, dans l'ordre renvoyé par LicenseHub.

Le lot doit inclure un installateur à l'un de ces chemins :

• install.sh
• scripts/install.sh
• scripts/install-release.sh
• le chemin dans FASTRESTFUL_UPDATE_INSTALL_SCRIPT

scripts/install-release.sh dans ce dépôt est l'implémentation de référence. Copiez-le à la racine du lot de version sous le nom install.sh. Il capture un instantané des sources et de la base de données précédentes, superpose les nouvelles sources, préserve les fichiers locaux de secrets, de médias et de base de données, installe les dépendances du backend, exécute les migrations Django et affiche l'exigence de redémarrage.

L'installateur reçoit FASTRESTFUL_RELEASE_DIR, FASTRESTFUL_BUNDLE_DIR, FASTRESTFUL_UPDATE_DIR, FASTRESTFUL_APP_ROOT, FASTRESTFUL_FROM_VERSION, FASTRESTFUL_TO_VERSION, FASTRESTFUL_PYTHON et FASTRESTFUL_INSTALL_LOG. Il s'exécute avec bash, un délai d'expiration et un journal capturé. Il doit être non interactif et laisser l'installation récupérable en cas d'échec.

Dépannage

Les échecs les plus fréquents rencontrés par les équipes — et les vérifications qui les résolvent.

L'API renvoie 401 ou 403

• 401 : jeton bearer absent ou expiré, X-API-Key manquant ou clé introuvable. Actualisez le JWT ou émettez une nouvelle clé.
• 403 : authentifié mais non autorisé. Vérifiez l'appartenance à l'espace de travail, le rôle, l'état de l'abonnement et le droit d'accès à l'endpoint.
• Les appels externes à la passerelle doivent utiliser X-API-Key (ou une clé bearer fr_live_…), et non un JWT de tableau de bord.
• Les appels au tableau de bord nécessitent à la fois Authorization: Bearer <access> et X-Organization: <uuid>.

Les requêtes du navigateur échouent en CORS ou CSRF

• Ajoutez l'origine exacte du frontend à CORS_ALLOWED_ORIGINS et CSRF_TRUSTED_ORIGINS.
• Utilisez le même schéma, hôte et port que le navigateur. localhost et 127.0.0.1 sont des origines différentes.
• Reconstruisez le frontend après avoir modifié NEXT_PUBLIC_API_URL ou NEXT_PUBLIC_SITE_URL.
• Pour les appels à la passerelle depuis des origines de consommateurs arbitraires, configurez des expressions régulières CORS ou un CORS permissif uniquement sur l'hôte de l'API produit.

La requête à la passerelle échoue

Les migrations échouent ou le schéma est en retard

python3.11 manage.py showmigrations
python3.11 manage.py makemigrations --check --dry-run
python3.11 manage.py migrate --noinput
python3.11 manage.py check

Si une migration entre en conflit avec une branche personnalisée, résolvez-le sur une copie de la base de données et ne modifiez jamais une migration déjà appliquée en production.

Les médias renvoient 404 ou un actif CDN obsolète

• Mode local : vérifiez que MEDIA_ROOT est accessible en écriture et que Nginx sert /media/.
• Mode S3 : vérifiez les autorisations du compartiment, la région, l'endpoint et l'origine CDN. Gardez le compartiment privé lorsque vous utilisez OAC.
• Après avoir remplacé un actif, purgez la distribution CDN ou utilisez l'action de purge de l'administration.
• Vérifiez que MEDIA_CDN_DOMAIN n'a pas de chemin final et correspond au certificat.

Les webhooks de paiement échouent

Commencez par la configuration propre au fournisseur dans Passerelles de paiement, étape par étape. Vérifiez ensuite les points suivants dans l'ordre :

1. L'URL est exacte et publique. Enregistrez /api/v1/billing/stripe-webhook/, /paypal-webhook/, /flutterwave-webhook/, /paystack-webhook/ ou /razorpay-webhook/ sur le même nom d'hôte que celui utilisé par les utilisateurs. Localhost ne fonctionnera pas.
2. Les valeurs de test et de production ne sont pas mélangées. Une clé de test avec un ID de webhook de production (ou l'inverse) fait échouer chaque livraison.
3. Le secret est du bon type. Stripe nécessite le secret de signature de l'endpoint (whsec_…), et non la clé secrète de l'API. Flutterwave nécessite le hash secret que vous avez créé. Razorpay nécessite le secret de signature du webhook.
4. PayPal utilise un ID de webhook, pas un secret. Placez l'ID de la même application PayPal et du même environnement dans PAYPAL_WEBHOOK_ID. FastRestful vérifie chaque événement avec l'API de vérification de signature de PayPal. Un ID absent ou incorrect renvoie Bad signature. Consultez Dépannage des webhooks PayPal.
5. Paystack n'a généralement pas besoin de secret de webhook. Laissez PAYSTACK_WEBHOOK_SECRET vide ; FastRestful vérifie avec PAYSTACK_SECRET_KEY.
6. Les types d'événements sont sélectionnés. Un webhook joignable mais non abonné à l'événement de règlement laisse la facture ouverte.
7. Votre proxy préserve les en-têtes du fournisseur. Nginx, Cloudflare et les équilibreurs de charge doivent transmettre les en-têtes de signature sans modification.
8. Le montant et la devise correspondent. FastRestful rejette un règlement qui ne correspond pas à la facture.
9. Vérifiez le reçu. Ouvrez Admin → Événements de paiement ; les ID d'événements en double sont acquittés sans double règlement. Renvoyez l'événement en échec depuis le tableau de bord du fournisseur.

Les e-mails ne sont pas envoyés

• Le développement utilise le backend e-mail de console. Vérifiez la sortie du terminal.
• La production utilise SMTP par défaut. Testez l'hôte, le port, TLS, le nom d'utilisateur et le mot de passe.
• Les paramètres de newsletter peuvent remplacer l'expéditeur défini dans l'environnement ; confirmez le fournisseur actif dans le studio.
• Vérifiez SPF, DKIM et DMARC avant d'incriminer la file d'attente. Les taux de rebond et de plainte suppriment les envois futurs.

Problèmes de compilation ou de routage du frontend

• Exécutez npm run typecheck et npm test avant de déboguer le déploiement.
• Une page vide pilotée par l'API signifie généralement que l'origine de l'API est inaccessible ou que CORS est incomplet.
• Si les pages produit publiques fonctionnent mais que /api/{slug} renvoie 404, vérifiez que le proxy ne transmet que les espaces de noms Django et non la route produit gérée par le frontend.
• Après des modifications i18n, exécutez npm run export:i18n et redémarrez Django.

Les modifications de locale ne s'affichent pas

• Le français intégré est chargé depuis le bundle frontend ; les surcharges d'administration proviennent de l'API de locale active.
• Enregistrez la surcharge d'administration, confirmez que la locale est active et forcez l'actualisation du navigateur.
• Après avoir modifié fr.json, exportez la source backend et redémarrez l'API pour vider son cache de processus.
• Vérifiez la présence d'une préférence de locale obsolète dans localStorage.

Authentification & accès

FastRestful utilise des jetons d'accès JWT à durée limitée, des jetons de rafraîchissement rotatifs et une session navigateur Django partagée. La même connexion peut ouvrir la console consommateur, le studio fournisseur et l'administration du personnel.

Flux d'authentification

En-têtes de requête

Authorization: Bearer <access-token>
X-Organization: <organization-uuid>
Content-Type: application/json

X-API-Key: fr_live_…
# backwards-compatible alternative:
Authorization: Bearer fr_live_…

Le tableau de bord utilise un JWT ainsi que l'en-tête explicite de l'espace de travail actif. Les consommateurs externes utilisent une clé d'API produit à laquelle ils sont abonnés. Un JWT de tableau de bord ne doit pas être utilisé comme clé d'API client, et une clé d'API brute ne doit pas être envoyée aux endpoints du tableau de bord.

Rôles d'espace de travail

L'accès du personnel de plateforme est distinct : il nécessite is_staff et ne découle jamais d'un rôle admin d'espace de travail. Les autorisations du personnel sont appliquées par modèle Django et par action d'administration.

Authentification à deux facteurs

• Enrôlement d'un authentificateur TOTP avec QR code ou URI de provisionnement et codes de récupération à usage unique.
• Les codes de récupération sont affichés une seule fois, hachés au repos et régénérés par ensemble.
• Un superutilisateur peut exiger la double authentification pour chaque compte dans les paramètres du site.
• L'accès à l'administration peut être bloqué jusqu'à confirmation de l'enrôlement ; la console affiche un écran de configuration dédié.

Invitations d'espace de travail

Les propriétaires et les administrateurs invitent par e-mail et attribuent un rôle. Les jetons d'invitation sont hachés, à usage unique, liés à l'adresse e-mail, expirent après sept jours et peuvent être renvoyés ou révoqués. L'acceptation d'une invitation nécessite un utilisateur authentifié dont l'adresse e-mail correspond et peut réactiver une adhésion inactive.

GET  /api/v1/organization-invites/
POST /api/v1/organization-invites/          {"email": "...", "role": "developer"}
POST /api/v1/organization-invites/{id}/resend/
POST /api/v1/organization-invites/{id}/revoke/
POST /api/v1/auth/invites/accept/           {"token": "..."}

Configuration SSO

OIDC

SSO_ISSUER=https://login.example.com/realms/acme
SSO_CLIENT_ID=fastrestful
SSO_CLIENT_SECRET=...
FRONTEND_URL=https://app.example.com

Enregistrez l'URL de rappel https://api.example.com/api/v1/auth/sso/callback/ auprès du fournisseur d'identité. Les destinations relatives sûres et les jetons d'invitation sont conservés lors de l'aller-retour.

SAML 2.0

SSO_SAML_ENABLED=1
SSO_SAML_ENTITY_ID=fastrestful
SSO_SAML_SSO_URL=https://idp.example.com/sso
SSO_SAML_IDP_CERT="-----BEGIN CERTIFICATE-----..."
SSO_SAML_AUDIENCE=fastrestful

Installez lxml avant d'activer SAML. Les métadonnées sont servies à l'adresse /api/v1/auth/saml/metadata/ ; configurez l'IdP avec l'URL du service consommateur d'assertion issue de l'endpoint de démarrage.

Cycle de vie des clés d'API

• Créez une clé dans l'application sélectionnée ; la clé brute n'apparaît qu'une fois.
• Envoyez-la en tant que X-API-Key ou en tant qu'identifiant bearer fr_live_….
• Effectuez une rotation pour révoquer l'ancienne clé et en émettre une nouvelle de manière atomique.
• Révoquez immédiatement en cas de perte d'un identifiant ; la valeur brute ne peut pas être récupérée.
• Utilisez la portée execute ou read pour appliquer le moindre privilège lorsque le client n'a pas besoin d'une gestion complète.

Produits API & versions

Un produit est l'identité publique. Une version est le contrat immuable. Les endpoints, la documentation, la politique de passerelle et les droits des forfaits sont tous liés à ce périmètre de version.

Le modèle de produit

Créer et publier un produit

1. Dans le studio fournisseur, créez le produit avec son nom, son slug, sa catégorie, son accroche, son README et l'URL amont.
2. Créez une version brouillon et importez un contrat OpenAPI 3.x ou Swagger 2.0.
3. Examinez le catalogue d'endpoints réconcilié et la documentation des endpoints.
4. Créez au moins un forfait public et configurez les quotas, les limites de débit et les droits d'accès.
5. Exécutez le contrôle de préparation à la publication ; les quatre vérifications doivent réussir.
6. Soumettez la version pour révision, puis promouvez-la en production.
7. Publiez le produit. La version en production précédente est automatiquement retirée.

Import OpenAPI

curl --request POST \
  --url 'https://api.example.com/api/v1/products/signal-stack/import-spec/' \
  --header 'Authorization: Bearer <access>' \
  --header 'X-Organization: <vendor-org-uuid>' \
  --header 'Content-Type: application/json' \
  --data '{
    "version": "2.5.0",
    "openapi": { "openapi": "3.0.3", "paths": { } },
    "changelog": "Add delivery scheduling."
  }'

L'import crée ou met à jour une version brouillon, réconcilie les lignes d'endpoints à partir de paths, indique les endpoints créés, mis à jour et supprimés, et préserve les champs de politique de passerelle sur les opérations conservées. L'import dans une version en production est rejeté.

Préparation à la publication

Machine à états des versions

draft ──submit_review──► review ──promote──► live ──deprecate──► deprecated
  └───────────────────────promote────────────────┘

# product visibility
draft ──publish──► public ──unpublish──► draft
                       └──retire──► retired ──restore──► draft

• Les versions en production sont immuables : les modifications sont rejetées au niveau du modèle et du sérialiseur.
• La promotion retire la version en production précédente afin de maintenir l'invariant d'une seule version en production.
• Le contrat et le catalogue d'endpoints doivent correspondre exactement avant la promotion.
• Les droits d'accès aux endpoints des forfaits sont remappés par méthode et chemin lorsqu'une nouvelle version en production remplace l'ancienne.

Rapports de changements incompatibles

GET /api/v1/versions/{version_id}/diff/?against={previous_version_id}

# Review added, removed, and changed operations before promotion.
# A release can be promoted only after the contract is validated.

Routage des hôtes produit

Chaque produit publié dispose de deux points d'entrée équivalents :

Le middleware lit le premier libellé de l'hôte comme slug du produit. Les alias de chemin sont enregistrés comme route finale, de sorte que les routes API nommées ont toujours la priorité. Les produits inconnus renvoient 404 avec une indication ; les requêtes sans clé vers des produits inconnus renvoient 401 pour éviter l'énumération.

Droits des forfaits

• all accorde l'accès à chaque endpoint public de la version en production.
• selected accorde uniquement l'ensemble d'endpoints configuré.
• Les droits sélectionnés sont appliqués au niveau de la passerelle, y compris pour les requêtes en chemin brut qui contournent le catalogue d'endpoints.
• Les conditions commerciales se verrouillent après le premier abonnement ; créez un forfait de remplacement au lieu de modifier un forfait déjà souscrit.

Passerelle & comptage

La passerelle est le seul chemin vers les amonts des fournisseurs. Elle résout le produit, authentifie la clé, applique la politique d'abonnement et de forfait, réserve le quota, transmet en toute sécurité, compte l'utilisation et écrit une trace expurgée.

Pipeline de requêtes

1. Résolvez le produit à partir de l'hôte ou de l'alias de chemin et trouvez l'endpoint de la version en production par méthode et chemin.
2. Authentifiez avec un JWT ou une session de tableau de bord, ou avec un identifiant externe X-API-Key / bearer fr_live_….
3. Résolvez l'abonnement pour le produit et l'application. Seuls les abonnements actifs et en période d'essai sont acceptés.
4. Validez la liaison de la clé et enregistrez last_used_at. Une clé ne peut pas franchir les applications ni les espaces de travail.
5. Réservez le quota sur le compteur mensuel et appliquez les limites de débit par endpoint de manière atomique.
6. Exécutez les contrôles de sécurité réseau : HTTPS, DNS public, aucune redirection, aucune traversée, IP épinglée.
7. Transmettez avec délai d'expiration, limites de corps et de téléversement, et nouvelles tentatives bornées.
8. Comptez : événement d'utilisation, compteur mensuel, journal de requêtes expurgé et aperçu de la réponse.

Appels directs au produit

curl --request POST \
  --url 'https://signal-stack.api.example.com/v2/deliveries' \
  --header 'X-API-Key: fr_live_…' \
  --header 'Content-Type: application/json' \
  --data '{"recipient":"[email protected]","template":"welcome"}'

curl --request GET \
  --url 'https://api.example.com/api/v1/signal-stack/v2/deliveries?limit=10' \
  --header 'X-API-Key: fr_live_…'

L'enveloppe héritée POST /api/v1/gateway/execute/ reste disponible pour les intégrations existantes et les outils de la console. Les nouveaux extraits utilisent la forme directe.

En-têtes de la passerelle

Quotas et limites de débit

• Le quota mensuel est réservé avant la transmission et compte les requêtes routées, y compris les échecs en amont.
• Le quota illimité supprime uniquement le plafond mensuel ; la limite par minute et le droit d'accès aux endpoints s'appliquent toujours.
• La limite de débit par endpoint utilise une fenêtre fixe atomique en cache. Une panne du cache partagé renvoie un 503 réessayable avant la réservation du quota.
• Le dépassement est facturé par 1 000 requêtes lorsqu'il est configuré ; zéro signifie alerte uniquement.

Idempotence et nouvelles tentatives

• Les réponses terminées sont stockées avec un hachage de jeton SHA-256, une empreinte de requête et une réponse expurgée pendant la durée de vie configurée.
• Les relectures renvoient la réponse stockée avant toute réservation de quota ou tout appel en amont.
• La réutilisation d'une clé avec une entrée de requête différente renvoie 409.
• Les nouvelles tentatives sont bornées et ne s'appliquent qu'aux échecs transitoires sûrs ; les méthodes non idempotentes ne sont pas réessayées aveuglément.
• Un disjoncteur s'ouvre après des échecs répétés en amont et renvoie un 503 réessayable pendant la période de refroidissement.

SSRF et sécurité réseau

• Les amonts doivent être en HTTPS public. Les réponses DNS privées, de bouclage, de liaison locale et non sûres sont rejetées.
• Le chemin doit rester sur l'hôte d'origine. La traversée par .. est rejetée.
• Les redirections ne sont pas suivies.
• L'adresse DNS publique sélectionnée est épinglée pendant la connexion TLS afin de prévenir le rebinding.
• Les secrets des fournisseurs sont ajoutés côté serveur et ne sont jamais renvoyés au navigateur.
• Les aperçus de réponse sont limités et masquent les en-têtes de cookie, d'autorisation et de clé d'API.

Journaux de requêtes et comptage

• Vue consommateur : historique des requêtes de l'espace de travail actif avec recherche, filtres de statut et export CSV.
• Vue fournisseur : journaux au niveau des requêtes pour tous les produits détenus, avec consommateur, endpoint, latence, statut et aperçus expurgés.
• Événements d'utilisation : code de statut, latence, abonnement, produit, endpoint et horodatage.
• Compteurs mensuels : modèle de lecture des quotas et des analyses.
• La conservation est configurable avec prune_telemetry.

Environnement de la passerelle

Tous les délais d'expiration, plafonds, budgets de nouvelles tentatives, seuils de disjoncteur, durées de vie d'idempotence, CIDR de proxy de confiance, limites d'aperçu des médias et le suffixe d'hôte produit sont pilotés par l'environnement. Consultez Configuration pour le tableau complet.

Facturation & versements

La facturation a deux rôles : permettre aux consommateurs de payer les forfaits API et permettre à l'opérateur de la plateforme de facturer la capacité des espaces de travail. Les deux utilisent les mêmes fournisseurs, factures et règlements par webhook.

Les deux plans de facturation

Voyez-le comme deux caisses distinctes :

Les deux utilisent un paiement hébergé, des webhooks signés, des factures et une réconciliation. Les revenus des API des fournisseurs alimentent le règlement des versements ; les revenus des abonnements de plateforme, non.

Forfaits fournisseur

• Intervalle mensuel ou annuel, devise, prix et description.
• Quota mensuel, limite de débit par minute, dépassement par 1 000 requêtes, jours d'essai.
• Jusqu'à huit lignes de fonctionnalités publiques et un forfait public recommandé.
• Droit d'accès aux endpoints all ou selected.
• Les conditions commerciales se verrouillent après le premier abonnement ; utilisez un forfait de remplacement pour les modifications.

Paiement et règlement

1. Le consommateur sélectionne un forfait et accepte les conditions de l'API.
2. Un abonnement en attente et une facture pour la première période sont créés.
3. Le fournisseur configuré ouvre le paiement hébergé.
4. Le fournisseur envoie un webhook signé après le paiement.
5. FastRestful vérifie la signature, enregistre l'événement du fournisseur, valide le montant et la devise, puis marque la facture comme payée.
6. Le droit d'accès n'est activé qu'après le règlement. Les redirections du navigateur n'accordent jamais l'accès.

POST /api/v1/billing/stripe-webhook/
POST /api/v1/billing/paypal-webhook/
POST /api/v1/billing/flutterwave-webhook/
POST /api/v1/billing/paystack-webhook/
POST /api/v1/billing/razorpay-webhook/

Prise en charge des fournisseurs

Chaque fournisseur ci-dessous dispose d'un guide de configuration étape par étape dans Passerelles de paiement, étape par étape.

Admin → Passerelles de paiement remplace les identifiants d'environnement champ par champ. La désactivation d'un enregistrement de passerelle désactive ce fournisseur partout, même si les clés d'environnement subsistent.

Remboursements

• Les fournisseurs disposant de l'autorisation de facturation remboursent les factures payées via la passerelle d'origine.
• Les remboursements Stripe se réconcilient de manière cumulative à partir des événements de webhook ; les passerelles hébergées confirment de manière synchrone.
• Les clés d'idempotence et les demandes de remboursement en attente rendent les nouvelles tentatives sûres.
• Les remboursements intégraux marquent la facture comme remboursée.
• Les remboursements après versement ajoutent des écritures de récupération des revenus du fournisseur et d'annulation proportionnelle des frais au grand livre.
• Les consommateurs ne peuvent pas se rembourser eux-mêmes ; les paiements manuels doivent être remboursés via leur fournisseur.

Versements

pending ──► in_transit ──► paid
   │              │
   ├──► failed ◄──┘
   └──► reversed

# Only paid invoices settle. Refunds reduce the next transfer.
# Gross collected revenue is stored separately from net transfer.
# Provider event IDs are unique and retries are idempotent.

• Configurez une destination de versement avec PATCH /api/v1/orgs/{id}/payout-provider/ (acct_… pour Stripe ou une adresse e-mail pour PayPal).
• Lancez un transfert avec POST /api/v1/payouts/{id}/transfer/.
• Réconciliez avec POST /api/v1/payouts/{id}/reconcile/ ; les états stricts exigent un ID de transfert ou un motif d'échec.
• Les webhooks Stripe réconcilient transfer.created|paid|failed|reversed.

Abonnements à la plateforme

• Les forfaits de plateforme sont gérés dans Admin → Forfaits de plateforme ; cinq forfaits au maximum.
• Chaque forfait peut définir des limites d'espaces de travail détenus et de publication d'API, des avantages et une recommandation.
• Les forfaits payants restent non publiés jusqu'à ce qu'un montant d'affichage et un ID de prix récurrent correspondant chez le fournisseur soient configurés.
• Les sessions de paiement et du portail de facturation sont créées côté serveur avec des destinations FRONTEND_URL fixes.
• La réconciliation des abonnements est en lecture seule dans l'administration afin que les modifications du personnel ne divergent pas du fournisseur.

Commandes de règlement

python3.11 manage.py generate_invoices --period 2026-10
python3.11 manage.py generate_payouts --period 2026-10

# Both commands are idempotent and safe to rerun.

La tâche Celery mensuelle s'exécute le 1er à 00:05 UTC. Sans broker, invoquez les commandes manuellement.

Environnement du fournisseur

Consultez Configuration → Paiements et versements pour chaque variable. Au minimum : secret et webhook Stripe, client et webhook PayPal, ou le trio clé publique, secret et webhook de la passerelle hébergée. L'interface de carte du frontend nécessite aussi NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY.

Passerelles de paiement, étape par étape

Connectez un véritable fournisseur de paiement sans hésitation. Chaque section de fournisseur comporte deux parties : les actions à effectuer dans le tableau de bord du fournisseur, puis les informations à saisir dans FastRestful. PayPal inclut un parcours complet de configuration des webhooks, notamment l'emplacement de l'ID de webhook requis par FastRestful.

Avant de commencer

Comment l'argent circule dans FastRestful

1. FastRestful crée une facture.

   L'abonnement et la facture de la première période existent avant l'ouverture du paiement. Rien n'est encore marqué comme payé.

2. Pour les forfaits payants, le fournisseur ouvre le paiement.

   Le client paie sur la page hébergée du fournisseur. FastRestful ne stocke que la référence de paiement.

3. Le fournisseur envoie un webhook signé.

   FastRestful vérifie la signature, enregistre l'événement une seule fois et contrôle le montant et la devise.

4. La facture est réglée.

   C'est seulement maintenant que l'abonnement s'active et que le droit d'accès commence. Une redirection du navigateur n'accorde jamais l'accès.

Où placer les identifiants

Vous pouvez placer les identifiants dans backend/.env ou dans Admin → Passerelles de paiement. Les enregistrements d'administration sont plus faciles à faire tourner et remplacent les valeurs d'environnement champ par champ. La désactivation d'un enregistrement d'administration désactive le fournisseur partout, même si les clés d'environnement existent encore.

Tester les webhooks sur votre ordinateur portable

Les fournisseurs ne peuvent pas joindre http://127.0.0.1:5056. Utilisez l'une de ces approches pour les tests locaux.

Stripe CLI

1. Installez et connectez-vous à la Stripe CLI.

   Suivez le guide d'installation de la CLI Stripe, puis exécutez stripe login et approuvez l'invite du navigateur.

2. Transférez les événements vers votre backend local.
   shellCopier

   stripe listen --forward-to localhost:5056/api/v1/billing/stripe-webhook/

3. Copiez le secret de signature affiché.

   La CLI affiche whsec_…. Placez-le dans STRIPE_WEBHOOK_SECRET ou dans l'enregistrement d'administration Stripe. Laissez la CLI en cours d'exécution.

4. Déclenchez un événement de test.
   shellCopier

   stripe trigger checkout.session.completed
   stripe trigger invoice.paid

PayPal, Flutterwave, Paystack et Razorpay

Ces fournisseurs nécessitent une URL HTTPS publique. Utilisez un tunnel tel que ngrok ou Cloudflare Tunnel, puis enregistrez l'URL du tunnel dans le tableau de bord du fournisseur :

# Example with ngrok
ngrok http 5056

# Use the generated https URL, for example:
# https://abc123.ngrok-free.app/api/v1/billing/paypal-webhook/

Vous changez l'URL du tunnel plus tard ? Mettez à jour ensemble le tableau de bord du fournisseur et la destination du webhook FastRestful. Une URL obsolète est la cause la plus fréquente du message « paiement réussi mais facture jamais clôturée ».

PayPal propose également un simulateur de webhooks dans le tableau de bord développeur. Pointez-le vers l'URL du tunnel et utilisez l'ID de webhook de la même application sandbox afin que FastRestful puisse vérifier l'événement simulé.

Choisir un fournisseur

Stripe, étape par étape

1. Créer et activer un compte Stripe

1. Créez un compte Stripe et complétez le profil de l'entreprise.
2. Gardez le mode Test activé pendant l'intégration. Le bouton bascule se trouve dans la barre supérieure du tableau de bord Stripe.
3. Vous pouvez accepter des paiements de test avant que Stripe ne termine l'activation du compte.

2. Copier les clés d'API

1. Ouvrez Developers → API keys.

   Dans le tableau de bord Stripe, ouvrez Developers, puis API keys.

2. Copiez la clé secrète.

   Utilisez d'abord la clé secrète de test (sk_test_…). Placez-la dans STRIPE_SECRET_KEY ou dans la fiche d'administration Stripe. Ne placez jamais la clé secrète dans le code frontend.

3. Copiez la clé publique.

   Placez la clé publique de test (pk_test_…) dans NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY si vous souhaitez l'interface de carte intégrée. Recompilez le frontend après l'avoir modifiée.

3. Ajoutez l'endpoint webhook Stripe

1. Ouvrez Developers → Webhooks → Add endpoint.
2. Définissez l'URL de l'endpoint.
   URL de production ou de préproductionCopier

   https://api.example.com/api/v1/billing/stripe-webhook/

3. Sélectionnez les événements que FastRestful rapproche.
   • checkout.session.completed
   • invoice.paid et invoice.payment_succeeded
   • invoice.payment_failed
   • customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
   • charge.refunded
   • transfer.created, transfer.paid, transfer.failed, transfer.reversed (versements)
4. Copiez le secret de signature.

   Stripe affiche une valeur commençant par whsec_…. Il s'agit de STRIPE_WEBHOOK_SECRET. Ce n'est pas la clé secrète de l'API.

Stripe signe chaque livraison. FastRestful rejette les signatures périmées et refuse la livraison lorsque STRIPE_WEBHOOK_SECRET est absent ; un secret de signature correct est donc obligatoire.

4. Ajoutez Stripe dans FastRestful

Ouvrez Admin → Passerelles de paiement et modifiez la ligne Stripe (recommandé), ou utilisez les variables d'environnement.

Si vous utilisez plutôt les variables d'environnement, définissez STRIPE_SECRET_KEY et STRIPE_WEBHOOK_SECRET, puis redémarrez le backend et les workers.

5. Offres de plateforme et tarifs Stripe

Nécessaire uniquement si vous vendez des abonnements de plateforme. Les offres API des fournisseurs utilisent le prix propre au produit et n'ont pas besoin d'un tarif Stripe.

1. Créez un produit dans Stripe.

   Ouvrez Product catalog → Add product. Donnez-lui le nom de votre offre de plateforme.

2. Ajoutez un tarif récurrent.

   Utilisez exactement le montant, la devise et l'intervalle de facturation affichés par votre offre de plateforme. Les tarifs mensuels et annuels doivent être des tarifs distincts.

3. Copiez chaque ID de tarif.

   Les ID de tarif commencent par price_….

4. Collez-les dans l'offre de plateforme.

   Ouvrez Admin → Offres de plateforme et renseignez ID du tarif mensuel Stripe et ID du tarif annuel Stripe.

FastRestful vérifie le tarif par rapport au montant, à la devise et à l'intervalle de l'offre au moment du paiement. Une incohérence renvoie 409 avec une explication au lieu de débiter un montant erroné.

6. Stripe Connect pour les versements aux fournisseurs

1. Activez Connect dans Stripe et créez un compte connecté pour chaque fournisseur que vous payez.
2. Copiez l'ID du compte connecté (acct_…).
3. Stockez-le comme destination du fournisseur avec PATCH /api/v1/orgs/{id}/payout-provider/ ou depuis les paramètres de versement du fournisseur.
4. Définissez éventuellement PAYOUT_PROVIDER=stripe pour n'autoriser que les versements Stripe.
5. Laissez les événements transfer.* sélectionnés sur le webhook Stripe.

7. Testez Stripe

1. Utilisez la carte de test 4242 4242 4242 4242, une date d'expiration future et n'importe quel CVC.
2. Effectuez un paiement et confirmez que la facture passe à payée.
3. Confirmez que l'abonnement devient actif et que la clé consommateur fonctionne.
4. Ouvrez Admin → Événements de paiement et confirmez que l'événement n'a été traité qu'une fois.
5. Déclenchez un remboursement et confirmez que l'état de remboursement de la facture est correct.

PayPal, étape par étape

PayPal est le fournisseur qui compte le plus d'étapes côté plateforme. FastRestful utilise deux produits PayPal différents : Checkout orders pour les achats d'offres API par les fournisseurs et Billing subscriptions pour les offres de plateforme. Les deux utilisent les mêmes identifiants d'application et le même webhook.

1. Créez une application PayPal et copiez les identifiants

1. Ouvrez le tableau de bord développeur PayPal.

   Rendez-vous sur developer.paypal.com et connectez-vous avec votre compte professionnel PayPal.

2. Choisissez Sandbox ou Live.

   Utilisez le commutateur Sandbox/Live en haut. Sandbox et Live disposent d'applications, d'identifiants et d'ID de webhook distincts.

3. Ouvrez Apps & Credentials → Create App.

   Donnez-lui un nom tel que FastRestful et sélectionnez le compte professionnel qui doit recevoir les paiements.

4. Copiez le Client ID et le Secret.

   Ils vont dans PAYPAL_CLIENT_ID et PAYPAL_CLIENT_SECRET (ou dans la fiche d'administration PayPal). Si le secret est masqué, utilisez l'action de régénération de l'application et copiez la nouvelle valeur.

2. Ajoutez le webhook PayPal (obligatoire)

C'est l'étape que la plupart des gens oublient. Sans ID de webhook, FastRestful rejette tous les événements PayPal et les commandes payées restent impayées.

1. Ouvrez votre application dans Apps & Credentials.
2. Faites défiler jusqu'à Webhooks et cliquez sur Add Webhook.

   Le libellé exact peut être Webhooks ou Add Webhook selon la version du tableau de bord PayPal.

3. Saisissez l'URL du webhook.
   URL du webhook PayPalCopier

   https://api.example.com/api/v1/billing/paypal-webhook/

   L'URL doit être en HTTPS public. Une redirection de navigateur ne prouve pas le paiement ; PayPal envoie des événements signés à cette URL, et ces événements règlent la facture.

4. Sélectionnez les types d'événements.

   Groupe d'événements	Sélection	Pourquoi FastRestful en a besoin
   Commandes Checkout	CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED	Capture et règle les paiements des offres API des fournisseurs.
   Abonnements	BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED	Active et met à jour les abonnements de plateforme. ACTIVATED est l'événement qui accorde le droit d'accès.
   Paiements d'abonnement	PAYMENT.SALE.COMPLETED	Enregistre les renouvellements et réactive les abonnements de plateforme en retard.
   Versements	PAYMENT.PAYOUTS-ITEM.SUCCEEDED, PAYMENT.PAYOUTS-ITEM.FAILED, PAYMENT.PAYOUTS-ITEM.BLOCKED, PAYMENT.PAYOUTS-ITEM.RETURNED, PAYMENT.PAYOUTS-ITEM.CANCELED	Rapproche les transferts de versement aux fournisseurs.

5. Enregistrez le webhook et copiez l'ID du webhook.

   Ouvrez le webhook enregistré si nécessaire. PayPal affiche un ID de webhook (une courte chaîne alphanumérique). Il s'agit de PAYPAL_WEBHOOK_ID. Ce n'est pas l'URL du webhook et pas le secret client.

3. Ajoutez PayPal dans FastRestful

Ouvrez Admin → Passerelles de paiement et modifiez la ligne PayPal. Dans ce formulaire, Clé publique correspond au Client ID, Clé secrète au secret client et Secret du webhook à l'ID du webhook.

Si vous préférez les variables d'environnement :

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_WEBHOOK_ID=...
PAYPAL_ENV=sandbox          # use live in production
# PAYPAL_API_BASE=          # only for a proxy or custom host

Redémarrez le backend et les workers après avoir modifié les valeurs d'environnement. Si vous utilisez la fiche d'administration, enregistrez-la et activez-la ; aucun redémarrage n'est nécessaire.

4. Offres de facturation PayPal pour les abonnements de plateforme

Ignorez cette section, sauf si vous vendez des abonnements de plateforme via PayPal. Les offres API des fournisseurs utilisent des commandes Checkout ponctuelles et n'ont pas besoin d'une offre de facturation PayPal.

1. Créez un produit dans PayPal.

   Dans le tableau de bord PayPal, ouvrez la section Billing/Subscriptions et créez un produit qui représente votre plateforme.

2. Créez une offre mensuelle et/ou annuelle.

   Définissez exactement le montant, la devise et l'intervalle qui correspondent à l'offre dans FastRestful. Créez une offre distincte pour chaque intervalle.

3. Copiez chaque ID d'offre.

   Les ID d'offre PayPal commencent par P-….

4. Collez-les dans l'offre de plateforme.

   Ouvrez Admin → Offres de plateforme et renseignez ID de l'offre mensuelle PayPal et ID de l'offre annuelle PayPal.

5. Confirmez que le webhook inclut les événements d'abonnement.

   L'abonnement est créé à l'état PENDING. Il ne devient actif qu'après l'arrivée de BILLING.SUBSCRIPTION.ACTIVATED.

5. PayPal Payouts pour les fournisseurs

1. Confirmez que le compte professionnel PayPal est approuvé pour Payouts.
2. Stockez l'adresse e-mail de réception PayPal du fournisseur comme destination de versement avec PATCH /api/v1/orgs/{id}/payout-provider/.
3. Définissez éventuellement PAYOUT_PROVIDER=paypal, ou PAYOUT_PROVIDER=stripe,paypal pour autoriser les deux.
4. Laissez les événements PAYMENT.PAYOUTS-ITEM.* sélectionnés sur le webhook.

6. Testez le bac à sable PayPal

1. Utilisez les identifiants du bac à sable.

   Définissez PAYPAL_ENV=sandbox, utilisez le Client ID et le secret de l'application du bac à sable, ainsi que l'ID de webhook du bac à sable.

2. Créez un compte acheteur de test.

   Le tableau de bord développeur PayPal fournit des comptes personnels de test. Connectez-vous à sandbox.paypal.com avec cet acheteur lorsque le paiement s'ouvre.

3. Effectuez un paiement de test.

   Approuvez la commande et attendez la redirection vers FastRestful.

4. Vérifiez la réception du webhook.

   Ouvrez Admin → Événements de paiement. Vous devriez voir CHECKOUT.ORDER.APPROVED, puis PAYMENT.CAPTURE.COMPLETED, et la facture devrait devenir payée.

5. Renvoyez une livraison si nécessaire.

   Dans le tableau de bord PayPal, ouvrez les livraisons d'événements du webhook et renvoyez l'événement en échec. FastRestful déduplique par ID d'événement.

Dépannage des webhooks PayPal

Flutterwave, étape par étape

1. Créez et vérifiez un compte Flutterwave.

   Complétez le profil professionnel et le KYC avant d'utiliser le mode Live.

2. Copiez les clés API.

   Ouvrez Settings → API Keys. Copiez la clé publique et la clé secrète. Les clés de test et de production sont distinctes.

3. Ajoutez l'URL du webhook.

   Ouvrez Settings → Webhooks et définissez :

   URL du webhook FlutterwaveCopier

   https://api.example.com/api/v1/billing/flutterwave-webhook/

4. Créez un hash secret.

   Saisissez une longue chaîne aléatoire comme hash secret du webhook. Placez la même valeur dans FLUTTERWAVE_WEBHOOK_SECRET ou dans la fiche d'administration. Il s'agit d'une valeur que vous choisissez, et non d'une clé générée par Flutterwave.

5. Saisissez les clés dans FastRestful.

   Modifiez la ligne Flutterwave dans Admin → Passerelles de paiement, ou définissez FLUTTERWAVE_PUBLIC_KEY, FLUTTERWAVE_SECRET_KEY et FLUTTERWAVE_WEBHOOK_SECRET.

6. Testez un paiement.

   FastRestful traite charge.completed avec le statut successful. Les autres événements sont accusés réception et ignorés.

Paystack, étape par étape

1. Créez et activez un compte Paystack.

   Complétez les étapes d'activation professionnelle avant d'utiliser les clés Live.

2. Copiez les clés API.

   Ouvrez Settings → API Keys & Webhooks. Copiez les clés publique et secrète pour le mode test ou Live.

3. Ajoutez l'URL du webhook.
   URL du webhook PaystackCopier

   https://api.example.com/api/v1/billing/paystack-webhook/

4. Laissez le secret du webhook vide.

   Paystack signe chaque webhook avec votre clé secrète via HMAC-SHA512. FastRestful revient à PAYSTACK_SECRET_KEY lorsque PAYSTACK_WEBHOOK_SECRET est vide. Ne définissez une valeur de remplacement que si l'assistance Paystack vous fournit une clé de signature distincte.

5. Saisissez les clés dans FastRestful.

   Modifiez la ligne Paystack dans Admin → Passerelles de paiement, ou définissez PAYSTACK_PUBLIC_KEY et PAYSTACK_SECRET_KEY.

6. Testez un paiement.

   FastRestful traite charge.success et compare le montant dans la plus petite unité monétaire (par exemple le kobo pour le NGN).

Razorpay, étape par étape

1. Créez et vérifiez un compte Razorpay.

   Complétez le KYC et activez les paiements Live.

2. Générez des clés API.

   Ouvrez Account & Settings → API Keys et générez une clé. Copiez le Key ID et le Key Secret.

3. Ajoutez le webhook.

   Ouvrez Account & Settings → Webhooks → Add New Webhook et définissez :

   URL du webhook RazorpayCopier

   https://api.example.com/api/v1/billing/razorpay-webhook/

   Sélectionnez payment_link.paid. FastRestful crée un Payment Link Razorpay pour le paiement et rapproche cet événement. Définissez un secret de webhook robuste ; Razorpay signe via HMAC-SHA256, et la même valeur doit être stockée dans FastRestful.

4. Saisissez les clés dans FastRestful.

   Modifiez la ligne Razorpay dans Admin → Passerelles de paiement, ou définissez RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET et RAZORPAY_WEBHOOK_SECRET.

5. Testez un paiement.

   Ouvrez le Payment Link, payez avec un moyen de test et confirmez que la facture est payée et que l'événement n'est enregistré qu'une fois.

Le test d'acceptation en 10 minutes

Exécutez ce test pour chaque fournisseur avant la mise en production :

• Le fournisseur apparaît comme configuré et activé dans Admin → Passerelles de paiement.
• Un paiement de test ouvre la page du fournisseur et revient à l'URL frontend correcte.
• Le webhook signé arrive et apparaît une seule fois dans Admin → Événements de paiement.
• La facture ne devient payée qu'après le webhook, et non à la redirection.
• L'abonnement devient actif et une clé consommateur fonctionne.
• Un remboursement revient au moyen de paiement d'origine et met à jour le grand livre.
• Si les versements sont activés, un transfert de test atteint la destination du fournisseur et est rapproché.
• Une livraison de webhook en double est accusée réception sans double règlement.

Erreurs courantes avec les webhooks

Liste de contrôle de mise en production

1. Passez aux identifiants de production.

   Remplacez les clés de test, les ID de webhook et les secrets par les valeurs de production. Définissez PAYPAL_ENV=live pour PayPal.

2. Enregistrez les URL de webhook de production.

   Utilisez votre vrai nom d'hôte API, pas un tunnel, et confirmez que HTTPS fonctionne depuis l'internet public.

3. Définissez la clé publique du frontend.

   Utilisez la clé publique Stripe de production et recompilez le frontend.

4. Faites correspondre les tarifs et les ID d'offre.

   Confirmez que les ID de tarif Stripe et les ID d'offre de facturation PayPal pointent vers des objets de production avec exactement le montant, la devise et l'intervalle.

5. Effectuez un petit paiement réel et remboursez-le.

   Vérifiez le webhook, la facture, le droit d'accès, le remboursement et les écritures au grand livre. C'est le seul moyen de valider le parcours de production.

6. Surveillez les événements du premier jour.

   Consultez Admin → Événements de paiement pour détecter les échecs et confirmez que le tableau de bord du fournisseur affiche des livraisons réussies.

Bibliothèque de médias et CDN

Un seul pipeline de stockage pour les médias, les logos produits, les photos de fournisseurs, les avatars utilisateurs et les images du CMS. Système de fichiers local en développement ; S3 + CloudFront en production.

Types et limites pris en charge

La validation vérifie l'extension, le type de contenu déclaré, la signature des octets magiques et la taille. Les octets identiques au sein d'un même espace de travail sont dédupliqués par somme de contrôle SHA-256. GET /api/v1/media/supported-types/ alimente les indications de formats acceptés dans l'interface.

Modes de stockage

Le mode S3 nécessite boto3 et django-storages dans l'environnement de production. manage.py check échoue si le bucket est absent et avertit lorsqu'aucun domaine CDN ni aucune ACL public-read n'est configuré.

Configuration de CloudFront

1. Créez un bucket privé avec l'option Block all public access activée.
2. Créez une distribution CloudFront avec le bucket comme origine et Origin Access Control (OAC).
3. Accordez à la distribution s3:GetObject sur arn:aws:s3:::<bucket>/* via la politique de bucket générée.
4. Faites pointer MEDIA_CDN_DOMAIN vers la distribution ou vers un CNAME avec un certificat ACM.
5. Définissez éventuellement MEDIA_CDN_DISTRIBUTION_ID pour activer les actions de purge.

Flux de travail de la bibliothèque

• Console : le personnel importe et gère la bibliothèque ; les locataires voient une étagère d'espace de travail en lecture seule à l'adresse /dashboard/media ou /vendor/media.
• Collections : dossiers et catégories propres à l'espace de travail, avec recherche, filtres et déplacements groupés.
• Préréglages de renommage : kebab, snake, Title Case, UPPER ou keep, avec préfixes, suffixes et séquences complétées.
• Points focaux : focal_x/focal_y par ressource (0–100), utilisés par les blocs d'image du CMS.
• Sélection par plage : Maj+clic sur une plage, téléchargement, copie de l'URL et ouverture de la ressource précédente ou suivante dans le panneau.
• Badges d'utilisation : voyez où une ressource est référencée avant de la supprimer.

Sémantique du sélecteur

Choisir une ressource de la bibliothèque copie ses octets dans le champ cible. Le remplacement ou la suppression de la ressource de la bibliothèque ne casse jamais une image sélectionnée, et chaque modèle conserve son propre cycle de vie de stockage. Les ressources d'un autre espace de travail sont refusées.

Cibles connectées : logo de produit, profil et couverture du fournisseur, avatar utilisateur, image de marque de l'administration, images de catégorie, images du CMS et médias des blocs de contenu.

API des médias

Environnement

Consultez Configuration pour la matrice de stockage des médias et des spécifications, y compris l'URL de l'endpoint, le domaine CDN, l'ID de distribution et le comportement des ACL.

Studio newsletter

Marketing par e-mail réservé au personnel, avec audiences, modèles par blocs, campagnes, tests d'objet A/B, segments, automatisations, analyses par lien et e-mails système transactionnels.

Démarrage rapide

1. Ouvrez /admin/newsletter/ → Réglages et configurez le fournisseur, l'expéditeur, l'URL publique du backend, l'adresse postale et le texte de désabonnement.
2. Listes et contacts → créez une liste ; ajoutez ou importez des contacts au format email, name, tags.
3. Modèles → dupliquez un modèle de départ intégré ou partez d'une page vierge, concevez avec l'éditeur par blocs, puis enregistrez et prévisualisez.
4. Campagnes → choisissez un modèle, des listes, un segment facultatif et un ou plusieurs objets, puis envoyez-vous un test.
5. Automatisations → ajoutez des étapes d'e-mail et d'attente ; l'ajout à une liste ou les étiquettes déclenchent l'inscription.
6. E-mails système → associez des modèles à des déclencheurs transactionnels.

python3.11 manage.py newsletter_beat
# or schedule the Celery tasks:
# newsletter.send_due_campaigns
# newsletter.process_automations

Fournisseurs d'e-mail

Les secrets sont chiffrés au repos. Un bouton de test envoie un message via le fournisseur sélectionné avant de lancer une campagne.

Modèles et éditeur

• Blocs : en-tête, hero, texte, image, bouton, séparateur, espacement, image + texte, fonctionnalités, citation, liens sociaux, HTML brut, pied de page.
• Blocs avancés : colonnes, témoignage, tableau, vidéo, fiche produit, bannière CTA, note de pied de page.
• Variantes pour les mises en page hero, la taille et l'alignement du texte, les cadres et légendes d'image, le style, la taille et l'alignement des boutons, le style et la largeur du séparateur, le rayon du thème et la largeur du contenu.
• Glisser-déposer et réorganisation au clavier, aperçu en direct avec temporisation, version texte brut, préen-tête et URL assainies.
• Variables : {{first_name}}, {{action_url}}, {{message}}, {{site_name}}, {{unsubscribe_url}}, {{preferences_url}}.
• 18 modèles intégrés pour les lancements, récapitulatifs, webinaires, études de cas, reconquêtes, NPS, promotions, journaux des modifications, éditoriaux, mises en avant de la communauté, intégrations et annonces de service.

Campagnes

• L'audience correspond à l'union des listes sélectionnées ∩ segment facultatif, dédupliquée ; seuls les contacts abonnés sont inclus, les adresses en échec ou ayant fait l'objet d'un signalement étant exclues.
• Les tests d'objet A/B répartissent un pourcentage des destinataires, attendent une fenêtre, puis envoient la version gagnante au reste. L'option manuelle « désigner le gagnant maintenant » est disponible.
• Le renvoi aux non-ouvreurs crée un brouillon ciblant uniquement les contacts qui n'ont pas ouvert la campagne d'origine.
• Planification, mise en pause, reprise, annulation, envoi de test et calendrier des campagnes.
• Rapports : délivrabilité, ouvertures, clics, désabonnements, comparaison A/B, tableau des clics par lien, chronologie d'engagement et derniers destinataires.
• Les valeurs UTM par défaut sont appliquées aux liens de campagne ; seules les cibles http(s) sont acceptées.

Segments et automatisations

Les segments combinent des listes, des étiquettes (toutes/au moins une), le statut des contacts, des fenêtres d'engagement (ouvert, cliqué, non ouvert depuis N jours) et l'ancienneté d'inscription. Les comptages sont évalués en direct et réutilisés par les campagnes.

Les automatisations se déclenchent à l'ajout à une liste, par étiquette, manuellement ou via l'API. Les étapes envoient un e-mail ou attendent N heures. Les exécutions avancent de manière idempotente et enregistrent les échecs. L'inscription est dédupliquée par contact.

E-mails système

Si un modèle actif du studio est associé à un déclencheur, il génère du HTML + texte ; sinon, l'ancien message en texte brut est envoyé. Les clés disponibles incluent bienvenue, réinitialisation du mot de passe, code de connexion, alerte de sécurité, avis de plateforme, facture émise, échec de paiement, fournisseur approuvé, alerte de quota, invitation d'organisation et récapitulatif d'activité.

Inscription publique et préférences

• POST /api/v1/newsletter/subscribe/ avec confirmation par double opt-in facultative.
• GET /confirm/<token>/, GET /unsubscribe/<token>/ et POST en un clic conforme à la RFC 8058.
• Centre de préférences à /api/v1/newsletter/preferences/<token>/ pour activer ou désactiver des listes ou se désabonner globalement.
• Le pixel d'ouverture et les redirections de clic réécrivent les liens lorsque le suivi est activé.
• Les e-mails sortants incluent les en-têtes List-Unsubscribe et List-Unsubscribe-Post.

Délivrabilité et opérations

• Graphiques de rejets, de signalements, de désabonnements et de croissance ; maintenez les taux de rejet et de signalement proches de zéro.
• Carte de chaleur des heures d'envoi par jour de la semaine × heure locale, avec recommandations de meilleures fenêtres.
• Estimations d'audience et adresses d'exemple avant l'envoi.
• Page Contacts avec statut, étiquettes, champs personnalisés, appartenances, suppressions, livraisons, événements et exécutions d'automatisation.
• Exports CSV des contacts, des destinataires de campagne et des liens.
• Exécutez newsletter_beat toutes les quelques minutes pour les planifications, les décisions A/B et les délais d'automatisation.

Annonces et bannières

Bannières publiques conçues dans l'administration pour les barres supérieures, les emplacements de pied de page et les publicités intégrées à la page — avec ciblage, planification, règles de fermeture, expérimentations visuelles et analyses des impressions et des clics.

Emplacements

Une seule bannière est diffusée par emplacement, choisie selon la priorité puis la récence. Une bannière peut cibler plusieurs emplacements.

Ciblage et planification

• Chemins : motifs d'inclusion et d'exclusion tels que /pricing, /docs/* ou *.
• Audience : tout le monde, les visiteurs déconnectés ou les utilisateurs connectés.
• Locale et appareil : listes d'autorisation séparées par des virgules ; la tablette revient au mobile lorsque le mobile est autorisé.
• Planification : horodatages de début et de fin et commutateur d'activation.
• Priorité : les nombres les plus élevés l'emportent lorsque plusieurs bannières correspondent.

Design et bannières intégrées

• Mises en page : barre, carte, divisée, minimale.
• Badge, titre, corps, libellé, URL, style et ouverture dans un nouvel onglet du CTA, image, côté, couleurs, dégradés, alignement et aperçu en direct.
• Icône ou emoji facultatif, motifs décoratifs (points, grille, rayures, halo) et animations d'entrée compatibles avec la réduction des animations.
• 32 bannières intégrées pour les lancements, la confiance et le statut, les promotions, les événements, le cycle de vie, l'éditorial, la communauté et les campagnes saisonnières.
• HTML personnalisé avec les variables {{click_url}}, {{dismiss_url}} et {{impression_url}} pour que le suivi continue de fonctionner.
• Fréquence de fermeture : à chaque chargement de page, une fois par session, une fois par jour ou une seule fois.

Diffusion et suivi

GET  /api/v1/announcements/?path=/pricing&locale=en&placement=topbar
POST /api/v1/announcements/<id>/impression/
POST /api/v1/announcements/<id>/dismiss/
GET  /api/v1/announcements/<id>/click/

Les charges utiles incluent du HTML rendu côté serveur avec styles en ligne, ainsi que impression_url, dismiss_url et frequency. Les événements enregistrent l'emplacement, le chemin, la locale, l'appareil, le référent, l'agent utilisateur et l'IP.

Expérimentations et rapports

• Les bannières de même priorité partagent le trafic selon leur poids (1–1000).
• Définissez un nom d'expérimentation et un libellé de variante sur plusieurs bannières ; une variante est choisie par requête selon le poids.
• Les rapports d'expérimentation affichent les impressions, les clics, le CTR et la variante en tête.
• Les rapports tracent l'activité quotidienne sur 30/90 jours et détaillent les emplacements, les pages les plus vues, les appareils et les événements récents.
• Les listes d'administration affichent des compteurs, des actions d'activation et de mise en pause, ainsi que des enregistrements d'événements en lecture seule.

Opérations

Les événements de bannière sont en ajout seul. L'état de fermeture est stocké dans le navigateur du visiteur et comptabilisé côté serveur. Le script public ignore les agents utilisateur de robots ; utilisez un agent utilisateur de navigateur standard pour les tests QA des bannières publiques.

Liens courts

Liens courts prêts pour les campagnes, redirections, codes QR, valeurs UTM par défaut, solutions de repli, analyses des clics et vérifications des destinations cassées — disponibles à la fois dans le tableau de bord consommateur et dans le studio fournisseur.

Ce qu'elle fait

• Créez des liens courts avec un slug personnalisé, une destination, des étiquettes, un type de redirection, une expiration et un état actif.
• Redirections 301 ou 302 ; les liens expirés ou désactivés peuvent pointer vers une destination sûre de repli ou une page 410 personnalisée.
• Valeurs UTM par défaut (utm_source, utm_medium, utm_campaign) ajoutées au moment de la redirection ; les paramètres de campagne entrants ont la priorité.
• Génération de QR au format SVG avec couleur personnalisée et métadonnées de campagne.
• Analyses des clics avec pays, appareil, référent et contexte de campagne.
• Vérifications de l'état des destinations cassées avec détails des erreurs et revérification en un clic.
• Import/export CSV et actions sur les sélections multiples.

Console

Ouvrez Liens dans le tableau de bord consommateur (/dashboard/links) ou le studio fournisseur (/vendor/links). L'éditeur comprend le titre, la destination, le slug, les étiquettes, le type de redirection, l'expiration, le commutateur d'activation et une portée à l'échelle du site réservée au personnel. Le tableau propose des actions de copie, QR, revérification, modification, suppression, état de santé et statut.

Configuration

python3.11 manage.py checklinks --limit 200 --timeout 6

Résumé de l'API

Les redirections publiques se résolvent par slug, enregistrent le clic, puis redirigent. Les listes d'administration incluent des colonnes de clics et d'état de santé, des actions de revérification, d'activation et de désactivation, une action rapide « Raccourcir un lien » et un journal des clics en lecture seule.

Site, CMS et locales

Le plan de contrôle Django gère l'enveloppe publique : identité, valeurs par défaut de recherche et de partage, navigation, pages, articles de blog, documents juridiques, CSS/JS personnalisés, mode maintenance et surcharges de locale.

Surfaces opérateur

Paramètres du site

• Logo, favicon et image de partage social avec sélecteur de médias et nettoyage après validation.
• Titre et description meta globaux, et image de partage de repli.
• Mode place de marché, pourcentage de commission par défaut, indicateur de maintenance.
• Libellé et destination du CTA d'en-tête (doivent être fournis ensemble).
• Bannière d'annonce : activation, texte et URL.
• Titre, résumé, mention de copyright et e-mail d'assistance du pied de page.
• Défi intégré ou Google reCAPTCHA pour les formulaires publics.
• Politique d'authentification à deux facteurs obligatoire pour tous les comptes.
• Couleurs du thème, polices et aperçu en direct de l'enveloppe publique.

Contenu structuré

Les pages et les articles sont assemblés à partir de sections ordonnées, et non de HTML brut. Les types de sections disponibles incluent texte libre, tableau, code, image, vidéo, split, citation, onglets, code multilingue, exemple d'endpoint, témoignages, liste de fonctionnalités, FAQ, étapes, indicateurs, grille de cartes, séparateur, hero, bandeau de logos, frise chronologique, liste de liens, encadré, collection d'API, collection de catégories, API populaires et articles récents.

• Le texte libre accepte des paragraphes séparés par une ligne vide ; les éléments de liste vont un par ligne.
• Les actions exigent à la fois un libellé et une destination ; les liens acceptent les chemins du site, HTTPS, mailto ou tel.
• Les brouillons n'apparaissent jamais publiquement ; les pages publiées apparaissent dans le contenu du site, les métadonnées et les routes du sitemap.
• Le SEO au niveau de la page remplace les valeurs globales par champ.
• Les pages juridiques ne rejoignent le groupe juridique du pied de page par défaut qu'après leur publication.

CSS et JS personnalisés

Admin → Ressources personnalisées injecte du CSS ou du JavaScript dans le site public sans déploiement. Chaque extrait possède un type, un emplacement (head ou footer) et une portée (site entier, chemins sélectionnés ou une page). Les chemins acceptent les correspondances exactes et les jokers /prefix/*.

• Charge utile publique : GET /api/v1/platform/assets/ renvoie les extraits actifs ainsi que le csp_nonce configuré.
• Aperçu : chaque extrait dispose d'un aperçu en iframe dans l'administration, avec injection forcée via ?fr_preview_asset=<id>.
• Révisions : chaque enregistrement crée un instantané immuable avec auteur et note ; toute révision peut être restaurée en tant que nouvelle entrée.
• CSP : définissez le même nonce dans Paramètres du site et dans votre politique de CDN ; les balises le reçoivent automatiquement.

Locales et surcharges de traduction

L'anglais est le lot source de référence. Le français est livré complet. Toute autre locale est une surcharge d'administration partielle fusionnée avec l'anglais à l'exécution.

• Ouvrez Locales du site → Gérer les traductions pour consulter la couverture, modifier le français intégré ou ajouter une locale.
• Le français intégré apparaît à 100 % sans ligne en base de données. L'enregistrement d'un champ crée une surcharge d'administration sans modifier le texte de repli livré.
• Exportez en JSON ou TypeScript, traduisez hors ligne, puis réimportez. Les clés inconnues sont ignorées et signalées.
• L'API publique des locales renvoie les surcharges actives ; le frontend les fusionne par-dessus l'anglais et le français intégrés.
• Après avoir modifié lib/i18n/*.json, exécutez npm run export:i18n et redémarrez l'API pour actualiser son cache de processus.

Mode maintenance

La maintenance suspend toutes les routes frontend et les appels API et passerelle des clients. L'administration du personnel, les sondes de santé, les rappels des fournisseurs d'identité et les webhooks signés de paiement et de versement restent disponibles. La disponibilité publique est exposée anonymement avec l'indicateur de maintenance, l'avis et l'intervalle de nouvelle tentative.

Contrats publics

Intégrations externes, étape par étape

E-mail, stockage objet, authentification unique, infrastructure et webhooks sortants. Chaque section indique d'abord ce qu'il faut faire sur le site du fournisseur, puis exactement quelles valeurs copier dans FastRestful.

Quelle valeur l'emporte ?

• Les variables d'environnement fournissent les valeurs de déploiement par défaut.
• Les fiches gérées dans l'administration remplacent les valeurs d'environnement correspondantes champ par champ.
• La désactivation d'une fiche d'administration désactive ce fournisseur partout, même si les clés d'environnement restent définies.
• Les valeurs des fournisseurs côté frontend sont intégrées au moment de la compilation. Recompilez après avoir modifié NEXT_PUBLIC_*.
• Exécutez l'action de test du fournisseur avant d'envoyer du trafic réel.

Fournisseurs d'e-mail et de newsletter

FastRestful peut envoyer les e-mails de campagne, d'automatisation et système via votre propre fournisseur. Configurez-le dans Admin → Newsletter → Réglages e-mail, ou héritez du SMTP depuis les variables d'environnement EMAIL_*. Les clés API et les secrets sont chiffrés au repos.

La configuration en six étapes

1. Créez un compte chez un fournisseur.

   Utilisez un fournisseur transactionnel tel qu'Amazon SES, Mailgun, SendGrid, Postmark, Brevo, Mailjet, SparkPost, Resend ou tout hôte SMTP.

2. Vérifiez votre domaine d'envoi ou votre adresse d'expédition.

   La plupart des fournisseurs ne livrent pas tant que le domaine ou l'adresse e-mail n'est pas vérifié. Ajoutez les enregistrements DNS fournis par le fournisseur.

3. Créez la clé API ou les identifiants SMTP.

   Utilisez l'autorisation minimale permettant l'envoi d'e-mails. Pour SMTP, copiez l'hôte, le port, le nom d'utilisateur et le mot de passe.

4. Saisissez les valeurs dans FastRestful.

   Ouvrez Admin → Newsletter → Réglages e-mail. Choisissez le fournisseur, collez les identifiants et définissez le nom d'expéditeur, l'e-mail d'expédition, l'adresse de réponse, l'adresse postale et le texte de désabonnement.

5. Définissez l'URL publique du backend.

   Elle est utilisée dans les pixels de suivi, les liens de confirmation et les liens de désabonnement. Il doit s'agir de l'origine publique qui atteint Django, et non du serveur de développement frontend.

6. Envoyez-vous un e-mail de test.

   Utilisez l'action de test intégrée. Vérifiez la source complète du message pour l'expéditeur et les liens attendus avant d'envoyer une campagne.

Aide-mémoire des fournisseurs

La délivrabilité est un travail DNS. Authentifiez SPF, DKIM et DMARC avant d'augmenter le volume. Commencez par de petits envois, surveillez les rebonds et les plaintes, et gardez le lien de désabonnement fonctionnel. Les campagnes, les automatisations et les e-mails système peuvent utiliser des modèles différents, mais partagent le même fournisseur.

Stockage objet et CDN

Le stockage sur le système de fichiers local convient au développement. En production, utilisez un stockage compatible S3 avec un CDN, afin que les fichiers téléversés survivent aux déploiements et que les ressources se chargent rapidement.

1. Créez le bucket S3 et les autorisations

1. Créez un bucket privé.

   Dans la console AWS, créez un bucket dans la région souhaitée. Laissez l'option Bloquer tout accès public activée. CloudFront le lira via OAC.

2. Créez un utilisateur ou un rôle IAM.

   La chaîne d'identifiants standard est prise en charge : variables d'environnement, profil d'instance ou IRSA sur Kubernetes. Ne codez pas les clés en dur dans le dépôt.

3. Accordez uniquement les autorisations dont FastRestful a besoin.
   politique IAM minimaleCopier

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:ListBucket"],
         "Resource": "arn:aws:s3:::my-media-bucket"
       },
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
         "Resource": "arn:aws:s3:::my-media-bucket/*"
       }
     ]
   }

4. Installez les bibliothèques de stockage.

   Exécutez pip install boto3 django-storages dans l'environnement backend et ajoutez-les à vos dépendances de déploiement.

5. Définissez les valeurs d'environnement.
   backend/.envCopier

   MEDIA_STORAGE=s3
   MEDIA_S3_BUCKET=my-media-bucket
   MEDIA_S3_REGION=us-east-1
   # MEDIA_S3_ENDPOINT_URL=   # only for S3-compatible providers
   # MEDIA_S3_ACL=            # omit when using CloudFront OAC

6. Redémarrez et téléversez une ressource de test.

   Ouvrez la médiathèque et téléversez une image. Elle doit apparaître dans le bucket et se charger depuis l'URL CDN ou S3 configurée.

2. Placez CloudFront devant le bucket

1. Créez une distribution CloudFront.

   Choisissez le bucket comme origine et créez un Origin Access Control (OAC).

2. Mettez à jour la politique du bucket.

   Autorisez la distribution CloudFront à lire les objets. La console CloudFront peut générer la politique pour vous.

3. Définissez les valeurs FastRestful.
   backend/.envCopier

   MEDIA_CDN_DOMAIN=cdn.example.com
   MEDIA_CDN_DISTRIBUTION_ID=E1234567890ABC
   # MEDIA_S3_ACL=public-read   # only if serving S3 directly, not recommended

4. Autorisez l'invalidation du cache.

   Ajoutez cloudfront:CreateInvalidation à la politique IAM si vous voulez que le bouton de purge de la médiathèque fonctionne.

5. Testez avec un nouveau téléversement.

   Téléversez un nouveau fichier, ouvrez-le via le domaine CDN, puis remplacez-le et utilisez l'action de purge.

3. Fournisseurs compatibles S3

Cloudflare R2, MinIO, DigitalOcean Spaces et les services similaires fonctionnent via l'API S3. Définissez MEDIA_S3_ENDPOINT_URL sur l'endpoint S3 du fournisseur et gardez le bucket privé si le fournisseur prend en charge un CDN ou des URL signées. Vérifiez le téléversement, le téléchargement et la suppression avant de vous y fier en production.

4. Stockage des spécifications OpenAPI

Par défaut, les contrats OpenAPI importés sont stockés dans la base de données. Pour les stocker dans S3, définissez :

SPEC_STORAGE=s3
SPEC_S3_BUCKET=my-spec-bucket
SPEC_S3_PREFIX=specs/
SPEC_S3_REGION=us-east-1
# SPEC_S3_ENDPOINT_URL=

Consultez Médiathèque et CDN pour les limites de téléversement, les types de fichiers pris en charge et le comportement du CDN.

Authentification unique

OIDC et SAML préservent tous deux les destinations relatives sûres et les jetons d'invitation d'organisation. La connexion par mot de passe peut rester activée comme solution de repli.

OIDC, étape par étape

1. Créez une application OIDC dans votre fournisseur d'identité.

   Utilisez Okta, Auth0, Microsoft Entra ID, Google Workspace, Keycloak, Authentik ou tout fournisseur OIDC conforme.

2. Enregistrez l'URL de rappel.
   URI de redirectionCopier

   https://api.example.com/api/v1/auth/sso/callback/

   Utilisez exactement le nom d'hôte que les utilisateurs atteignent. Une différence de barre oblique finale fera échouer le rappel.

3. Autorisez le flux de code d'autorisation et les portées.

   Demandez openid, email et profile.

4. Copiez l'émetteur, l'ID client et le secret client.
   backend/.envCopier

   SSO_ISSUER=https://login.example.com/realms/acme
   SSO_CLIENT_ID=fastrestful
   SSO_CLIENT_SECRET=...

5. Redémarrez le backend.

   Le bouton SSO reste masqué tant que le fournisseur n'est pas configuré.

6. Testez avec une identité réelle.

   Connectez-vous via le bouton et confirmez que le rappel revient vers la route frontend attendue.

SAML 2.0, étape par étape

1. Installez la dépendance facultative.

   Exécutez pip install lxml avant d'activer SAML.

2. Copiez les métadonnées SP.

   Communiquez cette URL à votre fournisseur d'identité ou téléversez le XML qu'il renvoie :

   Métadonnées SPCopier

   https://api.example.com/api/v1/auth/saml/metadata/

3. Définissez l'URL ACS et l'ID d'entité dans l'IdP.

   Le service de consommation d'assertions est :

   URL ACSCopier

   https://api.example.com/api/v1/auth/saml/callback/

   L'ID d'entité par défaut est fastrestful. Vous pouvez le modifier avec SSO_SAML_ENTITY_ID.

4. Copiez l'URL SSO de l'IdP et le certificat de signature.
   backend/.envCopier

   SSO_SAML_ENABLED=1
   SSO_SAML_ENTITY_ID=fastrestful
   SSO_SAML_SSO_URL=https://idp.example.com/sso
   SSO_SAML_IDP_CERT=-----BEGIN CERTIFICATE-----...
   # SSO_SAML_AUDIENCE=fastrestful

5. Redémarrez et testez.

   Lancez une connexion depuis le frontend et confirmez que l'assertion de l'IdP revient vers la page attendue.

Fournisseurs d'infrastructure

Outillage API et webhooks sortants

OpenAPI, Swagger et Postman

• Import OpenAPI : importez OpenAPI 3.x ou Swagger 2.0 dans une version brouillon. Le pipeline de publication réconcilie les endpoints et signale les changements incompatibles.
• Schéma de la plateforme : exportez-le sur /api/schema/ avec python3.11 manage.py spectacular --file schema.yml --validate.
• Swagger UI : servi sur /api/docs/ par le backend.
• Postman / kits de démarrage : les endpoints produit exposent des bundles téléchargeables pour les consommateurs.

Webhooks sortants, étape par étape

1. Créez l'endpoint dans FastRestful.

   Ouvrez la section des endpoints de webhook du plan de contrôle et ajoutez l'URL de votre récepteur. Elle doit utiliser HTTPS.

2. Choisissez les événements et un secret de signature.

   Stockez un secret robuste. FastRestful signe le corps brut de la requête avec HMAC-SHA256.

3. Envoyez une livraison de test.

   Confirmez que votre récepteur renvoie une réponse 2xx.

4. Vérifiez la signature sur votre serveur.

   Comparez votre propre HMAC-SHA256 du corps brut avec l'en-tête X-FastRestful-Signature. La valeur est sha256=<hex>. Le nom de l'événement se trouve dans X-FastRestful-Event.

5. Surveillez le journal de livraison.

   Les nouvelles tentatives sont sûres et l'historique de livraison est une preuve en lecture seule. Traitez les noms d'événements en double de manière idempotente.

Les webhooks de paiement sont distincts. Les webhooks des fournisseurs règlent les sommes et sont enregistrés dans le tableau de bord de chaque fournisseur. Les webhooks sortants de fournisseur servent à vos propres intégrations. Ne pointez pas un fournisseur de paiement vers un endpoint de webhook de fournisseur.

Liste de contrôle d'acceptation des intégrations

• Le fournisseur apparaît comme configuré et activé dans la page d'administration ou de paramètres.
• Un véritable message ou téléversement de test atteint le fournisseur et l'URL renvoyée se charge.
• L'e-mail de test arrive ; SPF, DKIM et DMARC passent.
• Les médias téléversés sont stockés dans le bucket et servis via le CDN.
• Le rappel OIDC ou SAML revient vers la route frontend attendue.
• Les signatures des webhooks sortants se vérifient sur le récepteur.
• Les nouvelles tentatives ne dupliquent pas les effets de bord.
• Les identifiants de test et de production ne sont pas mélangés.

Sauvegardes et mises à niveau

Un processus reproductible de sauvegarde, de restauration et de mise à niveau pour un déploiement FastRestful auto-hébergé. Les sauvegardes passent en premier ; la méthode de mise à niveau dépend de la façon dont vous avez acheté et déployé le produit.

Éléments à sauvegarder

Sauvegarde PostgreSQL

pg_dump --format=custom "$DATABASE_URL" > fastrestful-$(date +%F-%H%M).dump
pg_dump --format=plain "$DATABASE_URL" | gzip > fastrestful-$(date +%F-%H%M).sql.gz

# Verify the dump is readable
pg_restore --list fastrestful-$(date +%F-%H%M).dump > /dev/null

Restaurer dans une base de données propre

createdb fastrestful_restore
pg_restore --clean --if-exists --no-owner \
  --dbname=fastrestful_restore fastrestful-2026-10-21.dump

# Point a staging deployment at the restored database and run:
python3.11 manage.py migrate --check
python3.11 manage.py check

Testez les restaurations chaque trimestre. Une sauvegarde qui n'a jamais été restaurée est une hypothèse, pas un plan de reprise.

Deux façons de mettre à niveau

Séquence de mise à niveau manuelle

À utiliser uniquement pour un déploiement personnalisé qui n'est pas géré par le centre de mises à jour officiel.

1. Lisez les notes de version et vérifiez les changements de migration ou d'environnement.
2. Sauvegardez PostgreSQL, les médias et les secrets.
3. Placez la plateforme en mode maintenance si une migration nécessite une pause des écritures.
4. Récupérez le code, installez les dépendances backend et frontend.
5. Exécutez les migrations, collectez les fichiers statiques et construisez le frontend.
6. Redémarrez l'API et les workers ; vérifiez l'état de préparation et effectuez une requête de contrôle.
7. Quittez le mode maintenance et surveillez le taux d'erreur, la profondeur de file d'attente et les réceptions de webhooks.

git pull --ff-only
pip install -r backend/requirements.txt
npm ci

python3.11 backend/manage.py migrate --noinput
python3.11 backend/manage.py collectstatic --noinput
npm run build

sudo systemctl restart fastrestful
sudo systemctl restart fastrestful-worker fastrestful-beat
curl -f https://api.example.com/api/health/ready

Retour arrière

• Le retour arrière du code est simple uniquement lorsque la version précédente n'exigeait pas de migration de base de données irréversible.
• Conservez un instantané de la base de données avant chaque migration. Restaurez ensemble l'instantané et la version de code correspondante.
• Ne modifiez jamais une migration déjà appliquée en production ; ajoutez une nouvelle migration corrective.
• Après un retour arrière, relancez la requête de contrôle et inspectez les tâches en file d'attente pour vérifier les hypothèses de schéma.

Sécurité des migrations

python3.11 manage.py showmigrations
python3.11 manage.py makemigrations --check --dry-run
python3.11 manage.py migrate --plan

• D'abord des ajouts, ensuite le remplissage des données, puis la suppression des anciens champs dans une version ultérieure.
• Évitez les verrous de table prolongés sur les tables de comptage, de journal de requêtes et d'audit à fort volume.
• Activez le mode maintenance pour les migrations qui modifient les colonnes d'état monétaire ou d'état de version.
• Laissez Celery en pause jusqu'à la fin des migrations.

Publications du frontend

Le build frontend est statique et autonome. Alignez l'origine de l'API et l'URL du site public sur le déploiement. Si vous déployez un nouveau build qui attend de nouveaux champs d'API, publiez d'abord le backend ou gardez le contrat rétrocompatible.

Observabilité

Santé, journaux, métriques et files d'attente pour une plateforme où les requêtes, l'argent et la modération laissent tous des traces.

Santé et état de préparation

Utilisez l'état de préparation pour l'appartenance à l'équilibreur de charge. Une panne de cache renvoie 503 avec la dépendance défaillante au lieu de servir avec un état local uniquement.

Contexte des requêtes

• Chaque réponse d'API porte des métadonnées de requête dans les journaux applicatifs. Préservez l'ID de requête à travers votre reverse proxy.
• Les journaux de requêtes de la passerelle incluent l'abonnement, le produit, l'endpoint, le statut, la latence et des aperçus expurgés.
• Les événements fournisseur stockent les ID d'événement et les hachages de charge utile, pas les secrets bruts.
• Les événements d'audit relient l'acteur, l'action, l'organisation, la cible et les métadonnées.

Signaux à surveiller

Règles de journalisation

• Ne journalisez jamais les clés API brutes, les secrets des fournisseurs ou les charges utiles de paiement complètes.
• Gardez les aperçus de requête et de réponse limités et expurgés.
• Journalisez les ID d'événement fournisseur et les résultats de règlement, pas les données de carte.
• Utilisez des champs structurés lorsque possible : ID de requête, organisation, produit, endpoint, statut.
• Séparez les preuves d'audit des journaux applicatifs ordinaires.

Files d'attente et tâches planifiées

celery -A config inspect ping
celery -A config inspect active
celery -A config inspect reserved
celery -A config inspect scheduled

Surveillez séparément les files par défaut et de facturation. Le règlement s'exécute chaque mois ; la modération et les notifications s'exécutent toutes les 15 minutes ; les contrôles de disponibilité s'exécutent chaque jour.

Ensemble minimal d'alertes

• État de préparation en échec pendant plus de 2 minutes.
• Taux de 5xx de l'API au-dessus de l'objectif de service.
• Circuit de la passerelle ouvert ou taux d'erreur amont en forte hausse.
• Échecs de webhook ou événements fournisseur non traités.
• Signal beat de Celery absent ; profondeur de file en augmentation.
• Saturation du disque et des connexions de la base de données.
• Échec de sauvegarde ou dernière sauvegarde réussie trop ancienne.
• Baisse inattendue des inscriptions à la double authentification pour le personnel.

Commandes de diagnostic

python3.11 manage.py check --deploy
python3.11 manage.py showmigrations
python3.11 manage.py prune_telemetry --request-log-days 90 --usage-event-days 365
python3.11 manage.py check_api_availability
python3.11 manage.py checklinks --limit 200 --timeout 6

Mise à l'échelle

Où FastRestful monte en charge sans difficulté, où une infrastructure est nécessaire et quel état doit rester partagé.

Mettez à l'échelle les niveaux séparément

edge / CDN
  ├── frontend static assets
  └── API reverse proxy
        ├── Django / Gunicorn replicas
        ├── Celery workers (default queue)
        ├── Celery workers (billing queue)
        ├── Celery beat (one instance)
        ├── PostgreSQL primary + read capacity
        └── Redis (shared cache + broker)

Niveau web

• Exécutez plusieurs instances Gunicorn/Django sans état derrière un équilibreur de charge.
• Les sessions résident dans la base de données ; le cache et les limitations de débit utilisent Redis. Ne vous appuyez pas sur la mémoire locale en production.
• Dimensionnez les workers pour la requête de passerelle la plus lente (délai d'expiration par défaut de 15 secondes).
• Terminez TLS en périphérie et préservez l'hôte d'origine pour le routage produit.

Base de données

• Utilisez PostgreSQL avec un pool de connexions à mesure que le nombre de workers augmente.
• Tables à fort volume : événements d'usage, journaux de requêtes, événements d'audit, livraisons de webhooks.
• Élaguez la télémétrie selon un calendrier et archivez les preuves d'audit conformément à la politique.
• Conservez les écritures d'état monétaire dans des transactions ; ne partitionnez pas les tables de factures ou de grand livre sans plan de migration.

Redis

• Un cache partagé est requis pour les limites de débit de la passerelle et l'idempotence.
• Une panne Redis renvoie un 503 réessayable avant la réservation de quota ; la passerelle ne se rabat pas sur un état par processus.
• Surveillez les évictions. La perte d'enregistrements d'idempotence peut permettre des appels amont en double après un changement de TTL.
• Utilisez une base de données ou une instance Redis distincte pour le broker Celery si la pression du cache augmente.

Capacité de la passerelle

• Les quotas et limites de débit sont appliqués par abonnement et par endpoint, pas par processus.
• La latence amont domine le temps de requête ; gardez des délais d'expiration et des nouvelles tentatives prudents.
• Le stockage d'idempotence croît avec le volume de requêtes ; dimensionnez Redis pour le TTL configuré.
• Utilisez le routage par hôte produit avec TLS générique pour éviter un goulot d'étranglement de chemin central en périphérie.

Workers et tâches planifiées

• Exécutez une seule instance beat ; plusieurs planificateurs beat peuvent dupliquer les tâches minutées.
• Mettez à l'échelle séparément les files de facturation et par défaut.
• Gardez le règlement idempotent ; les réexécutions sont sûres par conception.
• Appliquez une contre-pression aux files d'e-mails et de modération via la concurrence des workers plutôt qu'en désactivant les nouvelles tentatives.

Médias et CDN

• Déplacez les téléversements vers S3 avant que le cycle de vie du disque local ne devienne un problème.
• Servez via CloudFront avec des noms d'objets immuables et une mise en cache longue durée.
• Gardez l'accès à l'origine privé ; évitez les politiques de bucket publiques.
• Utilisez la purge par ressource uniquement lorsqu'une clé d'objet est réutilisée intentionnellement.

Liste de contrôle de capacité

• Les alertes d'état de préparation et de 5xx sont reliées à l'astreinte.
• PostgreSQL dispose de marge pour les connexions, le disque et les IOPS.
• Redis dispose de marge pour le cache et les enregistrements d'idempotence.
• La profondeur de file Celery et le signal beat sont surveillés.
• Le stockage objet et le CDN sont hors du serveur web.
• La rétention de la télémétrie est configurée avant la croissance, pas après.

Modèle de données et autorisations

Les entités qui définissent FastRestful, les frontières de locataires qui les entourent et les invariants qui maintiennent la cohérence de l'argent et des versions.

Gestion des locataires

Organization constitue la frontière du locataire. Un utilisateur rejoint l'organisation via une Membership avec un rôle. L'organisation active est transmise explicitement et résolue côté serveur avant tout accès aux objets.

Entités principales

Invariants

• Un produit possède une seule version active à la fois.
• Le contrat et le catalogue d'endpoints d'une version active ne peuvent pas être modifiés.
• Un abonnement comporte des conditions commerciales immuables ; tout changement crée un nouveau forfait.
• Une clé API appartient à une seule application et ne peut pas traverser les applications.
• Un ID d'événement fournisseur est enregistré une seule fois ; les rejeux ne règlent pas deux fois.
• Les versements suivent une machine à états monotone.
• Les écritures du grand livre sont en ajout seul.
• Le dernier propriétaire actif de l'espace de travail ne peut pas être supprimé ni rétrogradé.

Vérifications des autorisations

Suppression et rétention

• Les tickets ne sont jamais supprimés ; ils restent des preuves de support.
• L'historique des versions actives reste disponible pour l'audit même après dépréciation.
• Les événements d'audit et les reçus fournisseur sont en ajout seul.
• Les journaux de requêtes et les événements d'usage sont élagués selon la rétention configurée.
• Les suppressions de médias suivent le cycle de vie des ressources et doivent respecter les références en cours d'utilisation.

Extension du modèle

1. Partez d'un flux de travail réel, pas d'un champ hypothétique.
2. Gardez les données réservées à la plateforme hors des sérialiseurs anonymes.
3. Validez au niveau du modèle ou de l'API ; ajoutez des contraintes de base de données pour l'argent et les transitions d'état.
4. Ajoutez des tests de contrat pour les autorisations, les frontières de locataires et l'idempotence.
5. Documentez la surface opérateur avant de livrer le modèle.

Extensions

Étendez l'expérience publique et le flux opérationnel sans forker le cœur : ressources personnalisées, sections CMS, surcouches de langue, webhooks et modèles d'administration.

CSS et JavaScript personnalisés

Admin → Ressources personnalisées injecte un extrait dans le site public. Chaque extrait possède un type, un emplacement, une portée et un état actif.

• Chaque enregistrement crée une révision immuable avec auteur et note ; toute révision peut être restaurée en tant que nouvelle entrée.
• Prévisualisez le site en direct dans une iframe d'administration avec l'extrait injecté de force.
• Utilisez le nonce CSP configuré à la fois dans les paramètres du site et dans la politique de périphérie ; les balises injectées le reçoivent automatiquement.
• Traitez les extraits comme du code opérateur de confiance. Ils peuvent restyler ou instrumenter le site public.

Sections CMS structurées

Les pages et les articles sont assemblés à partir de sections ordonnées. L'éditeur comprend les blocs prose, tableau, code, image, vidéo, split, citation, onglets, groupes de code, exemples d'endpoints, témoignages, fonctionnalités, FAQ, étapes, métriques, cartes, séparateurs, hero, bandeau de logos, chronologie, liste de liens, encadrés, collections d'API, collections de catégories, meilleures API et articles récents.

• Utilisez des sections structurées plutôt que coller du HTML arbitraire.
• Définissez ensemble le libellé de l'action et sa destination.
• Utilisez des chemins du site, HTTPS, mailto ou des destinations tel.
• Conservez un texte alternatif d'image significatif ; le corps du texte peut servir de légende.
• Les pages publiées n'intègrent les métadonnées de navigation et de sitemap que lorsqu'elles sont en ligne.

Surcouches de langue

L'anglais est le bundle canonique ; le français est livré complet. Ajoutez une autre langue dans l'administration, importez un bundle JSON ou TypeScript et ne remplacez que les clés nécessaires.

• Les valeurs intégrées restent la solution de repli lorsqu'une clé de surcouche est vide.
• Les clés inconnues sont ignorées et signalées lors de l'import.
• Exportez en JSON ou TypeScript pour une traduction hors ligne.
• Exécutez npm run export:i18n après avoir modifié le bundle frontend et redémarrez l'API.

Webhooks sortants

Les webhooks fournisseur livrent des événements signés à des endpoints HTTPS avec un historique de livraison sûr en cas de nouvelle tentative. Gardez le secret de signature dans l'espace de travail fournisseur et vérifiez la signature avant d'agir sur une charge utile.

• Utilisez une URL d'endpoint stable et renvoyez rapidement une réponse 2xx.
• Considérez les événements comme étant livrés au moins une fois et rendez les gestionnaires idempotents.
• Utilisez le journal de livraison pour inspecter le statut de réponse et les aperçus.
• Ne réutilisez pas les routes de webhook d'un fournisseur de paiement pour les événements fournisseur.

Modèle d'extension de l'administration

1. Enregistrez le modèle avec un comportement explicite de liste, de filtre, de recherche et d'autorisation.
2. Ajoutez un formulaire d'administration ciblé plutôt que d'exposer des champs internes bruts.
3. Utilisez des événements d'audit pour les actions qui modifient l'état.
4. N'ajoutez une page de prévisualisation ou de rapport que lorsqu'elle répond à une question opérateur réelle.
5. Testez les frontières d'autorisation et la séparation des sérialiseurs publics et privés.

Modèle d'extension de l'API

• Maintenez la portée du locataire avant chaque requête.
• Utilisez des sérialiseurs de requête et de réponse explicites.
• Renvoyez des codes d'erreur stables pour le comportement client.
• Rendez les nouvelles tentatives sûres grâce à l'idempotence lorsque de l'argent ou de l'état est concerné.
• Ajoutez des annotations OpenAPI pour que le schéma reste exploitable.

Administration

Le plan de contrôle du personnel est une interface d'administration Django sensible aux autorisations pour les opérations de la plateforme. Il n'utilise pas de métriques de démonstration et ne contourne pas les autorisations de modèle.

Périmètre d'accès

• L'accès du personnel nécessite is_staff. Un rôle admin d'espace de travail n'est pas un rôle de personnel de plateforme.
• La double authentification peut être exigée pour chaque compte depuis les paramètres du site.
• Les autorisations de modèle Django et le comportement du ModelAdmin enregistré sont respectés.
• Les lectures en administration peuvent être plus larges que les écritures ; la propriété des objets et l'état du fournisseur conditionnent toujours les actions conséquentes.
• Chaque action sensible doit créer un événement d'audit avec acteur, cible et métadonnées.

Vue d'ensemble des opérations

/admin/ affiche un instantané en direct et en lecture seule construit à partir des enregistrements actuels : trafic, API publiques, consommateurs actifs, espaces de travail actifs, messages de contact, adoption de la double authentification, annonces de la plateforme, files nécessitant une attention, état des paiements, flux d'audit, expérience du site et couverture des langues.

• Actions rapides : créer une API, examiner les fournisseurs, paramètres du site, forfaits de plateforme, studio de contenu, newsletter, bannières, liens.
• Files de décision : fournisseurs, modération, appels, restrictions de sécurité, support, webhooks en échec, versements, factures, boîte de réception des contacts.
• Panneau de paiement : revenus par fournisseur, abonnements actifs, MRR, paiements en attente, reçus de webhooks, remboursements, liens de passerelle.

Sections du plan de contrôle

Modération et sécurité

• Les signalements comportent le type et le libellé de la cible, la catégorie, les preuves, la priorité, l'échéance SLA, l'affectation et des résumés de résolution publics et privés.
• Le personnel configure les fenêtres SLA par priorité, les seuils d'escalade et les fenêtres d'appel dans Politique de modération.
• Les signalements clos éligibles peuvent faire l'objet d'un appel une fois dans la fenêtre ; la décision publique d'origine reste attachée.
• Les appels acceptés rouvrent le dossier avec un nouveau SLA dérivé de la politique.
• La résolution d'un signalement confirmé peut émettre une sanction de sécurité auditable : avertissement, restriction communautaire, restriction de publication ou restriction de plateforme.
• Les dossiers de sanction indiquent les points, le motif public, les dates d'effet et le statut ; seuls l'utilisateur concerné ou les membres actifs du fournisseur peuvent les lire.

Support et équipe

• Les tickets relient le consommateur, le produit, l'abonnement et, facultativement, le contexte du journal de requêtes.
• Les messages actualisent l'horodatage d'activité du ticket afin que les files restent triées par dernière réponse.
• Les invitations d'équipe, changements de rôle, désactivations et retraits sont réservés au propriétaire ou à l'administrateur ; le dernier propriétaire actif ne peut pas être retiré.
• Les invitations sont hachées, à usage unique, liées à une adresse e-mail et expirent.

Forfaits de plateforme et réconciliation

• Cinq forfaits de plateforme maximum ; les codes restent stables après leur création.
• Prix affiché, ID fournisseur annuels et mensuels, limite d'espaces de travail, limite de publication d'API, avantages et recommandation.
• Les forfaits payants ne sont pas publiés tant qu'une paire montant + ID de prix récurrent fournisseur n'existe pas.
• La réconciliation en lecture seule des abonnements de plateforme affiche l'état et les droits sans permettre au personnel de diverger du fournisseur.

Notifications de plateforme

Les annonces rédigées par le personnel sont diffusées dans des lignes de boîte de réception par utilisateur. L'audience peut être tous les comptes ou le personnel uniquement ; les niveaux sont info, avis et critique. Les compteurs de livraison apparaissent dans l'instantané des opérations.

Audit et exports

• Événements d'audit en ajout seul avec acteur, action, organisation, cible et métadonnées.
• Les tâches d'export prennent en charge les flux de travail d'examen de sécurité et de rétention.
• Les listes d'administration proposent des vues filtrées, la recherche et l'export CSV lorsque c'est pertinent.
• Ne placez jamais de secrets bruts, de clés API ou de charges utiles de fournisseur dans les métadonnées d'audit.

Gestion des langues

Langues du site → Gérer les traductions affiche les langues intégrées et gérées, la couverture et les clés manquantes. Le français intégré est modifiable via une surcouche d'administration. L'import/export prend en charge JSON et les littéraux TypeScript ; les clés inconnues sont ignorées et signalées.

Référence de l'API

L'API FastRestful est une surface Django REST Framework dont la racine est /api/v1/. OpenAPI est servi par le backend et constitue le contrat de référence.

URL de base et documentation

Authentification

curl --request POST \
  --url 'https://api.example.com/api/v1/auth/token/' \
  --header 'Content-Type: application/json' \
  --data '{"username":"[email protected]","password":"..."}'

# Response
{"access":"...", "refresh":"...", "user": {...}}

curl --request GET \
  --url 'https://api.example.com/api/v1/dashboard/consumer/' \
  --header 'Authorization: Bearer <access>' \
  --header 'X-Organization: <organization-uuid>'

Espaces de noms

Carte des endpoints principaux

Pagination et filtrage

Les endpoints de liste utilisent un contrat par numéro de page : page, page_size, search, ordering et les filtres de ressource. Les réponses utilisent {count, next, previous, results}. Le tri accepte un nom de champ, éventuellement préfixé par -.

GET /api/v1/products/?page=2&page_size=25&search=delivery&ordering=-rating_average
GET /api/v1/invoices/?status=paid&ordering=-created_at
GET /api/v1/request-logs/?status_class=server&ordering=-created_at

Format des erreurs

Les erreurs de validation utilisent l'objet à clés de champ de DRF. Les erreurs de passerelle et de plateforme utilisent un objet JSON avec un code lisible par machine, un message destiné aux humains et des métadonnées de nouvelle tentative facultatives.

{
  "detail": "Monthly quota exceeded.",
  "code": "quota_exceeded",
  "retry_after": 300
}

Format d'appel de la passerelle

GET https://signal-stack.api.example.com/v2/deliveries?limit=10
X-API-Key: fr_live_…
Idempotency-Key: request-8241

{
  "status": 200,
  "latency_ms": 84,
  "content_type": "application/json",
  "data_preview": "...",
  "headers": {...}
}

Webhooks

FastRestful comporte deux types de webhooks. Gardez-les séparés :

POST /api/v1/billing/stripe-webhook/
POST /api/v1/billing/paypal-webhook/
POST /api/v1/billing/flutterwave-webhook/
POST /api/v1/billing/paystack-webhook/
POST /api/v1/billing/razorpay-webhook/

• Les endpoints de webhook fournisseur doivent utiliser HTTPS et stocker un secret de signature.
• Les livraisons sont signées, réessayées en toute sécurité et journalisées avec leur statut et un aperçu de la réponse.
• Les webhooks du fournisseur de paiement sont enregistrés dans le tableau de bord de chaque fournisseur, et non dans la section des webhooks fournisseur.
• Les ID d'événement fournisseur sont uniques ; les événements signés en double sont acquittés sans double règlement.
• La configuration et les listes d'événements de webhook se trouvent dans Passerelles de paiement, étape par étape.

Flux de travail OpenAPI

cd backend
python3.11 manage.py spectacular --file schema.yml --validate

Utilisez le schéma généré pour les SDK, Postman ou les tests de contrat. Les contrats OpenAPI au niveau produit sont distincts : ils sont importés dans les versions d'API et promus via le pipeline de publication.

En cas de blocage

Si un endpoint renvoie un code inattendu, vérifiez d'abord l'ID de requête, la méthode d'authentification, l'en-tête d'espace de travail et l'état de l'abonnement. Le Guide de dépannage couvre les modes de défaillance courants dans l'ordre.