Question 1

Qu’est-ce que l’API Cathopic ?

Accepted Answer

Notre API est un service REST qui vous permet d’intégrer directement la bibliothèque de médias catholiques de Cathopic dans vos applications. Accédez par programmation à des milliers d’images, de vidéos et de graphismes. Ce que vous pouvez faire Rechercher et parcourir l’ensemble de notre catalogue Licencier des ressources pour vos utilisateurs finaux automatiquement Télécharger dans plusieurs formats optimisés pour différents cas d’usage Accéder à des métadonnées riches incluant des tags, des descriptions et des informations liturgiques Architecture REST Conçue selon des principes REST standard : URL de base : https://api.cathopic.com Format des données : requêtes et réponses JSON Authentification : clé API via l’en-tête x-api-key Méthode HTTP : POST pour tous les endpoints Quatre endpoints essentiels POST /resources - Rechercher dans le catalogue POST /resource - Obtenir les détails d’un élément spécifique POST /confirm - Licencier une ressource et obtenir des URL de téléchargement POST /remove - Arrêter la licence lorsque ce n’est plus nécessaire (site web uniquement) Documentation complète Tout ce dont vous avez besoin est disponible en ligne : Référence API interactive : api.cathopic.com/docs Exemples de code dans plusieurs langages Spécifications détaillées des paramètres Commencer Contactez notre équipe pour demander l’accès à l’API Générez votre clé API dans Paramètres → API Ajoutez un moyen de paiement pour la facturation d’utilisation Démarrez la construction Consultez les autres questions de cette section pour obtenir des détails sur l’authentification, la facturation et les bonnes pratiques. Contrat de licence de l’API Toute utilisation de l’API est soumise à notre Contrat de licence de l’API. Points clés à comprendre : Usage numérique uniquement : le contenu ne peut être affiché que dans des environnements web et e-mail Pas de téléchargement de fichiers : les utilisateurs finaux ne peuvent pas télécharger ni exporter les fichiers originaux Usages interdits : l’entraînement IA/ML, les supports imprimés et l’usage hors ligne sont strictement interdits Facturation selon l’usage : payez uniquement pour l’utilisation réelle du contenu par vos utilisateurs finaux En utilisant l’API, vous acceptez toutes les conditions du contrat de licence Avant d’intégrer l’API : Consultez l’intégralité du Contrat de licence de l’API Comprenez les restrictions et les obligations Assurez-vous que votre cas d’usage respecte les exigences « numérique uniquement » Planifiez votre intégration pour suivre l’usage avec précision afin de facturer Pour plus de détails, consultez : Que puis-je construire avec l’API ? (inclut des restrictions détaillées) Comment les licences fonctionnent-elles via l’API ? (détails complets sur la licence) Comment l’utilisation de l’API est-elle facturée ? (explication du modèle de facturation)

Question 2

Que puis-je créer avec l’API ?

Accepted Answer

L’API Cathopic vous permet d’intégrer directement du contenu visuel catholique dans votre application, votre site web ou votre plateforme. Toutefois, l’utilisation de l’API est strictement régie par notre contrat de licence d’API, qui limite l’usage à des environnements numériques spécifiques. Ce que vous pouvez créer Systèmes de gestion d’Église et de paroisse Permettre aux paroisses d’ajouter des images catholiques à leurs bulletins et newsletters Faciliter la promotion d’événements avec un contenu visuel pertinent Fournir des images liturgiques correspondant au calendrier de l’Église Créer des affichages numériques pour les annonces paroissiales Plateformes de contenu catholique Créer des plateformes de blog pour des auteurs catholiques avec des images intégrées Créer des sites d’actualités catholiques avec des visuels pertinents Développer des applications de dévotion avec des images et des prières quotidiennes Concevoir des plateformes de catéchèse avec des supports visuels d’enseignement Outils de marketing par e-mail Permettre aux services pastoraux de créer des newsletters avec des images catholiques Permettre aux organisations religieuses de concevoir des campagnes par e-mail Fournir des modèles avec du contenu Cathopic intégré Prendre en charge des campagnes de collecte de fonds avec des visuels appropriés Créateurs de sites web et CMS Intégrer des images catholiques dans des plateformes de création de sites web Fournir des modules de contenu pour les organisations catholiques Permettre la sélection d’images par glisser-déposer depuis Cathopic Créer des modèles spécifiquement pour les services catholiques Gestion d’événements et des réseaux sociaux Aider les services pastoraux à créer des visuels pour les réseaux sociaux (sans télécharger de fichiers) Concevoir des systèmes d’invitations d’événements avec des images catholiques Construire des calendriers de contenu avec des visuels de la saison liturgique Permettre aux organisations de planifier des publications avec des images appropriées Restrictions critiques à respecter La licence d’API interdit strictement certains usages. En cas de violation, la résiliation peut être immédiate : ❌ Entraînement IA/ML (INTERDIT DÉFINITIVEMENT) Ne peut pas être utilisé pour entraîner, affiner ou alimenter des modèles IA/ML Ne peut pas créer d’ensembles d’embeddings, de jeux de données ou d’extractions dérivées pour l’IA Cette restriction demeure indéfiniment, même après la résiliation de l’accord S’applique à toutes les formes d’apprentissage automatique et d’intelligence artificielle ❌ Téléchargements et exports de fichiers Les utilisateurs finaux ne peuvent pas télécharger ou enregistrer le contenu sous forme de fichiers Ne peut pas fournir de fonctionnalité « télécharger » ou « exporter » Le contenu doit rester hébergé par Cathopic ou dans un cache autorisé Seuls des URL optimisées pour le web peuvent être utilisées, et non des fichiers d’origine ❌ Impression et usage hors ligne Ne peut pas être utilisé dans des supports imprimés, brochures ou affiches Pas de publicité hors ligne ni de produits physiques Strictement limité aux environnements web et e-mail numériques Ne peut pas être incorporé dans des PDF destinés à l’impression ❌ Revente et redistribution Ne peut pas créer des produits qui revendent ou redistribuent le contenu Cathopic Ne peut pas créer de marketplaces de photos d’archives en utilisant notre API Ne peut pas proposer le contenu comme produit autonome Doit être intégré comme partie d’un service plus large ❌ Modification et œuvres dérivées Ne peut pas altérer, transformer ou créer des œuvres dérivées Ne peut pas appliquer des filtres ou des modifications significatives Doit afficher le contenu tel qu’il est fourni par l’API Le recadrage et le redimensionnement de base sont autorisés à des fins de mise en page Uniquement les environnements web et e-mail Le contenu consulté via l’API ne peut être utilisé que dans : Sites web : pages web publiques ou privées Applications web : outils et plateformes accessibles via un navigateur E-mail : newsletters, campagnes et e-mails transactionnels Blogs : systèmes de gestion de contenu en ligne Intégrations web : contenu contrôlé via iframe ou servi par l’API Important : le contenu doit être affiché uniquement avec une résolution optimisée pour le web. Les fichiers originaux en haute résolution ne sont jamais accessibles via l’API. Exigences techniques Votre application doit : Utiliser HTTPS : tous les appels à l’API et la diffusion du contenu doivent être sécurisés Mettre en œuvre la gestion des filigranes : commencez avec du contenu filigrané, et ne demandez du contenu non filigrané que lorsque c’est nécessaire Suivre l’utilisation avec précision : consignez toute utilisation du contenu à des fins de facturation Appeler l’endpoint /confirm : lorsque l’utilisateur final s’engage à utiliser le contenu Appeler l’endpoint /remove : lorsque le contenu n’est plus utilisé (arrêt de la facturation) Empêcher l’accès non autorisé : protégez vos identifiants d’API Respecter les limites de débit : suivez les limites définies pour votre compte Vos obligations légales Lorsque vous intégrez l’API, vous devez : Mettre à jour vos Conditions d’utilisation afin d’informer les utilisateurs finaux : Le contenu ne peut pas être téléchargé ni utilisé en dehors de votre application Le contenu ne peut pas être utilisé à des fins d’IA/ML Le contenu appartient à Cathopic et à ses créateurs L’utilisation est suivie pour la facturation et la conformité Mettre en œuvre des contrôles techniques pour empêcher : Les téléchargements par clic droit (lorsque c’est possible) L’accès direct aux URL des fichiers d’origine Les extensions de navigateur qui permettent les téléchargements Conserver des journaux d’utilisation pour : La vérification de la facturation Les audits de conformité Le règlement des litiges Exemples d’intégrations conformes ✅ Créateur de bulletins paroissiaux Les paroisses créent des bulletins numériques avec des images catholiques Le contenu s’affiche sur le site web et dans les newsletters par e-mail Aucune fonctionnalité de téléchargement n’est fournie La facturation suit l’utilisation par paroisse et par image ✅ Plateforme d’e-mail pour un service Les organisations religieuses conçoivent des campagnes par e-mail Les images sont servies directement dans les e-mails via des URL d’API Facturation par e-mail envoyé avec le contenu Aucun stockage de fichiers sur les appareils des utilisateurs finaux ✅ Plateforme CMS catholique Créateur de site web avec une bibliothèque Cathopic intégrée Les utilisateurs parcourent et sélectionnent des images pour leurs pages Le contenu est intégré via des URL servies par l’API Facturation par jour d’utilisation par utilisateur Exemples d’intégrations interdites ❌ Générateur d’images alimenté par l’IA Utiliser le contenu Cathopic pour entraîner des modèles d’IA Créer des jeux de données pour l’apprentissage automatique Générer des images similaires à partir de notre contenu ❌ Outil de conception pour l’impression Permettre aux utilisateurs de créer des affiches imprimables Fournir un téléchargement pour l’impression en haute résolution Créer des PDF avec du contenu Cathopic pour l’impression ❌ Marketplace de photos d’archives Revendre le contenu Cathopic comme produits autonomes Créer des collections dérivées de photos d’archives Redistribuer le contenu à plusieurs clients Avant de commencer à développer Lecture essentielle : Consultez l’accord de licence d’API dans son intégralité Étudiez la documentation technique sur api.cathopic.com/docs Comprenez en détail le modèle de facturation (voir Comment l’utilisation de l’API est-elle facturée ?) Planifiez votre intégration pour respecter toutes les restrictions Contactez-nous via support si vous avez des questions Rappel : en accédant à l’API ou en l’utilisant, vous acceptez toutes les conditions de l’accord de licence d’API. Le non-respect peut entraîner une résiliation immédiate et des conséquences juridiques.

