Système de réponse automatique aux litiges Stripe avec PDF de preuves

Construisez un système de réponse automatique aux litiges pour Stripe qui : 1. Collecte de preuves partagée (app/dispute_evidence.php) Créez un fichier partagé avec des fonctions utilisées à la fois par le webhook et le worker de synchronisation. Cela évite de dupliquer la logique de preuve. Fonctions clés : - getDisputeUserPlan($user, $stripe) - récupère le plan d'abonnement de l'utilisateur depuis l'API Stripe (source de vérité, car le champ de plan dans la base de données locale est effacé à l'annulation). Retombe sur les champs de la base de données locale si l'appel Stripe échoue. Mappe les ID de produits aux noms de plans et inclut le prix/intervalle et le statut d'annulation. - collectDisputeEvidence($stripe, $user, $email, $charge, $photosDb) - collecte toutes les preuves textuelles et fichiers, retourne un tableau prêt à soumettre à Stripe. - generateServiceDocPdf($stripe, $user, $email, $photos_done, $recent_photos, $total_amount_paid) - génère un PDF avec les informations client, le résumé d'utilisation, le tableau d'activité récente et jusqu'à 6 images réelles de produits (redimensionnées en JPEG de 500px de large / qualité 75 pour rester sous la limite de téléchargement de fichiers de 5 Mo de Stripe). Retourne à la fois l'ID de fichier Stripe et les données PDF brutes. Important : récupérez total_amount_paid depuis l'API de frais Stripe (somme des frais réussis non remboursés) au lieu de faire confiance à la base de données locale qui peut être nulle/obsolète. 2. Gestionnaire de webhook (dans stripe_webhook.php) Capturez les événements charge.dispute.created. Quand un litige arrive : - Obtenez les objets litige, frais et client depuis Stripe - Recherchez l'utilisateur dans la base de données locale par stripe_customer_id - Enregistrez le litige dans une base de données SQLite des litiges (champs : dispute_id, charge_id, payment_intent_id, stripe_customer_id, user_id, email, amount, currency, reason, status, epoch_created, epoch_evidence_submitted, evidence_json, stripe_response, epoch_resolved, outcome) - Appelez collectDisputeEvidence() pour collecter toutes les preuves (texte + téléchargements de fichiers) - Soumettez les preuves à Stripe via $stripe->disputes->update($dispute_id, ['evidence' => $evidence]) - Envoyez une notification Telegram qu'un nouveau litige est arrivé et que les preuves ont été soumises automatiquement Capturez également les événements charge.dispute.updated et charge.dispute.closed pour suivre les résultats des litiges (gagnés/perdus) dans la base de données et envoyer des notifications Telegram avec le résultat. 3. Champs de preuve soumis à Stripe Champs TEXTE (écrivez des chaînes directement) : - product_description - décrivez ce qu'est le produit/service - customer_name / customer_email_address - depuis l'objet client Stripe - access_activity_log - journal d'utilisation détaillé : date d'inscription, nombre d'éléments/actions effectués, dernière date d'activité, plan d'abonnement (depuis Stripe), plateforme, montant total payé (depuis Stripe), activité récente avec horodatages - uncategorized_text - l'argument "pourquoi nous devrions gagner" : le client s'est inscrit sur X, a activement utilisé le service en faisant Y choses, montant total payé, le service a été livré numériquement/instantanément, le client ne nous a jamais contactés pour un remboursement avant de contester - refund_policy_disclosure / cancellation_policy_disclosure - quand les politiques ont été présentées (lors du paiement, toujours accessibles sur /legal) - refund_refusal_explanation / cancellation_rebuttal - preuve d'utilisation et absence de contact préalable - service_date - date du frais (format Y-m-d) Champs de TÉLÉCHARGEMENT DE FICHIER (téléchargez d'abord le fichier sur Stripe via $stripe->files->create(['purpose'=>'dispute_evidence', 'file'=>fopen($path,'r')]), puis passez l'ID file_xxxxx retourné) : - receipt - récupérez le PDF de facture directement depuis Stripe ($stripe->invoices->retrieve($charge->invoice)->invoice_pdf), téléchargez-le et téléversez-le comme preuve de litige - service_documentation - générez un PDF contenant : section d'informations client, résumé d'utilisation du service, tableau d'activité récente et jusqu'à 6 images/captures d'écran réelles du produit que le client a reçues. Redimensionnez les images avant de les intégrer (500px de large, qualité JPEG 75) pour rester sous la limite de 5 Mo de Stripe. Enregistrez également les deux PDF dans votre stockage de fichiers (par exemple, Cloudflare R2, S3) avec des noms de fichiers hachés pour qu'ils ne soient pas devinables mais visibles depuis le tableau de bord d'administration. Stockez les URL de stockage dans evidence_json comme _receipt_r2_url et _service_doc_r2_url. 4. Worker de synchronisation CLI (workers/syncDisputes.php) Un script qui récupère TOUS les litiges existants depuis l'API Stripe (paginé avec $stripe->disputes->all(['limit' => 100]) et starting_after pour la pagination), les enregistre dans la base de données locale des litiges, et pour ceux qui ont encore un statut needs_response ou warning_needs_response et n'ont pas encore eu de preuves soumises, soumet automatiquement les preuves en utilisant la fonction partagée collectDisputeEvidence(). Cela est nécessaire car le webhook ne capture que les litiges futurs, pas les existants. Exécutez uniquement via CLI (php workers/syncDisputes.php). Enregistre un fichier cache JSON avec les résultats de synchronisation pour que le tableau de bord puisse afficher la dernière heure de synchronisation. 5. Mini tableau de bord (disputes.php avec authentification ?key=) Une page HTML simple protégée par le paramètre de requête ?key= qui affiche : - Boîtes de statistiques : litiges totaux, en attente, gagnés, perdus, contestés au cours des 30 derniers jours (montant + nombre), contestés au cours des 12 derniers mois (montant + nombre), total $ contesté - Une note montrant la commande de synchronisation CLI et la dernière heure de synchronisation depuis le cache - Un formulaire de test où vous entrez un stripe_customer_id pour prévisualiser quelles preuves seraient soumises (sans réellement soumettre) - Un tableau de tous les litiges : date, email, montant, raison, statut (badges colorés), statut de soumission des preuves, liens vers la vue détaillée et le tableau de bord Stripe Vue détaillée (action=view&id=dispute_id) : affiche toutes les informations du litige, lien vers Stripe, et un bouton "Régénérer les preuves", liens de fichiers PDF, ID de téléchargement de fichiers Stripe, tous les champs de preuve texte. Régénérer les preuves (action=regen&id=dispute_id) : régénère les PDF de reçu et de documentation de service et les téléverse vers le stockage de fichiers, met à jour evidence_json avec de nouvelles URL PDF. Utilisez fastcgi_finish_request() pour envoyer la réponse HTTP immédiatement (rediriger vers la page de détails avec un avis "régénération en arrière-plan"), puis continuez à générer les PDF en arrière-plan pour éviter les délais d'attente du frontend. Ajoutez une réécriture nginx pour la page (par exemple, rewrite ^/disputes/?$ /disputes.php). Assurez-vous qu'elle soit dans le bon fichier de configuration nginx (vérifiez vers quel fichier le lien symbolique dans sites-enabled pointe réellement). 6. Notifications Telegram - Nouveau litige : "{site name} - Nouveau litige de {email} pour ${amount} ({reason}). Preuves soumises automatiquement à Stripe. {stripe_dashboard_link}" - Échec des preuves : "{site name} - Nouveau litige de {email} pour ${amount} ({reason}). La soumission des preuves a ÉCHOUÉ : {error}" - Litige gagné/perdu avec le résultat et le lien - Erreur de permission de base de données : "{site name} - ERREUR BD LITIGES : {error} - vérifiez les permissions sur data/disputes.db" 7. Assurez-vous que ces événements de webhook Stripe soient activés dans le tableau de bord Stripe : charge.dispute.created, charge.dispute.updated, charge.dispute.closed 8. Permissions de la base de données Le fichier disputes.db doit être inscriptible par l'utilisateur du serveur web (par exemple, www-data). Si vous le créez depuis CLI en tant que root, corrigez la propriété pour correspondre à vos autres fichiers de base de données. PHP-FPM s'exécute en tant qu'utilisateur différent de root. 9. Dépendances - FPDF (setasign/fpdf) pour la génération de PDF, installé via composer require setasign/fpdf - Extension GD pour le redimensionnement d'images (généralement déjà installée) - SDK PHP Stripe (déjà installé si vous avez des webhooks Stripe) - SDK AWS S3 pour les téléversements R2/S3 (déjà installé si vous utilisez Cloudflare R2)