API Refundize : intégrer la défense dans votre stack technique

L'API Refundize supporte deux méthodes d'authentification. La méthode recommandée pour les intégrations serveur-à-serveur est la clé API, à passer dans le header X-API-Key de chaque requête. Vous générez votre clé dans le dashboard Refundize > Paramètres > API. La clé a une portée configurable : lecture seule (GET), lecture/écriture (GET/POST/PUT), ou admin (tous les endpoints + webhooks). Pour les applications tierces ou les intégrations multi-utilisateurs, utilisez OAuth 2.0 avec le flux authorization_code. Les tokens OAuth expirent après 1 heure ; utilisez le refresh_token (valable 30 jours) pour les renouveler automatiquement.

L'API Refundize s'organise autour de 5 ressources principales. /disputes : liste, création, mise à jour et suppression des litiges. GET /v1/disputes retourne les litiges avec filtres (plateforme, type, statut, période). POST /v1/disputes crée un litige manuellement. GET /v1/disputes/{id} récupère le détail. /defenses : génération et gestion des réponses. POST /v1/defenses/generate lance la génération IA d'une défense. GET /v1/defenses/{id} récupère la défense générée. /webhooks : gestion des endpoints de notification. /analytics : KPIs agrégés pour les tableaux de bord. /platforms : statut des connexions aux plateformes. Chaque endpoint retourne des réponses JSON avec un code HTTP standard (200, 201, 400, 401, 404, 429, 500).

Plutôt que de poller l'API toutes les 5 minutes, configurez des webhooks pour recevoir les événements en push. Les événements disponibles : dispute.created, dispute.updated, dispute.resolved, defense.generated, defense.sent, chargeback.detected, review.new_negative, platform.disconnected, health.threshold_warning. Chaque webhook envoie un POST à votre URL avec un payload JSON signé. La signature est un HMAC-SHA256 du payload avec votre webhook_secret, envoyé dans le header X-Refundize-Signature. Vérifiez toujours la signature côté serveur pour éviter les injections.

Deux exemples d'intégration complets. TypeScript (Node.js) : listez les litiges ouverts et générez une défense. Utilisez axios pour les requêtes HTTP et implémentez un retry avec backoff pour gérer le rate limiting. Python : même logique avec requests et tenacity pour le retry. Les deux exemples couvrent : authentification, récupération des litiges, filtrage par deadline (< 24h), génération de défense, gestion des erreurs, et pagination. Pour l'ERP de Lucas, ces exemples servent de base à un worker qui tourne toutes les 30 minutes, détecte les nouveaux litiges, génère les défenses, et les pousse dans l'interface support de l'ERP.

Pour une intégration de niveau production, suivez ces patterns éprouvés. Circuit breaker : si l'API Refundize est indisponible (erreurs 5xx consécutives), ouvrez le circuit et passez en mode dégradé (alerte manuelle à votre équipe). Cache : mettez en cache les réponses GET (litiges, analytics) avec un TTL de 5 minutes pour réduire les appels API. Idempotence : chaque requête POST/PUT inclut un header X-Idempotency-Key unique ; Refundize ignore les doublons. Queue de traitement : utilisez une file d'attente pour désynchroniser la détection et la réponse — le worker de détection alimente la queue, le worker de réponse consomme la queue. Ce pattern permet de scaler les deux processus indépendamment.