Question 3

Quelles sont les limites de débit ?

Accepted Answer

À l’heure actuelle, nous n’appliquons pas de limites strictes de requêtes par seconde. Toutefois, une utilisation raisonnable est attendue afin de maintenir la qualité du service pour tout le monde. Approche actuelle Au lieu de limites strictes, nous encourageons une utilisation responsable : Espacer vos requêtes de manière raisonnable Mettre en place un backoff exponentiel en cas d’erreur Mettre en cache les réponses pour éviter les appels redondants Nous contacter si vous anticipez des volumes de trafic élevés Bonnes pratiques Mettre en cache de façon agressive : Conserver les résultats de recherche pour les requêtes courantes Garder les métadonnées des médias localement après récupération Ne pas appeler /confirm plusieurs fois pour le même utilisateur/ressource Regrouper vos opérations : Regrouper les requêtes liées Ajouter de petites pauses entre les lots Limiter le nombre de connexions simultanées (10 à 20 est raisonnable) Gérer les erreurs avec élégance : Mettre en place une logique de reprise avec backoff exponentiel Ne pas réessayer immédiatement en cas d’échec Consigner les erreurs pour le suivi Temps de réponse attendus Recherche /resources : généralement 200-500 ms Détails /resource : moins de 100 ms /confirm licensing : 300-800 ms Configurez le délai d’attente (timeout) de votre client sur au moins 30 secondes pour gérer occasionnellement des réponses plus lentes. Si vous atteignez des limites Vous recevrez une erreur 429 Too Many Requests. Lorsque cela se produit : // Implement exponential backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } return response; } catch (error) { if (i === maxRetries - 1) throw error; } } } Surveillez votre utilisation Suivez l’activité de l’API dans Paramètres → API : Voir le nombre total de requêtes effectuées Vérifier les licences actives Examiner les tendances d’utilisation Surveiller les schémas inhabituels Besoin de limites plus élevées ? Si votre utilisation légitime nécessite des volumes de requêtes élevés (> 1M requêtes/mois), contactez notre équipe pour discuter : Votre application et vos schémas de trafic Le volume de requêtes attendu Les limites de débit garanties si nécessaire

Question 4

Comment l’utilisation de l’API est-elle facturée ?

Accepted Answer

L’API Cathopic utilise un modèle de facturation « à l’usage » basé sur l’utilisation réelle du contenu par vos utilisateurs finaux. Toutes les conditions de facturation sont régies par notre Contrat de licence d’API. Deux modèles de facturation La facturation dépend de la manière dont vos utilisateurs finaux consomment le contenu : 1. Utilisation sur site (modèle « Jours d’utilisation ») S’applique lorsque le contenu est affiché sur des sites web, des blogs ou des applications web Calculée par jour civil pendant lequel un utilisateur final accède à un contenu spécifique Formule : Total des jours d’utilisation × (tarif mensuel négocié ÷ 30) La facturation au prorata quotidien garantit que vous ne payez que l’utilisation réelle Suivie séparément pour chaque utilisateur final et pour chaque élément de contenu 2. Utilisation par e-mail (modèle « Par e-mail ») S’applique lorsque le contenu est intégré dans des messages e-mail Facturée par message e-mail envoyé (et non par destinataire) Facturation unique par e-mail incluant le contenu Taux négocié lors de la mise en place de l’accès à l’API Quand la facturation commence et s’arrête Le contenu filigrané est gratuit Le contenu apparaît d’abord avec un filigrane Le prévisualisation filigranée ne génère pas de frais Idéal pour permettre aux utilisateurs finaux de parcourir avant de s’engager Peut être utilisé à des fins de test et d’essai La facturation commence lorsque le filigrane est retiré L’utilisateur final décide d’utiliser le contenu sans filigrane Votre application appelle POST /confirm avec : media_id : l’identifiant du contenu usage_type : « website » ou « email » client_identifier : l’identifiant unique de votre utilisateur final L’API renvoie des URL permanentes pour le contenu sans filigrane La facturation commence immédiatement à partir de ce moment Vous devez stocker ces URL et les données d’utilisation pour le suivi de la facturation La facturation s’arrête lorsque le contenu est retiré L’utilisateur final retire ou cesse d’utiliser le contenu Votre application appelle POST /remove avec : media_id : l’identifiant du contenu client_identifier : l’identifiant de l’utilisateur final La facturation pour cette utilisation spécifique s’arrête Vous devez supprimer les URL sans filigrane de votre base de données Exemple de facturation sur site Supposons que vous ayez négocié un tarif mensuel de pour une utilisation illimitée du contenu : Scénario : La paroisse A affiche l’image n°12345 sur sa page d’accueil Jour 1 : Vous appelez /confirm → la facturation commence Jours 1-15 : L’image reste sur la page d’accueil (15 jours d’utilisation) Jour 16 : La paroisse retire l’image, vous appelez /remove → la facturation s’arrête Calcul : 15 jours × ( ÷ 30 jours) = Facturé : pour cette utilisation spécifique Si la paroisse B utilise aussi la même image pendant 10 jours, cela est suivi séparément et s’ajoute. Exemple de facturation par e-mail Supposons que vous ayez négocié un tarif de --.05 par e-mail : Scénario : Un service envoie une newsletter avec l’image n°67890 Action : Vous appelez /confirm avec usage_type: "email" Résultat : Un prélèvement unique de --.05 pour cet e-mail Destinataires : Peu importe si l’e-mail est envoyé à 100 ou à 10 000 personnes Facturé : --.05 au total (et non par destinataire) Plafonds mensuels de facturation Votre accord peut inclure des plafonds mensuels de facturation : Vous protège contre des factures imprévues Une fois le plafond atteint, l’utilisation supplémentaire peut être gratuite ou facturée à un tarif réduit Le montant spécifique du plafond est négocié lors de la mise en place de l’accès à l’API S’applique au total des charges mensuelles pour l’ensemble des utilisateurs finaux Facturation et paiement Calendrier des factures Les factures sont émises mensuellement au cours des 10 premiers jours de chaque mois Couvre toute l’utilisation du mois précédent Détail de l’utilisation par utilisateur final et par élément de contenu Envoyé à l’adresse e-mail associée à votre compte API Traitement des paiements Paiements traités exclusivement via Stripe Prélèvement automatique sur votre moyen de paiement enregistré Vous devez conserver à tout moment des informations de paiement valides Reçus fournis automatiquement après un paiement réussi Échecs de paiement En cas d’échec du paiement, le système effectue 4 tentatives de relance Vous recevez des notifications par e-mail en cas de problème de paiement Si toutes les relances échouent, l’accès à l’API est suspendu L’accès est rétabli immédiatement après un paiement réussi Les factures impayées peuvent entraîner des frais d’intérêt Vos responsabilités de suivi Vous devez conserver des enregistrements exacts de : Journaux d’utilisation : quand le contenu a été confirmé et retiré Identifiants des utilisateurs finaux : quels utilisateurs ont accédé à quel contenu Identifiants de contenu : quels éléments multimédias ont été utilisés Types d’utilisation : site web vs e-mail pour chaque utilisation Dates : date de début et date de fin pour l’utilisation sur site URL : URL sans filigrane stockées pour l’utilisation active Ces journaux sont essentiels pour : Vérifier les factures mensuelles Résoudre les litiges de facturation Les audits de conformité par Cathopic Votre propre reporting interne Accéder aux rapports d’utilisation Vous pouvez suivre votre utilisation de l’API en temps réel : Allez dans Paramètres → API Consultez la section « Utilisation à la demande » Voir les statistiques de la période de facturation en cours : Coût total accumulé jusqu’à présent Nombre d’utilisations sur site Nombre d’utilisations par e-mail Cliquez sur « Voir le rapport détaillé » pour un détail par : Utilisateur final (identifiant client) Élément de contenu Type d’utilisation Période Coûts individuels Exportez les rapports au format CSV pour vos dossiers Négocier les tarifs La tarification de l’API est personnalisée pour chaque client : Les tarifs sont négociés pendant le processus de demande d’accès à l’API En fonction du volume d’utilisation attendu En fonction de votre cas d’usage spécifique et du type d’intégration Peut inclure des remises sur volume pour les applications à forte utilisation Des plafonds de facturation peuvent être négociés pour fournir des coûts prévisibles Pour discuter des tarifs : Visitez notre page d’assistance Sélectionnez « Demande d’accès à l’API » Décrivez votre intégration et l’utilisation prévue Notre équipe fournira un devis personnalisé Comprendre l’intégralité de la licence La facturation n’est qu’un aspect du contrat d’API. Consultez l’ensemble des conditions : Lisez l’intégralité du Contrat de licence d’API Comprenez les restrictions d’utilisation (numérique uniquement, pas d’IA/ML, pas de téléchargements) Connaissez vos obligations en matière de suivi et de reporting Vérifiez les clauses relatives à la propriété intellectuelle et à la résiliation Pour les détails techniques de mise en œuvre : Consultez les endpoints /confirm et /remove sur api.cathopic.com/docs Comprenez comment calculer l’utilisation pour votre intégration spécifique Consultez les bonnes pratiques pour un suivi de facturation exact À retenir : Le suivi exact de l’utilisation est de votre responsabilité. Conservez des journaux détaillés pour garantir une facturation correcte et la conformité au contrat de licence.

Question 5

Comment demander l’accès développeur pour l’API et OAuth

Accepted Answer

Cathopic examine un compte développeur une seule fois. Cette approbation unique débloque à la fois l’API commerciale et la gestion des applications OAuth ; vous ne soumettez pas de demandes séparées. Après approbation, vous créez et gérez vos clés API et vos identifiants OAuth depuis les Paramètres de Cathopic. Les développeurs n’ont jamais besoin d’une commande de serveur Cathopic ni d’un accès à l’infrastructure. 1. Préparez votre compte Cathopic Créez un compte Cathopic, vérifiez son adresse e-mail et assurez-vous que le nom d’utilisateur et l’e-mail indiqués dans la demande correspondent exactement à ce compte. 2. Envoyer la demande développeur Ouvrez le formulaire de contact Cathopic. Choisissez Demander l’accès développeur. Confirmez le nom d’utilisateur Cathopic et décrivez le produit, l’organisation et l’usage prévu du catalogue. Envoyez le formulaire. La demande apparaît dans le tableau de bord interne de révision de Cathopic. 3. Recevoir la décision Cathopic examine le compte et le cas d’usage. Une fois approuvé, le développeur reçoit un e-mail avec les prochaines étapes et un lien vers Paramètres → Développeur / API → Applications OAuth. Si des informations supplémentaires sont nécessaires, Cathopic contacte l’e-mail indiqué dans la demande. 4. Créer l’application Choisissez une application web confidentielle lorsque le produit dispose d’un backend sécurisé, ou une application publique PKCE pour des clients uniquement navigateur, mobile ou bureau. Saisissez son nom public, sa description, son site web, sa politique de confidentialité, le contact sécurité, les URL de rappel exactes, et uniquement les portées dont elle a besoin. 5. Stocker les identifiants L’ID client identifie l’intégration et est partagé par tous les utilisateurs de ce produit. L’autorisation utilisateur et les jetons restent distincts pour chaque compte Cathopic. Un secret client confidentiel n’est affiché qu’une seule fois et doit être chiffré sur le serveur de l’application. Ne l’incluez jamais dans du code de navigateur, des sites web générés, des journaux, des messages d’assistance ou un dépôt public. La même page permet au développeur approuvé de modifier les rappels et les portées, de faire tourner un secret confidentiel ou de révoquer l’application.

Question 6

Comment fonctionnent les clés API ?

Accepted Answer

Les clés API sont vos identifiants d’authentification pour accéder à l’API Cathopic. Comprendre leur fonctionnement est essentiel pour une intégration API sécurisée et efficace. Qu’est-ce qu’une clé API ? Une clé API est un jeton secret unique qui identifie votre application et l’autorise à accéder à l’API Cathopic : Une longue chaîne alphanumérique (par ex. sk_live_abc123xyz789...) Agit à la fois comme authentification et autorisation Liée à votre compte Cathopic et à la facturation Peut être active ou inactive Cycle de vie de la clé Création : Générez des clés dans Paramètres → API Donnez à chaque clé un nom descriptif (« Site Web de production », « Environnement de préproduction », « Application mobile ») Copiez la clé complète immédiatement : elle n’est affichée qu’une seule fois Conservez-la en lieu sûr (variables d’environnement, gestionnaire de secrets, gestionnaire de mots de passe) Utilisation : Incluez-la dans l’en-tête HTTP x-api-key avec chaque requête Les clés sont validées côté serveur à chaque requête Toute l’utilisation de l’API est suivie et facturée à votre compte Désactivation : Les clés peuvent être temporairement désactivées sans suppression Utile pour le dépannage ou pour mettre en pause une intégration spécifique Peut être réactivée à tout moment Suppression : Supprime définitivement la clé Ne peut pas être annulée ni récupérée Toutes les requêtes avec cette clé échoueront immédiatement Recommandations pour la gestion des clés Sécurité : Ne jamais commiter les clés dans le contrôle de version : utilisez des fichiers .env et ajoutez-les à .gitignore Ne jamais exposer dans du code côté client : les clés API doivent uniquement être utilisées côté serveur Utilisez des variables d’environnement : stockez les clés dans process.env.CATHOPIC_API_KEY ou équivalent Faites une rotation régulièrement : changez périodiquement les clés (tous les trimestres ou après des changements au sein de l’équipe) Utilisez des clés séparées par environnement : des clés différentes pour le développement, la préproduction et la production Organisation : Noms descriptifs : nommez les clés selon leur usage : « Site Web de production », « Application iOS », « Système d’e-mails » Documentez la propriété : suivez quel membre de l’équipe a créé chaque clé Audits réguliers : examinez les clés actives chaque mois et supprimez celles qui ne sont pas utilisées Plusieurs clés API Vous pouvez créer plusieurs clés API pour des usages différents : Par environnement : clés distinctes pour le développement, la préproduction et la production Par application : clés différentes pour le site web, l’application mobile, les outils internes Par membre de l’équipe : clés individuelles pour les développeurs (plus facile à suivre et à révoquer) Toutes les clés sous votre compte partagent la même facturation. L’utilisation de toutes les clés est regroupée dans votre facture mensuelle. Suivi de l’utilisation des clés Suivez l’activité pour chaque clé : Allez dans Paramètres → API Affichez la liste de toutes les clés avec les dates de dernière utilisation Cliquez sur une clé pour voir des statistiques d’utilisation détaillées Surveillez toute activité inattendue Que faire si une clé est compromise Si vous pensez qu’une clé API a été exposée : Supprimez-la ou désactivez-la immédiatement dans Paramètres → API Générez une nouvelle clé de remplacement Mettez à jour votre application avec la nouvelle clé Vérifiez les journaux d’utilisation pour toute activité suspecte Contactez le support si vous constatez une utilisation non autorisée Exemple : stocker les clés en toute sécurité Node.js avec des variables d’environnement : // Fichier .env (à ajouter à .gitignore !) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Votre code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }) }); Python avec des variables d’environnement : import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'} )

Question 7

Comment authentifier les requêtes ?

Accepted Answer

Toutes les requêtes adressées à l’API Cathopic doivent être authentifiées à l’aide de votre clé API. Voici comment authentifier correctement vos appels API. Méthode d’authentification L’API Cathopic utilise une authentification par clé API via des en-têtes HTTP : Nom de l’en-tête : x-api-key Valeur de l’en-tête : Votre clé API complète Requis pour : Tous les endpoints de l’API Sensible à la casse : Les noms et valeurs des en-têtes doivent correspondre exactement Exemple d’authentification de base cURL : curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Virgin Mary", "page": 1, "page_size": 20, "order": "popular" }' JavaScript (fetch) : const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': process.env.CATHOPIC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }) }); const data = await response.json(); console.log(data); JavaScript (axios) : const axios = require('axios'); const response = await axios.post( 'https://api.cathopic.com/resources', { query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }, { headers: { 'x-api-key': process.env.CATHOPIC_API_KEY } } ); console.log(response.data); Python (requests) : import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={ 'x-api-key': api_key, 'Content-Type': 'application/json' }, json={ 'query': 'Virgin Mary', 'page': 1, 'page_size': 20, 'order': 'popular' } ) data = response.json() print(data) PHP (cURL) : <?php $apiKey = getenv('CATHOPIC_API_KEY'); $ch = curl_init('https://api.cathopic.com/resources'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'x-api-key: ' . $apiKey, 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'query' => 'Virgin Mary', 'page' => 1, 'page_size' => 20, 'order' => 'popular' ])); $response = curl_exec($ch); $data = json_decode($response, true); curl_close($ch); print_r($data); ?> Erreurs d’authentification Si l’authentification échoue, vous recevrez une réponse d’erreur : Clé API manquante : HTTP 401 Unauthorized { "message": "Unauthorized" } Clé API invalide : HTTP 401 Unauthorized { "message": "Unauthorized" } Clé API inactive : HTTP 401 Unauthorized { "error": "Unauthorized token" } Rappels importants Sécurité : Ne jamais coder en dur les clés API : Utilisez des variables d’environnement ou une configuration sécurisée Côté serveur uniquement : Ne mettez jamais les clés API dans du JavaScript côté client Utilisez uniquement HTTPS : Les clés API transmises via HTTP sont vulnérables Faites tourner régulièrement les clés : Changez les clés périodiquement pour la sécurité Gestion des erreurs : Vérifiez les codes de statut : Contrôlez toujours le statut de la réponse HTTP Journalisez les échecs d’authentification : Suivez les tentatives échouées pour le suivi de la sécurité Implémentez une logique de relance : Avec un backoff exponentiel pour les erreurs transitoires Validez avant l’envoi : Assurez-vous que la clé API est chargée correctement Tester l’authentification Test rapide pour vérifier que votre clé API fonctionne : curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test", "page": 1, "page_size": 1}' Réponse attendue (succès) : { "total": 1234, "page": 1, "page_size": 1, "results": [ ... ] } Erreurs courantes Mauvais nom d’en-tête : Doit être x-api-key, et non api-key ou Authorization Format de valeur incorrect : Utilisez la clé complète telle quelle, sans préfixe « Bearer » Espace en trop : Supprimez les espaces en fin de valeur de la clé API avant de l’utiliser Clé non chargée : Vérifiez que la variable d’environnement est correctement définie Pour résoudre les problèmes d’authentification, consultez « Common authentication errors » dans cette section.

Question 8

Comment faire pivoter une clé API ?

Accepted Answer

Faire pivoter régulièrement les clés API est une pratique de sécurité importante. Voici comment faire pivoter vos clés en toute sécurité sans perturber votre service. Pourquoi faire pivoter les clés API ? Bonne pratique de sécurité : Limite l’exposition si une clé est compromise Changements au sein de l’équipe : Lorsque des développeurs quittent l’équipe ou changent de rôle Compromission suspectée : Si vous pensez qu’une clé a pu être exposée Conformité : Certaines politiques de sécurité exigent une rotation périodique des clés Changements d’environnement : Lors de la migration de l’infrastructure ou d’un refactoring Processus standard de rotation (sans interruption) Étape 1 : Créer une nouvelle clé Connectez-vous à Paramètres → API Cliquez sur "Créer une nouvelle clé API" Donnez-lui un nom descriptif (par ex. « Production Web v2 ») Copiez immédiatement la nouvelle clé : elle n’est affichée qu’une seule fois Conservez-la en lieu sûr Étape 2 : Mettre à jour votre application Déployez la nouvelle clé dans votre application (variables d’environnement, gestionnaire de secrets, etc.) Redémarrez votre application pour charger la nouvelle clé Vérifiez que la nouvelle clé fonctionne correctement Surveillez les éventuelles erreurs Étape 3 : Surveiller la transition Conservez temporairement les deux clés actives Consultez Paramètres → API pour voir les dates « Dernière utilisation » Attendez que l’ancienne clé n’affiche plus d’activité récente Assurez-vous que toutes les instances/services ont basculé vers la nouvelle clé Étape 4 : Supprimer l’ancienne clé Une fois confirmé que l’ancienne clé n’est plus utilisée Supprimez ou désactivez l’ancienne clé dans Paramètres → API Documentez la rotation pour vos archives Processus rapide de rotation (en cas de compromission) Si une clé est définitivement compromise et que vous devez agir immédiatement : Supprimez d’abord la clé compromise dans Paramètres → API Créez une nouvelle clé de remplacement Déployez rapidement la nouvelle clé dans toutes les applications Acceptez une brève interruption pour empêcher tout accès non autorisé Surveillez les journaux d’utilisation pour toute activité suspecte Contactez le support si nécessaire Stratégie de rotation multi-environnements Pour les systèmes de production, utilisez une approche progressive : Semaine 1 : Développement Créez et déployez la nouvelle clé dans l’environnement de développement Testez soigneusement Semaine 2 : Préproduction Déployez la nouvelle clé dans la préproduction Lancez les tests d’intégration Surveillez les problèmes Semaine 3 : Production Déployez la nouvelle clé en production pendant une période de faible trafic Surveillez de près Conservez l’ancienne clé active pendant 24 à 48 heures en solution de repli Semaine 4 : Nettoyage Vérifiez que l’ancienne clé n’affiche aucune activité Supprimez l’ancienne clé Mettez à jour la documentation Exemple d’automatisation Script pour aider à vérifier que la rotation de clé est terminée : #!/bin/bash # check-api-key.sh OLD_KEY="sk_live_OLD123..." NEW_KEY="sk_live_NEW789..." echo "Testing old key..." OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $OLD_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Testing new key..." NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $NEW_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Old key status: ${OLD_RESPONSE: -3}" echo "New key status: ${NEW_RESPONSE: -3}" if [ "${NEW_RESPONSE: -3}" == "200" ]; then echo "✅ New key is working!" else echo "❌ New key failed!" fi Bonnes pratiques Faire pivoter régulièrement : Tous les 90 jours pour les clés de production Documenter les rotations : Conservez un historique indiquant quand les clés ont été pivotées et pourquoi Tester avant de supprimer : Vérifiez toujours que la nouvelle clé fonctionne avant de retirer l’ancienne Utiliser plusieurs clés : Séparer les clés par environnement facilite la rotation Automatiser lorsque possible : Utilisez des outils de gestion des secrets qui prennent en charge la rotation automatique Checklist après rotation Confirmez ces éléments après la rotation : ✅ Toutes les instances de production utilisent la nouvelle clé ✅ Tous les environnements de préproduction/développement ont été mis à jour (si vous utilisez la même clé) ✅ Variables d’environnement mises à jour ✅ Secrets CI/CD mis à jour ✅ Documentation mise à jour ✅ Membres de l’équipe informés ✅ Ancienne clé supprimée ✅ Rotation consignée à des fins d’audit

Question 9

Comment sécuriser mes identifiants ?

Accepted Answer

Les clés API sont la passerelle vers votre compte Cathopic. Les garder en sécurité permet d’éviter tout accès non autorisé et de se protéger contre la fraude liée à la facturation. La règle d’or : gardez les clés secrètes Traitez vos clés API comme des mots de passe. Erreurs courantes à éviter : Intégrer les clés directement dans le code source Les commiter dans Git ou tout autre système de contrôle de version Utiliser les clés dans du JavaScript côté client ou dans des applications mobiles Partager les clés par e-mail, Slack ou des applications de messagerie Stocker les clés dans des emplacements publics (dépôts publics, wikis, etc.) Utilisez des variables d’environnement Stockez les clés dans des variables d’environnement plutôt que dans le code : // Fichier .env (à ajouter à .gitignore !) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Votre code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Cela sépare les données sensibles de votre base de code et facilite la rotation des clés. Côté serveur uniquement Les appels API doivent être effectués depuis vos serveurs backend, et non depuis des navigateurs ou des applications mobiles. Si les utilisateurs ont besoin d’accéder à des ressources Cathopic : Créez un point de terminaison (endpoint) backend qui utilise votre clé API Votre front-end appelle VOTRE endpoint, et non Cathopic directement Votre serveur valide la demande de l’utilisateur avant d’appeler Cathopic Restreindre par IP (si possible) Certains environnements permettent la mise en liste blanche des IP. Si vos appels API proviennent d’IP connues : Configurez des règles de pare-feu pour limiter l’accès sortant Utilisez des comptes de service dédiés avec des permissions minimales Surveillez les journaux d’accès pour détecter toute activité inhabituelle Si une clé est compromise Si vous pensez qu’une clé a été exposée : Générez immédiatement une nouvelle clé API Mettez à jour votre application avec la nouvelle clé Supprimez la clé compromise Vérifiez les journaux d’utilisation pour toute activité suspecte Contactez le support si vous constatez des frais non autorisés Gérez vos clés en toute sécurité dans Paramètres → API.

Question 10

Erreurs d’authentification courantes

Accepted Answer

Si vous rencontrez des difficultés pour vous authentifier auprès de l’API Cathopic, voici les erreurs les plus courantes et comment les corriger. 401 Unauthorized L’erreur d’authentification la plus courante : HTTP 401 Unauthorized { "message": "Unauthorized" } Causes fréquentes : En-tête x-api-key manquant Clé API invalide ou expirée Erreur de frappe dans la clé API Espace avant/après la clé Clé non chargée depuis une variable d’environnement Comment corriger : Vérifiez que le nom de l’en-tête est exactement x-api-key (en minuscules) Copiez à nouveau votre clé API depuis Paramètres → API Vérifiez que les variables d’environnement sont chargées : console.log(process.env.CATHOPIC_API_KEY) Supprimez les espaces : apiKey.trim() Vérifiez que la clé est active (non supprimée ou désactivée) Mauvais nom d’en-tête L’API exige x-api-key, et non d’autres noms d’en-tête courants : // ❌ FAUX Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRECT x-api-key: sk_live_abc... Erreur de jeton non autorisé HTTP 401 Unauthorized { "error": "Unauthorized token" } Cause : Votre clé API a été désactivée ou supprimée. Comment corriger : Vérifiez si la clé est toujours active dans Paramètres → API Réactivez la clé si elle a été désactivée Générez une nouvelle clé si l’ancienne a été supprimée Variable d’environnement non chargée Votre code ne trouve pas la clé API : // Renvoie undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Comment corriger : Node.js : // Assurez-vous que .env est chargé require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; if (!apiKey) { throw new Error('CATHOPIC_API_KEY not set'); } Python : import os from dotenv import load_dotenv load_dotenv() api_key = os.environ.get('CATHOPIC_API_KEY') if not api_key: raise ValueError('CATHOPIC_API_KEY not set') Erreur d’exposition côté client Vous essayez d’utiliser la clé API dans du JavaScript exécuté dans le navigateur : // ❌ Cela échouera (les clés ne fonctionnent pas dans les navigateurs) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Comment corriger : Créez un point d’accès côté serveur qui fait office de proxy pour les requêtes vers l’API Cathopic. Consultez « Comment sécuriser mes identifiants ? » pour des exemples. Erreurs CORS Si vous voyez des erreurs CORS dans la console du navigateur : Access to fetch has been blocked by CORS policy... Cause : Vous essayez d’appeler l’API directement depuis du JavaScript côté client. Comment corriger : L’API Cathopic est uniquement côté serveur. Vous devez faire passer les requêtes via votre propre backend. Tester l’authentification Test rapide pour vérifier votre configuration : curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: VOTRE_CLE" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Recherchez une réponse HTTP 200 # Si 401, vérifiez soigneusement la clé Checklist de débogage Si l’authentification échoue encore : ☐ Le nom de l’en-tête est x-api-key (sensible à la casse) ☐ La clé API est la clé complète (commence par sk_live_ ou similaire) ☐ Pas de préfixe Bearer ni de guillemets autour de la clé ☐ La variable d’environnement est définie et chargée ☐ La requête est envoyée depuis le serveur, pas depuis le navigateur ☐ La clé est active dans Paramètres → API ☐ Le moyen de paiement est ajouté et valide Si les problèmes persistent, contactez l’assistance développeurs avec : Le message d’erreur Les 4 derniers chiffres de votre clé API Le langage de programmation et le framework Un exemple de code (sans exposer votre clé complète)

Question 11

Paramètres de recherche disponibles

Accepted Answer

L’endpoint /resources accepte plusieurs paramètres pour affiner vos résultats de recherche. Recherche de base POST https://api.cathopic.com/resources { "query": "Saint Francis", "page": 1, "page_size": 20, "order": "popular" } Paramètres query (string, optionnel) Votre terme de recherche. Laissez vide pour obtenir toutes les ressources. Exemples : "Virgin Mary", "Eucharist", "cross" Prend en charge la correspondance approximative et la tolérance aux fautes de frappe Recherche dans les titres, les descriptions et les tags page (entier, par défaut : 1) La page de résultats à renvoyer. Commence à 1. page_size (entier, par défaut : 20, max : 100) Nombre de résultats par page. Le maximum est 100 pour maintenir les performances. order (string, par défaut : "popular") Comment trier les résultats : popular - Les ressources les plus téléchargées d’abord recent - Les téléversements les plus récents d’abord Structure de la réponse { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Resource title", "description": "Resource description", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Exemples pratiques Obtenir les 10 ressources les plus populaires sur la prière : { "query": "prayer", "page": 1, "page_size": 10, "order": "popular" } Obtenir les téléversements récents, sans terme de recherche spécifique : { "query": "", "page": 1, "page_size": 50, "order": "recent" } Parcourir la page 3 d’images de saints : { "query": "saints", "page": 3, "page_size": 20, "order": "popular" } Pour consulter la référence complète de l’API, visitez api.cathopic.com/docs.

Question 12

Comment télécharger des images via l’API ?

Accepted Answer

Clarification importante : L’API ne permet pas de « télécharger » au sens traditionnel. À la place, elle fournit des URL permanentes vers du contenu optimisé pour le web que votre application sert aux utilisateurs finaux. Cela est régi par notre Contrat de licence de l’API. Vous NE téléchargez PAS de fichiers L’API Cathopic fonctionne fondamentalement différemment des téléchargements traditionnels : Aucun transfert de fichier : vous ne recevez ni ne stockez jamais les fichiers image/vidéo réels Accès par URL : l’API fournit des URL qui pointent vers du contenu hébergé par Cathopic Optimisé pour le web uniquement : le contenu est servi dans une résolution adaptée à l’affichage numérique Pas de fichiers originaux : les originaux haute résolution ne sont jamais accessibles via l’API Toujours hébergé : le contenu reste sur les serveurs de Cathopic ou sur un CDN autorisé Résolutions disponibles L’API fournit trois tailles optimisées pour le web : Petite : adaptée aux vignettes et aux petites intégrations (typiquement ~400 px de large) Moyenne : adaptée au contenu web standard (typiquement ~800 px de large) Grande : meilleure qualité pour l’affichage web (typiquement ~1200 px de large) Restrictions critiques : Les fichiers originaux haute résolution ne sont JAMAIS fournis Les résolutions sont optimisées pour l’écran, pas pour l’impression Les tailles de fichiers sont compressées pour une livraison web rapide Vous ne pouvez pas demander des résolutions personnalisées ni la qualité originale Pour connaître l’ensemble des conditions, lisez le Contrat de licence de l’API et consultez la documentation technique à api.cathopic.com/docs. Le « téléchargement » d’images implique deux étapes : licencier la ressource avec /confirm, puis utiliser les URL renvoyées. Étape 1 : licencier la ressource Appelez /confirm pour licencier une ressource pour un utilisateur final spécifique : POST https://api.cathopic.com/confirm x-api-key: VOTRE_CLE_API { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Paramètres : media_id - L’identifiant de la ressource provenant de vos résultats de recherche usage_type - Soit « website » soit « email » client_identifier - Identifiant unique pour votre utilisateur final Étape 2 : utiliser les URL de téléchargement La réponse contient des URL permanentes dans plusieurs formats : { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Important : stocker les URL Les URL renvoyées sont permanentes : stockez-les dans votre base de données : // Après avoir appelé /confirm const response = await api.confirm(mediaId, userId); // Stocker dans votre base de données await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // La prochaine fois, récupérez depuis la base de données au lieu d’appeler /confirm à nouveau Choisir le bon format Format AVIF : Taille de fichier plus petite (meilleures performances) Meilleure compression Recommandé pour les navigateurs modernes Non pris en charge dans les navigateurs plus anciens Format JPEG : Compatibilité universelle Taille de fichier plus grande À utiliser comme solution de repli pour les navigateurs plus anciens Rappel critique ⚠️ Vérifiez toujours votre base de données avant d’appeler /confirm. L’appeler plusieurs fois pour le même utilisateur et la même ressource créera des frais en double. Documentation complète à api.cathopic.com/docs.

Question 13

Gérer la pagination et le tri

Accepted Answer

L’API renvoie les résultats de recherche par pages. Voici comment naviguer efficacement dans de grands ensembles de résultats. Pagination de base POST /resources { "query": "saints", "page": 1, "page_size": 20 } Réponse: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 items ... ] } La réponse indique qu’il y a 1 523 résultats au total et que vous consultez la page 1 avec 20 éléments. Calculer le nombre total de pages const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 pages Charger la page suivante // Page suivante simple currentPage++; // Ou construire l’interface de pagination for (let page = 1; page <= totalPages; page++) { // Créer le bouton de page } Optimiser la taille des pages Choisissez la taille des pages selon votre cas d’usage : Petites pages (10-20 éléments) : Chargement initial plus rapide Adapté à une recherche côté utilisateur Nécessite davantage de requêtes API Grandes pages (50-100 éléments) : Moins de requêtes API Adapté au traitement par lots Requêtes individuelles plus lentes Le maximum est de 100 éléments Options de tri Populaire (par défaut) : { "order": "popular" } Renvoie d’abord les ressources les plus téléchargées. Idéal pour afficher du contenu de qualité, éprouvé. Récent : { "order": "recent" } Renvoie d’abord les téléchargements les plus récents. Pratique pour découvrir du contenu nouveau. Exemple de défilement infini let currentPage = 1; const pageSize = 20; let isLoading = false; let hasMore = true; async function loadMore() { if (isLoading || !hasMore) return; isLoading = true; const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'prayer', page: currentPage, page_size: pageSize, order: 'popular' }) }); const data = await response.json(); // Ajouter les résultats à votre interface appendResults(data.results); // Vérifier s’il y a d’autres pages const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Déclencher au défilement window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Conseils de performance Mettre en cache les résultats localement pour éviter des requêtes redondantes Utiliser des tailles de pages adaptées à votre cas d’usage Implémenter des états de chargement pour une meilleure expérience utilisateur Envisager la virtualisation pour des listes très longues Ne pas charger toutes les pages d’un coup : charger à la demande Pour plus de détails, consultez la documentation complète à api.cathopic.com/docs.

Question 14

Comment rechercher dans le catalogue et utiliser les URL d’aperçu Cathopic

Accepted Answer

Utilisez GET /api/v2/catalog avec catalog.read. Il utilise la couche de recherche floue tolérante aux fautes de frappe existante de Cathopic et charge les mêmes modèles médiatiques canoniques utilisés par la grille du site web. Paramètres q ou query: texte jusqu’à 250 caractères. type: photo, vidéo, graphique, œuvre, ai, ou tout. orientation: paysage, portrait, carré, ou tout. sort: most_recent, popular, ou popular_alltime. page, per_page : jusqu’à 50, et locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUtilisez les URL d’aperçu inchangées Chaque résultat inclut preview.url et preview.transformation_url_template. Ils proviennent exactement du même présentateur de grille, de l’hôte CDN, du chemin de stockage et des règles de filigrane utilisés sur cathopic.com. Utilisez-les inchangés afin que les intégrations réutilisent les clés de cache existantes de Cloudflare. Ne téléversez pas une autre copie et ne le mettez pas en proxy inutilement. N’ajoutez pas de paramètres de requête destinés à contourner le cache. Remplacez <OPTIONS> uniquement par des options d’image Cloudflare stables. Les aperçus ne consomment jamais un téléchargement. already_licensed inclut les droits individuels et ceux de l’équipe partagée.

Question 15

Comment obtenir une licence et télécharger une ressource en toute sécurité

Accepted Answer

La création de la licence et la création de l’URL d’origine sont séparées, de sorte que les nouvelles tentatives sont sûres et que les URL fraîches ne sont jamais facturées à nouveau. 1. Créer la licence POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Utilisez une clé unique de 8 à 160 caractères ASCII imprimables pour la tentative de sélection logique, et conservez-la lors des nouvelles tentatives. Une nouvelle licence renvoie 201 ; une relecture idempotente renvoie 200 avec le même ID de licence. Cathopic vérifie d’abord l’original. En une seule transaction, il verrouille l’abonnement individuel ou d’équipe, vérifie l’accès au média et les droits partagés existants, consomme au plus un téléchargement, et enregistre le droit, l’historique et la licence. 2. Demander l’URL d’origine POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENL’URL expire au bout de cinq minutes. Demandez une nouvelle URL pour un re-téléchargement ; ne créez pas une autre licence. Cathopic déduit le chemin de stockage et n’accepte jamais un chemin arbitraire. Erreurs importantes subscription_required: aucun accès payant actif. media_type_not_in_plan: type non inclus. download_balance_exhausted: il ne reste plus de téléchargements avec formule limitée. file_unavailable: original introuvable ; aucun frais. idempotency_key_conflict: la clé a été utilisée pour un autre ID de média. Conservez le X-Request-Id pour le support, mais ne consignez jamais de jetons, de secrets ou d’URL signées. Faites une pause avec un jitter après les réponses 429 ou les erreurs transitoires 5xx.

Question 16

Démarrage rapide OAuth 2.0 pour les applications connectées Cathopic

Accepted Answer

Les applications connectées Cathopic utilisent le flux OAuth 2.0 Authorization Code avec un PKCE S256 obligatoire. La même validation du développeur débloque également l’API commerciale de Cathopic, mais les connexions OAuth utilisent des jetons utilisateur et le plan de l’utilisateur connecté, plutôt que des clés d’API et une facturation API à l’usage. 1. Obtenir l’accès et enregistrer l’application Soumettez la demande unique d’accès développeur via le formulaire de contact. Après que Cathopic a approuvé le compte par e-mail, ouvrez Paramètres → Développeur / API → Applications OAuth, créez l’application, enregistrez ses rappels (callbacks) exacts et les scopes requis, et stockez son secret à usage unique s’il est confidentiel. 2. Découvrir le serveur d’autorisation GET https://cathopic.com/.well-known/oauth-authorization-server3. Rediriger l’utilisateur GET https://cathopic.com/oauth/authorize ?client_id=CLIENT_ID &redirect_uri=EXACT_CALLBACK &response_type=code &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read &state=UNGUESSABLE_STATE &code_challenge=BASE64URL_SHA256_VERIFIER &code_challenge_method=S256 &ui_locales=enConstruisez une seule URL ; les retours à la ligne ne servent qu’à rendre l’exemple lisible. Générez de nouvelles valeurs de state à haute entropie et de PKCE pour chaque tentative. ui_locales est optionnel et peut demander une langue prise en charge telle que en ou es. Si une connexion est requise, Cathopic reprend la même demande d’autorisation, puis affiche l’écran d’autorisation. 4. Valider le callback et échanger le code Comparez le state renvoyé avant d’échanger le code. L’URI de redirection doit correspondre octet pour octet. POST https://cathopic.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIERLes applications publiques omettent client_secret. Stockez les jetons et les secrets confidentiels uniquement sur le serveur et chiffrez-les au repos. Les jetons d’accès durent 30 minutes ; les jetons d’actualisation durent jusqu’à 30 jours et sont renouvelés (rotated) lorsqu’ils sont utilisés. Contrôles courants Un callback rejeté diffère généralement de l’URI enregistrée par le schéma, l’hôte, le port, le chemin, la casse, ou la barre oblique finale. invalid_request avant consentement signifie que PKCE S256, le challenge ou le state est manquant ou invalide. invalid_grant signifie généralement qu’un code ou qu’un jeton d’actualisation renouvelé a été réutilisé, ou que le callback ou le vérificateur a changé. Après un 401, actualisez une fois ; si l’actualisation échoue, demandez à l’utilisateur de se reconnecter. Un 403 signifie que le jeton ne dispose pas du scope requis. Consultez le contrat OpenAPI et le guide détaillé d’intégration des applications connectées.

Question 17

Comment connecter Cathopic à une autre application ?

Accepted Answer

Une plateforme approuvée peut vous permettre d’utiliser le catalogue Cathopic sans recevoir votre mot de passe. Elle envoie votre navigateur vers une page sécurisée sur cathopic.com, où vous vous connectez et consultez les autorisations exactes demandées. Connecter votre compte Dans l’autre application, choisissez son connecteur Cathopic et cliquez sur Connecter ou Se connecter avec Cathopic. Confirmez que le navigateur est sur cathopic.com. Connectez-vous à Cathopic si nécessaire. Cathopic revient à la même demande d’autorisation au lieu d’ouvrir votre profil. Lisez chaque autorisation. Elles peuvent inclure l’identité du compte, l’accès au catalogue, le solde de l’abonnement ou la possibilité d’accorder une licence à des ressources. Choisissez Autoriser l’accès. Cathopic ne vous renvoie que vers le rappel (callback) exact enregistré pour cette application. Langue et sécurité du compte L’application peut demander une langue prise en charge pour les écrans de connexion et d’autorisations. Cathopic conserve cette langue tout au long de la connexion. L’application reçoit des jetons à durée de vie courte, jamais votre mot de passe, et ne peut effectuer que les actions listées sur l’écran d’autorisation. Si vous ne faites pas confiance à la demande Choisissez Annuler. N’approuvez pas la connexion si l’application vous est inconnue, si les autorisations semblent inutiles, ou si le navigateur n’affiche pas le domaine Cathopic. Vous pouvez ultérieurement révoquer l’accès depuis Paramètres → Développeur / API → Applications connectées.

Question 18

Les applications connectées utilisent-elles mes téléchargements, et comment les déconnecter ?

Accepted Answer

La recherche et l’affichage d’aperçus avec filigrane ne consomment jamais un téléchargement. Un téléchargement ne peut être consommé que lorsqu’une application connectée demande à Cathopic d’accorder une licence à une ressource payante. Lorsqu’un téléchargement est consommé La ressource est payante, l’offre inclut son type et ni vous ni l’abonnement de l’équipe en cours ne l’ont déjà concédé sous licence. L’offre dispose d’un solde limité. Les offres illimitées enregistrent la licence sans réduire un nombre. Le fichier original est disponible. Cathopic le vérifie avant de modifier le solde. Lorsqu’aucun téléchargement supplémentaire n’est consommé La ressource est gratuite. Vous ou un autre membre utilisant le même abonnement d’équipe l’avez déjà concédée sous licence. Vous demandez un nouveau lien de téléchargement pour une licence existante. L’application réessaie la même demande avec la même clé d’idempotence. Les membres de l’équipe consomment le solde partagé de l’administrateur de l’équipe. Cathopic est toujours la source de vérité. Déconnecter une application Ouvrir Paramètres → Développeur / API → Applications connectées. Vérifiez l’application et ses autorisations. Cliquer Déconnecter et confirmer. Tous les jetons d’accès et d’actualisation actifs pour cette application sont révoqués immédiatement. Les licences existantes et l’historique des téléchargements restent inchangés.

Question 19

Codes d’erreur courants de l’API

Accepted Answer

Comprendre les réponses d’erreur vous aide à résoudre les problèmes rapidement. Voici les erreurs les plus courantes que vous rencontrerez. 400 Requête incorrecte { "error": "media_id is required" } Causes : Paramètre requis manquant Format de paramètre invalide JSON mal formé Correction : Vérifiez que le corps de votre requête correspond à la spécification de l’API sur api.cathopic.com/docs. 401 Non autorisé { "message": "Unauthorized" } ou { "error": "Unauthorized token" } Causes : Clé API manquante ou invalide Clé API désactivée Mauvais nom d’en-tête Correction : Vérifiez que votre en-tête x-api-key est correct et que la clé est active dans Paramètres → API. 404 Introuvable { "error": "No file found for media_id 1234" } ou { "error": "Media item not found" } Causes : La ressource n’existe pas La ressource a été supprimée Mauvais media_id Correction : Vérifiez que le media_id existe en commençant par une recherche avec /resources. 429 Trop de requêtes { "error": "Limit exceed." } Causes : Trop de requêtes sur une courte période Limite de débit dépassée Correction : Mettez en place un backoff exponentiel. Attendez puis réessayez en augmentant progressivement les délais (1 s, 2 s, 4 s, etc.). 500 Erreur interne du serveur { "error": "Internal server error" } Causes : Problème temporaire du serveur Condition inattendue Correction : Attendez un instant puis réessayez. Si le problème persiste, contactez le support. Exemple de gestion des erreurs async function searchWithErrorHandling(query) { try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query, page: 1, page_size: 20 }) }); if (!response.ok) { const error = await response.json(); switch (response.status) { case 400: console.error('Bad request:', error); break; case 401: console.error('Unauthorized. Check your API key.'); break; case 404: console.error('Resource not found:', error); break; case 429: console.error('Rate limited. Implementing backoff...'); await sleep(5000); return searchWithErrorHandling(query); // Retry case 500: console.error('Server error. Retrying in 10s...'); await sleep(10000); return searchWithErrorHandling(query); default: console.error('Unknown error:', error); } throw new Error(`API error: ${response.status}`); } return await response.json(); } catch (error) { console.error('Request failed:', error); throw error; } } En cas d’erreurs persistantes, consultez la documentation complète de l’API ou contactez le support.

Question 20

Erreurs de limitation de débit

Accepted Answer

Si vous voyez 429 Too Many Requests, c’est que vous sollicitez l’API trop fréquemment. Voici comment le gérer correctement. L’erreur HTTP 429 Too Many Requests { "error": "Limit exceed." } Pourquoi cela arrive Les limites de débit protègent l’API contre une utilisation excessive : Trop de requêtes en peu de temps Interrogation fréquente ou scraping agressif Absence de délai entre les requêtes Requêtes concurrentes sans limitation (throttling) Stratégie de backoff exponentiel La meilleure façon de gérer les limites de débit est d’utiliser un backoff exponentiel : attendez plus longtemps après chaque nouvelle tentative : async function fetchWithBackoff(url, options, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt + 1}/${maxRetries}`); await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { if (attempt === maxRetries - 1) throw error; } } throw new Error('Max retries exceeded'); } Prévenir les limitations de débit Ajoutez des délais entre les requêtes : // Mauvais : requêtes en rafale for (const id of mediaIds) { await api.getResource(id); // Pas de délai } // Bon : requêtes limitées for (const id of mediaIds) { await api.getResource(id); await sleep(500); // Délai de 500ms } Traitez par lots : // Traiter par lots de 10 avec des délais const batchSize = 10; for (let i = 0; i < mediaIds.length; i += batchSize) { const batch = mediaIds.slice(i, i + batchSize); await Promise.all(batch.map(id => api.getResource(id))); if (i + batchSize < mediaIds.length) { await sleep(2000); // 2s entre les lots } } Mettre en cache les réponses : const cache = new Map(); async function getCachedResource(mediaId) { if (cache.has(mediaId)) { return cache.get(mediaId); } const data = await api.getResource(mediaId); cache.set(mediaId, data); return data; } Ce qu’il ne faut PAS faire ❌ Réessayer immédiatement sans délai ❌ Faire des requêtes en parallèle sans limite ❌ Ignorer les erreurs 429 ❌ Utiliser des délais fixes et courts (utilisez toujours un backoff exponentiel) Si les problèmes persistent Contactez l’assistance développeurs si vous avez réellement besoin de limites de débit plus élevées pour votre cas d’usage. Indiquez : Votre application et votre cas d’usage Le volume de requêtes attendu Votre implémentation actuelle (avec backoff)

Question 21

Dépassement de délai et problèmes réseau

Accepted Answer

Les problèmes de réseau peuvent entraîner l’échec des requêtes à l’API. Voici comment gérer les dépassements de délai et les problèmes de connexion avec élégance. Définir des délais appropriés Définissez toujours des délais pour éviter que les requêtes restent en attente : // JavaScript avec fetch const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); // 30s try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }), signal: controller.signal }); clearTimeout(timeout); return await response.json(); } catch (error) { clearTimeout(timeout); if (error.name === 'AbortError') { console.error('Requête dépassée après 30s'); } else { console.error('Erreur réseau :', error); } throw error; } // Python avec requests import requests from requests.exceptions import Timeout, RequestException try: response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'}, timeout=30 # 30 secondes ) return response.json() except Timeout: print('Requête dépassée après 30s') raise except RequestException as e: print(f'Erreur réseau : {e}') raise Erreurs réseau courantes Délai de connexion : Impossible d’établir une connexion au serveur En général, problème réseau ou de pare-feu Vérifiez la connexion Internet Vérifiez que le pare-feu autorise le HTTPS vers api.cathopic.com Délai de lecture : Connexion établie, mais aucune réponse Le serveur peut être lent ou surchargé Augmentez le délai ou réessayez plus tard Échec de résolution DNS : Impossible de résoudre api.cathopic.com Problème du serveur DNS Réessayez ou vérifiez les paramètres DNS Réessayer avec un backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); const response = await fetch(url, { ...options, signal: controller.signal }); clearTimeout(timeout); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { const isLastAttempt = attempt === maxRetries - 1; if (isLastAttempt) { console.error(`Tous les ${maxRetries} essais ont échoué`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`L’essai ${attempt + 1} a échoué. Nouvelle tentative dans ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Valeurs de délai recommandées Délai de connexion : 10 secondes Délai de lecture : 30 secondes Recherche /resources : 30 secondes /confirm licensing : 30 secondes Déboguer les problèmes réseau Utilisez curl pour tester la connectivité : # Tester la connectivité de base curl -v https://api.cathopic.com/resources # Tester avec un délai curl --max-time 30 -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Vérifiez : ✓ api.cathopic.com se résout en DNS ✓ La connexion SSL/TLS réussit ✓ Une réponse HTTP est reçue ✓ Le temps de réponse est raisonnable (<5s en général) Si les problèmes persistent, contactez support avec des détails de diagnostic réseau.

Question 22

Débogage des requêtes ayant échoué

Accepted Answer

Lorsque les requêtes échouent, un débogage systématique permet d’identifier rapidement le problème. Activer la journalisation détaillée async function debugRequest(url, options) { console.log('=== API Request ==="); console.log('URL:', url); console.log('Method:', options.method); console.log('Headers:', { ...options.headers, 'x-api-key': options.headers['x-api-key']?.substring(0, 10) + '...' }); console.log('Body:', options.body); const startTime = Date.now(); try { const response = await fetch(url, options); const duration = Date.now() - startTime; console.log('=== API Response ==="); console.log('Status:', response.status, response.statusText); console.log('Duration:', duration + 'ms'); console.log('Headers:', Object.fromEntries(response.headers)); const data = await response.json(); console.log('Body:', data); return { response, data }; } catch (error) { console.error('=== Request Failed ==="); console.error('Error:', error.message); console.error('Duration:', Date.now() - startTime + 'ms'); throw error; } } Vérifiez d’abord ces points 1. La clé API est correcte : console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. Le nom du header est exact : // Doit être en minuscules 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Correct 'X-API-Key': apiKey, // ✗ Incorrect 'api-key': apiKey, // ✗ Incorrect } 3. Le JSON est valide : try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. La requête atteint le serveur : // Utilisez l’onglet Network des DevTools du navigateur ou curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Erreurs courantes Mauvais Content-Type : // ✗ Incorrect headers: { 'Content-Type': 'text/plain' } // ✓ Correct headers: { 'Content-Type': 'application/json' } Ne pas sérialiser le body : // ✗ Incorrect body: { query: 'test' } // ✓ Correct body: JSON.stringify({ query: 'test' }) Utiliser GET au lieu de POST : // ✗ Tous les endpoints nécessitent POST method: 'GET' // ✓ Correct method: 'POST' Tester avec une requête minimale Réduisez au strict minimum pour isoler le problème : const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Objet vide }); console.log(response.status); console.log(await response.json()); Si cela fonctionne, ajoutez progressivement les paramètres jusqu’à ce que cela échoue. Comparer avec un exemple fonctionnel Testez avec curl pour vérifier votre implémentation : curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Jesus", "page": 1, "page_size": 5}' Si curl fonctionne mais pas votre code, comparez les headers et le body exacts. Encore bloqué ? Contactez l’assistance développeur avec : Le message d’erreur complet Les headers de la requête (masquez votre clé API complète) Le body de la requête Le statut de la réponse et le body Le langage de programmation et la bibliothèque HTTP Un extrait de code (sans exposer les identifiants)

Question 23

Comment contacter le support développeurs

Accepted Answer

Vous avez besoin d’aide pour votre intégration API ? Notre équipe de support développeurs est là pour vous aider. Quand contacter le support Contactez-nous si vous rencontrez : Des problèmes d’authentification malgré le suivi des guides Des réponses d’erreur inattendues Des problèmes de performance ou des réponses lentes Des questions sur la facturation ou l’utilisation Besoin de limites de débit plus élevées Des précisions sur les conditions de licence De l’aide pour des scénarios d’intégration spécifiques Comment nous contacter Page d’assistance : Rendez-vous sur cathopic.com/support et remplissez le formulaire de contact. E-mail (si fourni) : Envoyez les détails directement à l’adresse e-mail de support développeurs indiquée dans votre tableau de bord API. Informations à inclure Aidez-nous à vous aider plus rapidement en fournissant : 1. Une description claire du problème Ce que vous essayez de faire Ce qui se passe par rapport à ce que vous attendez Quand le problème a commencé 2. Détails techniques Langage de programmation et framework Bibliothèque HTTP ou SDK que vous utilisez Les 4 derniers chiffres de votre clé API Messages d’erreur (texte intégral) Codes d’état HTTP 3. Exemple de code (sanitisé) // Supprimez votre clé API complète ! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Seuls les 4 derniers chiffres 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Détails de la requête/réponse En-têtes de la requête Corps de la requête Statut de la réponse Corps de la réponse Horodatage du problème Avant de contacter le support Essayez d’abord ces étapes pour gagner du temps : Consultez la documentation API Relisez les questions de cette section d’aide Testez avec curl pour isoler le problème Vérifiez que votre clé API est active dans Paramètres → API Vérifiez que votre moyen de paiement est valide Délai de réponse Nous visons à répondre aux demandes de support développeurs sous 24 à 48 heures les jours ouvrés. Les problèmes complexes peuvent nécessiter un temps d’investigation supplémentaire. Pour les problèmes urgents Si vous rencontrez une panne critique en production : Marquez votre demande de support comme « Urgent » Indiquez l’e-mail de votre compte pour une identification prioritaire Ajoutez des détails sur l’impact (nombre d’utilisateurs concernés, impact sur le chiffre d’affaires, etc.) Statut de l’API Avant de signaler une panne, vérifiez s’il y a un incident connu : Testez la connectivité de base : curl https://api.cathopic.com/resources Consultez notre page de statut (si disponible) Recherchez des annonces dans le tableau de bord de votre compte Ressources supplémentaires Documentation API complète : api.cathopic.com/docs Tableau de bord du compte : cathopic.com/settings/api Support général : cathopic.com/support Informations sur la licence : cathopic.com/legal/license Nous sommes là pour vous aider à réussir votre intégration !

Développeur / API

Bien démarrer

Clés API, facturation et sécurité

Catalogue, recherche et licences

Applications OAuth

Applications connectées

Dépannage