Question 1

Cos’è l’API di Cathopic?

Accepted Answer

La nostra API è un servizio RESTful che ti consente di integrare direttamente la libreria di media cattolici di Cathopic nelle tue applicazioni. Accedi programmaticamente a migliaia di immagini, video e grafica. Cosa puoi fare Cerca e sfoglia l’intero catalogo Licenzia le risorse automaticamente per i tuoi utenti finali Scarica in più formati ottimizzati per diversi casi d’uso Accedi a metadati ricchi inclusi tag, descrizioni e informazioni liturgiche Architettura REST Costruita su principi REST standard: URL di base: https://api.cathopic.com Formato dei dati: richieste e risposte JSON Autenticazione: chiave API tramite header x-api-key Metodo HTTP: POST per tutti gli endpoint Quattro endpoint principali POST /resources - Cerca nel catalogo POST /resource - Ottieni i dettagli di un elemento specifico POST /confirm - Licenzia una risorsa e ottieni gli URL di download POST /remove - Interrompi la licenza quando non è più necessaria (solo sito web) Documentazione completa Tutto ciò di cui hai bisogno è disponibile online: Riferimento API interattivo: api.cathopic.com/docs Esempi di codice in più linguaggi Specifiche dettagliate dei parametri Come iniziare Contatta il nostro team per richiedere l’accesso all’API Genera la tua chiave API in Impostazioni → API Aggiungi un metodo di pagamento per la fatturazione dell’utilizzo Inizia a sviluppare Consulta le altre domande di questa sezione per i dettagli su autenticazione, fatturazione e best practice. Accordo di licenza per l’API Tutti gli utilizzi dell’API sono soggetti al nostro Accordo di licenza per l’API. Punti chiave da comprendere: Solo uso digitale: il contenuto può essere visualizzato esclusivamente in ambienti web e email Nessun download di file: gli utenti finali non possono scaricare o esportare i file originali Usi vietati: l’addestramento di AI/ML, i materiali di stampa e l’uso offline sono strettamente vietati Fatturazione basata sull’utilizzo: paga solo per l’effettivo utilizzo del contenuto da parte dei tuoi utenti finali Usando l’API, accetti tutti i termini dell’accordo di licenza Prima di integrare l’API: Rivedi l’Accordo di licenza per l’API completo Comprendi le restrizioni e gli obblighi Assicurati che il tuo caso d’uso sia conforme ai requisiti di solo digitale Pianifica la tua integrazione per tracciare l’utilizzo in modo accurato ai fini della fatturazione Per maggiori dettagli, vedi: Cosa posso creare con l’API? (include restrizioni dettagliate) Come funzionano le licenze tramite API? (dettagli completi sulla licenza) Come viene fatturato l’utilizzo dell’API? (spiegazione del modello di fatturazione)

Question 2

Cosa posso creare con l’API?

Accepted Answer

L’API di Cathopic ti consente di integrare contenuti visivi cattolici direttamente nella tua applicazione, nel tuo sito web o nella tua piattaforma. Tuttavia, l’uso dell’API è disciplinato rigorosamente dalla nostra Licenza d’uso dell’API, che limita l’utilizzo ad ambienti digitali specifici. Cosa puoi creare Sistemi di gestione di parrocchie e chiese Consentire alle parrocchie di aggiungere immagini cattoliche a bollettini e newsletter Promuovere eventi con contenuti visivi pertinenti Fornire immagini liturgiche in linea con il calendario della chiesa Creare display digitali per gli annunci parrocchiali Piattaforme di contenuti cattolici Creare piattaforme di blogging per autori cattolici con immagini integrate Realizzare siti web di notizie cattoliche con visual pertinenti Sviluppare app devozionali con immagini e preghiere quotidiane Progettare piattaforme di catechesi con strumenti didattici visivi Strumenti di email marketing Consentire ai ministeri di creare newsletter con immagini cattoliche Permettere alle organizzazioni religiose di progettare campagne email Fornire template con contenuti Cathopic integrati Supportare campagne di raccolta fondi con visual appropriati Costruttori di siti web e CMS Integrare immagini cattoliche nelle piattaforme di creazione di siti web Fornire moduli di contenuto per organizzazioni cattoliche Abilitare la selezione delle immagini tramite drag-and-drop da Cathopic Creare template specifici per i ministeri cattolici Gestione di eventi e social media Aiutare i ministeri a creare grafiche per i social (senza scaricare file) Progettare sistemi di invito per eventi con immagini cattoliche Creare calendari dei contenuti con visual della stagione liturgica Consentire alle organizzazioni di programmare post con immagini appropriate Restrizioni critiche che devi rispettare La Licenza d’uso dell’API proibisce rigorosamente alcuni utilizzi. La violazione di queste restrizioni può comportare la cessazione immediata: ❌ Addestramento AI/ML (PROIBITO IN MODO PERMANENTE) Non può essere usata per addestrare, fare fine-tuning o alimentare qualsiasi modello AI/ML Non può creare embedding, dataset o estrazioni derivate per l’AI Questa restrizione resta valida a tempo indeterminato, anche dopo la cessazione dell’accordo Si applica a tutte le forme di machine learning e intelligenza artificiale ❌ Download e esportazioni di file Gli utenti finali non possono scaricare o salvare contenuti come file Non può fornire funzionalità di "download" o "export" Il contenuto deve rimanere ospitato da Cathopic o in una cache autorizzata Possono essere usati solo URL ottimizzati per il web, non file originali ❌ Stampa e uso offline Non può essere usata in materiali di stampa, brochure o poster Nessuna pubblicità offline o prodotti fisici Limitazione rigorosa agli ambienti digitali web ed email Non può essere incorporata in PDF destinati alla stampa ❌ Rivendita e redistribuzione Non può creare prodotti che rivendono o ridistribuiscono contenuti Cathopic Non può creare marketplace di foto stock usando la nostra API Non può offrire contenuti come prodotto autonomo Deve essere integrato come parte di un servizio più ampio ❌ Modifica e opere derivate Non può alterare, trasformare o creare opere derivate Non può applicare filtri o modifiche significative Deve visualizzare il contenuto così come fornito dall’API È consentito un ritaglio e un ridimensionamento di base per finalità di impaginazione Solo ambienti web ed email I contenuti accessibili tramite l’API possono essere usati solo in: Siti web: pagine web pubbliche o private Applicazioni web: strumenti e piattaforme basati sul browser Email: newsletter, campagne ed email transazionali Blog: sistemi di gestione di contenuti online Web embed: iframe controllati o contenuti serviti tramite API Importante: il contenuto deve essere visualizzato esclusivamente con risoluzione ottimizzata per il web. I file originali ad alta risoluzione non sono mai accessibili tramite l’API. Requisiti tecnici La tua applicazione deve: Usare HTTPS: tutte le chiamate API e la consegna dei contenuti devono essere sicure Implementare la gestione delle watermark: inizia con contenuti con watermark, richiedi quelli senza watermark solo quando necessario Tracciare l’utilizzo in modo accurato: registra tutto l’utilizzo dei contenuti ai fini della fatturazione Chiamare l’endpoint /confirm: quando l’utente finale si impegna a usare il contenuto Chiamare l’endpoint /remove: quando il contenuto non è più in uso (cessa la fatturazione) Prevenire accessi non autorizzati: proteggi le credenziali della tua API Rispettare i limiti di velocità: segui i limiti impostati per il tuo account I tuoi obblighi legali Quando integri l’API, devi: Aggiornare i tuoi Termini di utilizzo per informare gli utenti finali: Il contenuto non può essere scaricato o usato al di fuori della tua applicazione Il contenuto non può essere usato per scopi AI/ML Il contenuto è di proprietà di Cathopic e dei suoi creatori L’utilizzo viene tracciato per fatturazione e conformità Implementare controlli tecnici per prevenire: Download con tasto destro (laddove possibile) Accesso diretto tramite URL ai file originali Estensioni del browser che abilitano i download Mantenere i log di utilizzo per: Verifica della fatturazione Verifiche di conformità Risoluzione delle controversie Esempi di integrazioni conformi ✅ Costruttore di bollettini parrocchiali Le parrocchie creano bollettini digitali con immagini cattoliche Il contenuto viene visualizzato sul sito web e nelle newsletter email Nessuna funzionalità di download fornita La fatturazione traccia l’utilizzo per parrocchia e per immagine ✅ Piattaforma email per i ministeri Le organizzazioni religiose progettano campagne email Le immagini vengono servite direttamente nelle email tramite URL dell’API Fatturazione per email inviata con contenuto Nessun salvataggio di file sui dispositivi degli utenti finali ✅ Piattaforma CMS cattolica Costruttore di siti web con libreria Cathopic integrata Gli utenti sfogliano e selezionano immagini per le loro pagine Il contenuto viene incorporato tramite URL serviti dall’API Fatturazione per giorno di utilizzo per utente Esempi di integrazioni proibite ❌ Generatore di immagini basato su AI Usare contenuti Cathopic per addestrare modelli AI Creare dataset per il machine learning Generare immagini simili basandosi sui nostri contenuti ❌ Strumento di progettazione per la stampa Consentire agli utenti di creare poster stampabili Fornire download per la stampa ad alta risoluzione Creare PDF con contenuti Cathopic per la stampa ❌ Marketplace di foto stock Rivendere contenuti Cathopic come prodotti autonomi Creare collezioni derivate di foto stock Riditribuire contenuti a più clienti Prima di iniziare a costruire Lettura essenziale: Rivedi l’Accordo di licenza dell’API completo Studia la documentazione tecnica su api.cathopic.com/docs Comprendi in dettaglio il modello di fatturazione (vedi Come viene fatturato l’utilizzo dell’API?) Pianifica la tua integrazione per rispettare tutte le restrizioni Contattaci tramite support se hai domande Ricorda: accedendo o utilizzando l’API accetti tutti i termini dell’Accordo di licenza dell’API. La mancata conformità può comportare la cessazione immediata e conseguenze legali.

Question 3

Quali sono i limiti di velocità (rate limits)?

Accepted Answer

Al momento, non applichiamo limiti rigorosi di richieste al secondo. Tuttavia, ci si aspetta un uso corretto per mantenere la qualità del servizio per tutti. Approccio attuale Invece di limiti rigidi, incoraggiamo un uso responsabile: Distanzia le richieste in modo ragionevole Implementa un backoff esponenziale quando si verificano errori Usa la cache delle risposte per evitare chiamate ridondanti Contattaci se prevedi volumi di traffico elevati Best practice Usa la cache in modo aggressivo: Salva i risultati di ricerca per le query più comuni Conserva localmente i metadati dei media dopo il recupero Non chiamare /confirm più volte per lo stesso utente/risorsa Raggruppa le operazioni: Raggruppa insieme le richieste correlate Aggiungi piccoli ritardi tra i batch Limita le connessioni concorrenti (10-20 è ragionevole) Gestisci gli errori con attenzione: Implementa una logica di retry con backoff esponenziale Non riprovare immediatamente in caso di fallimento Registra gli errori per il monitoraggio Tempi di risposta attesi Ricerca su /resources: in genere 200-500ms Dettagli di /resource: sotto 100ms /confirm per la licenza: 300-800ms Imposta il timeout del client su almeno 30 secondi per gestire occasionali risposte più lente. Se raggiungi i limiti Riceverai un errore 429 Too Many Requests. Quando succede: // 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; } } } Monitora il tuo utilizzo Traccia l’attività API in Impostazioni → API: Visualizza il totale delle richieste effettuate Controlla le licenze attive Rivedi le tendenze di utilizzo Monitora eventuali pattern insoliti Hai bisogno di limiti più alti? Se il tuo caso d’uso legittimo richiede volumi elevati di richieste (>1M richieste/mese), contatta il nostro team per discutere: La tua applicazione e i pattern di traffico Il volume di richieste previsto I limiti di velocità garantiti, se necessari

Question 4

Come viene fattilizzato l’utilizzo dell’API?

Accepted Answer

L’API di Cathopic utilizza un modello di fatturazione “pay-as-you-go” basato sull’utilizzo effettivo dei contenuti da parte dei tuoi utenti finali. Tutti i termini di fatturazione sono regolati dal nostro Accordo di licenza per l’API. Due modelli di fatturazione La fatturazione dipende da come i tuoi utenti finali consumano i contenuti: 1. Utilizzo sul sito web (modello “Days of Use”) Si applica quando i contenuti vengono visualizzati su siti web, blog o applicazioni web Viene calcolato per ogni giorno di calendario in cui un utente finale accede a contenuti specifici Formula: Totale giorni di utilizzo × (tariffa mensile concordata ÷ 30) La fatturazione giornaliera pro-rata garantisce che tu paghi solo l’utilizzo effettivo Tracciato separatamente per ogni utente finale e per ogni singolo elemento di contenuto 2. Utilizzo via email (modello “Per Email”) Si applica quando i contenuti vengono incorporati nei messaggi email Addebitato per ogni messaggio email inviato (non per destinatario) Fatturazione una tantum per email che include il contenuto Tariffa concordata durante la configurazione dell’accesso all’API Come iniziano e si interrompono le fatturazioni I contenuti con filigrana sono gratuiti Il contenuto appare inizialmente con una filigrana L’anteprima con filigrana non genera addebiti Ideale per consentire agli utenti finali di consultare prima di impegnarsi Può essere usato per test e finalità di prova La fatturazione inizia quando la filigrana viene rimossa L’utente finale decide di utilizzare il contenuto senza filigrana La tua applicazione chiama POST /confirm con: media_id: l’identificatore del contenuto usage_type: “website” oppure “email” client_identifier: l’ID univoco del tuo utente finale L’API restituisce URL permanenti per i contenuti senza filigrana La fatturazione inizia immediatamente da questo momento Devi memorizzare questi URL e i dati di utilizzo per il tracciamento della fatturazione La fatturazione si interrompe quando il contenuto viene rimosso L’utente finale rimuove o smette di utilizzare il contenuto La tua applicazione chiama POST /remove con: media_id: l’identificatore del contenuto client_identifier: l’ID dell’utente finale La fatturazione per quello specifico utilizzo si interrompe Devi eliminare dal tuo database gli URL dei contenuti senza filigrana Esempio di fatturazione per sito web Supponiamo che tu abbia concordato una tariffa mensile di per un utilizzo illimitato dei contenuti: Scenario: La Parrocchia A visualizza l’Immagine n. 12345 nella homepage Giorno 1: chiami /confirm → inizia la fatturazione Giorni 1-15: l’Immagine rimane nella homepage (15 giorni di utilizzo) Giorno 16: la Parrocchia rimuove l’immagine, chiami /remove → la fatturazione si interrompe Calcolo: 15 giorni × ( ÷ 30 giorni) = Addebitato: per questo specifico utilizzo Se anche la Parrocchia B usa la stessa immagine per 10 giorni, viene tracciato separatamente e si aggiunge altro. Esempio di fatturazione via email Supponiamo che tu abbia concordato una tariffa di --.05 per email: Scenario: Un Dicastero invia una newsletter con l’Immagine n. 67890 Azione: chiami /confirm con usage_type: "email" Risultato: addebito una tantum di --.05 per quella email Destinatari: non importa se viene inviata a 100 o a 10.000 persone Addebitato: --.05 totale (non per destinatario) Limiti mensili di fatturazione Il tuo accordo può includere limiti mensili di fatturazione: Ti protegge da bollette inaspettatamente alte Una volta raggiunto il limite, l’utilizzo aggiuntivo può essere gratuito o a tariffa ridotta L’importo specifico del limite viene concordato durante la configurazione dell’accesso all’API Si applica al totale degli addebiti mensili su tutti gli utenti finali Fatturazione e pagamento Programma delle fatture Le fatture vengono emesse mensilmente entro i primi 10 giorni di ogni mese Coprono tutto l’utilizzo del mese precedente Dettaglio dell’utilizzo per utente finale e per singolo elemento di contenuto Inviate all’indirizzo email associato al tuo account API Elaborazione dei pagamenti I pagamenti vengono elaborati esclusivamente tramite Stripe Addebito automatico sul metodo di pagamento registrato Devi mantenere sempre informazioni di pagamento valide Le ricevute vengono fornite automaticamente dopo un pagamento riuscito Fallimenti di pagamento Se il pagamento non va a buon fine, il sistema effettua 4 tentativi di recupero Ricevi notifiche via email riguardo ai problemi di pagamento Se tutti i tentativi falliscono, l’accesso all’API viene sospeso L’accesso viene ripristinato immediatamente dopo un pagamento riuscito Le fatture non pagate possono accumulare interessi Le tue responsabilità di tracciamento Devi mantenere registri accurati di: Log di utilizzo: quando il contenuto è stato confermato e rimosso ID degli utenti finali: quali utenti hanno accesso a quali contenuti ID dei contenuti: quali elementi multimediali sono stati usati Tipi di utilizzo: sito web vs email per ogni utilizzo Date: data di inizio e data di fine per l’utilizzo sul sito web URL: URL senza filigrana memorizzati per l’utilizzo attivo Questi log sono essenziali per: Verificare le fatture mensili Risoluzione delle controversie di fatturazione Audit di conformità da parte di Cathopic La tua reportistica interna Accedere ai report di utilizzo Puoi monitorare l’utilizzo della tua API in tempo reale: Vai su Impostazioni → API Visualizza la sezione “Utilizzo on-demand” Consulta le statistiche del periodo di fatturazione corrente: Costo totale accumulato finora Numero di utilizzi sul sito web Numero di utilizzi via email Clicca “Visualizza report dettagliato” per il dettaglio per: Utente finale (client identifier) Elemento di contenuto Tipo di utilizzo Intervallo di date Costi individuali Esporta i report in formato CSV per i tuoi archivi Concordare le tariffe Il prezzo dell’API è personalizzato per ogni cliente: Le tariffe vengono concordate durante il processo di richiesta di accesso all’API In base al volume di utilizzo previsto In base al tuo caso d’uso specifico e al tipo di integrazione Può includere sconti sul volume per applicazioni ad alto utilizzo I limiti di fatturazione possono essere concordati per fornire costi prevedibili Per discutere i prezzi: Visita la nostra pagina di supporto Seleziona “API access request” Descrivi la tua integrazione e l’utilizzo previsto Il nostro team fornirà un preventivo personalizzato Comprendere l’intera licenza La fatturazione è solo un aspetto dell’accordo relativo all’API. Rivedi i termini completi: Leggi l’Accordo di licenza per l’API completo Comprendi le restrizioni d’uso (solo digitale, niente AI/ML, niente download) Conosci i tuoi obblighi per il tracciamento e la rendicontazione Rivedi le clausole su proprietà intellettuale e risoluzione Per dettagli tecnici sull’implementazione: Consulta gli endpoint /confirm e /remove su api.cathopic.com/docs Comprendi come calcolare l’utilizzo per la tua integrazione specifica Rivedi le migliori pratiche per un tracciamento della fatturazione accurato Ricorda: il tracciamento accurato dell’utilizzo è una tua responsabilità. Mantieni log dettagliati per garantire una fatturazione corretta e la conformità all’accordo di licenza.

Question 5

Come richiedere l’accesso per sviluppatori per l’API e OAuth

Accepted Answer

Cathopic esamina un account sviluppatore una sola volta. Questa singola approvazione sblocca sia l’API commerciale sia la gestione delle applicazioni OAuth; non invii richieste separate. Dopo l’approvazione, crei e gestisci le tue chiavi API e le credenziali OAuth da Impostazioni di Cathopic. Gli sviluppatori non hanno mai bisogno di un comando del server Cathopic o di accesso all’infrastruttura. 1. Prepara il tuo account Cathopic Crea un account Cathopic, verifica l’indirizzo email e assicurati che il nome utente e l’email nella richiesta corrispondano esattamente a quell’account. 2. Invia la richiesta per sviluppatori Apri il modulo di contatto di Cathopic. Seleziona Richiedi accesso per sviluppatori. Conferma il nome utente di Cathopic e descrivi il prodotto, l’organizzazione e l’uso previsto del catalogo. Invia il modulo. La richiesta appare nella dashboard interna di revisione di Cathopic. 3. Ricevi la decisione Cathopic esamina l’account e il caso d’uso. Quando viene approvato, lo sviluppatore riceve un’email con i passaggi successivi e un link a Impostazioni → Developer / API → applicazioni OAuth. Se serve ulteriore informazione, Cathopic contatta l’email indicata nella richiesta. 4. Crea l’applicazione Scegli un’applicazione web riservata quando il prodotto ha un backend sicuro, oppure un’applicazione pubblica PKCE per client solo browser, mobile o desktop. Inserisci il suo nome pubblico, descrizione, sito web, informativa sulla privacy, contatto per la sicurezza, gli URL di callback esatti e solo gli scope di cui ha bisogno. 5. Salva le credenziali L’ID client identifica l’integrazione e viene condiviso da tutti gli utenti di quel prodotto. L’autorizzazione dell’utente e i token restano separati per ciascun account Cathopic. Un segreto client riservato viene mostrato una sola volta e deve essere cifrato sul server dell’applicazione. Non includerlo mai nel codice del browser, nei siti web generati, nei log, nei messaggi di supporto o in un repository pubblico. Nella stessa pagina l’utente sviluppatore approvato può modificare callback e scope, ruotare un segreto riservato o revocare l’applicazione.

Question 6

Come funzionano le chiavi API?

Accepted Answer

Le chiavi API sono le tue credenziali di autenticazione per accedere all’API di Cathopic. Comprendere come funzionano è essenziale per un’integrazione API sicura ed efficace. Che cos’è una chiave API? Una chiave API è un token segreto univoco che identifica la tua applicazione e la autorizza ad accedere all’API di Cathopic: Una lunga stringa alfanumerica (ad es. sk_live_abc123xyz789...) Agisce sia come autenticazione sia come autorizzazione Collegata al tuo account Cathopic e alla fatturazione Può essere attiva o inattiva Ciclo di vita della chiave Creazione: Genera le chiavi in Impostazioni → API Assegna a ogni chiave un nome descrittivo ("Sito Web di Produzione", "Staging", "App Mobile") Copia l’intera chiave subito: viene mostrata solo una volta Conserva in modo sicuro (variabili d’ambiente, secrets manager, password manager) Utilizzo: Includi nell’header HTTP x-api-key con ogni richiesta Le chiavi vengono validate lato server ad ogni richiesta Tutti gli utilizzi dell’API vengono tracciati e addebitati al tuo account Disattivazione: Le chiavi possono essere disabilitate temporaneamente senza eliminarle Utile per la risoluzione dei problemi o per mettere in pausa una specifica integrazione Può essere riattivata in qualsiasi momento Eliminazione: Rimuove definitivamente la chiave Non può essere annullata o recuperata Tutte le richieste con quella chiave falliranno immediatamente Linee guida per la gestione delle chiavi Sicurezza: Non inserire mai le chiavi nel controllo versione: Usa i file .env e aggiungili a .gitignore Non esporre mai nel codice lato client: Le chiavi API devono essere usate solo lato server Usa variabili d’ambiente: Conserva le chiavi in process.env.CATHOPIC_API_KEY o equivalente Ruota regolarmente le chiavi: Cambiale periodicamente (trimestralmente o dopo cambi di membri del team) Usa chiavi separate per ogni ambiente: Chiavi diverse per sviluppo, staging e produzione Organizzazione: Nomi descrittivi: Dai alle chiavi un nome in base allo scopo: "Sito Web di Produzione", "App iOS", "Sistema Email" Traccia la proprietà: Registra quale membro del team ha creato ogni chiave Audit regolari: Rivedi le chiavi attive ogni mese e rimuovi quelle non utilizzate Più chiavi API Puoi creare più chiavi API per scopi diversi: Per ambiente: Chiavi separate per sviluppo, staging e produzione Per applicazione: Chiavi diverse per sito web, app mobile, strumenti interni Per membro del team: Chiavi individuali per i developer (più facile da tracciare e revocare) Tutte le chiavi sotto il tuo account condividono la stessa fatturazione. L’utilizzo di tutte le chiavi viene combinato nella tua fattura mensile. Monitoraggio dell’utilizzo delle chiavi Traccia l’attività per ogni chiave: Vai su Impostazioni → API Visualizza l’elenco di tutte le chiavi con le date dell’ultimo utilizzo Clicca su una chiave per vedere statistiche dettagliate sull’utilizzo Monitora attività non previste Cosa fare se una chiave è compromessa Se ritieni che una chiave API sia stata esposta: Elimina o disattiva immediatamente la chiave in Impostazioni → API Genera una nuova chiave di sostituzione Aggiorna la tua applicazione con la nuova chiave Rivedi i log di utilizzo per eventuali attività sospette Contatta l’assistenza se vedi utilizzo non autorizzato Esempio: conservare le chiavi in modo sicuro Node.js con variabili d’ambiente: // File .env (aggiungi a .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Il tuo codice 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 con variabili d’ambiente: 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

Come faccio ad autenticare le richieste?

Accepted Answer

Tutte le richieste all’API di Cathopic devono essere autenticate utilizzando la tua chiave API. Ecco come autenticare correttamente le chiamate alla tua API. Metodo di autenticazione L’API di Cathopic utilizza l’autenticazione tramite chiave API tramite intestazioni HTTP: Nome dell’intestazione: x-api-key Valore dell’intestazione: La tua chiave API completa Richiesto per: Tutti gli endpoint dell’API Maiuscole/minuscole: I nomi e i valori delle intestazioni devono corrispondere esattamente Esempio di autenticazione di 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); ?> Errori di autenticazione Se l’autenticazione non riesce, riceverai una risposta di errore: Chiave API mancante: HTTP 401 Unauthorized { "message": "Unauthorized" } Chiave API non valida: HTTP 401 Unauthorized { "message": "Unauthorized" } Chiave API inattiva: HTTP 401 Unauthorized { "error": "Unauthorized token" } Promemoria importanti Sicurezza: Non inserire mai chiavi API nel codice: Usa variabili d’ambiente o configurazioni sicure Solo lato server: Non includere mai chiavi API in JavaScript lato client Usa solo HTTPS: Le chiavi API trasmesse via HTTP sono vulnerabili Ruota regolarmente le chiavi: Cambiale periodicamente per la sicurezza Gestione degli errori: Controlla i codici di stato: Verifica sempre lo stato della risposta HTTP Registra gli errori di autenticazione: Tieni traccia dei tentativi non riusciti per il monitoraggio della sicurezza Implementa la logica di retry: Con backoff esponenziale per errori temporanei Verifica prima di inviare: Assicurati che la chiave API sia caricata correttamente Test dell’autenticazione Test rapido per verificare che la tua chiave API funzioni: 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}' Risposta attesa (successo): { "total": 1234, "page": 1, "page_size": 1, "results": [ ... ] } Errori comuni Nome dell’intestazione errato: Deve essere x-api-key, non api-key o Authorization Formato del valore non corretto: Usa la chiave completa così com’è, senza prefisso "Bearer" Spazi bianchi finali: Rimuovi gli spazi bianchi dai valori della chiave API prima di usarli Chiave non caricata: Controlla che la variabile d’ambiente sia impostata correttamente Per la risoluzione dei problemi di autenticazione, vedi "Errori comuni di autenticazione" in questa sezione.

Question 8

Come ruoto una chiave API?

Accepted Answer

Ruotare regolarmente le chiavi API è una pratica di sicurezza importante. Ecco come ruotare le chiavi in modo sicuro senza interrompere il servizio. Perché ruotare le chiavi API? Best practice di sicurezza: Riduce l’esposizione se una chiave viene mai compromessa Cambiamenti nel team: Quando gli sviluppatori lasciano l’azienda o cambiano ruolo Possibile compromissione: Se ritieni che una chiave possa essere stata esposta Conformità: Alcune policy di sicurezza richiedono la rotazione periodica delle chiavi Cambiamenti dell’ambiente: Quando migri l’infrastruttura o fai refactoring Processo di rotazione standard (zero downtime) Passo 1: Crea una nuova chiave Accedi a Impostazioni → API Clicca "Crea nuova chiave API" Assegnale un nome descrittivo (es., "Produzione Web v2") Copia subito la nuova chiave: viene mostrata solo una volta Conservala in modo sicuro Passo 2: Aggiorna la tua applicazione Distribuisci la nuova chiave alla tua applicazione (variabili d’ambiente, secret manager, ecc.) Riavvia l’applicazione per caricare la nuova chiave Verifica che la nuova chiave funzioni correttamente Monitora eventuali errori Passo 3: Monitora la transizione Mantieni entrambe le chiavi attive temporaneamente Controlla Impostazioni → API per vedere le date di "Ultimo utilizzo" Attendi finché la vecchia chiave non mostra più attività recente Assicurati che tutte le istanze/servizi siano passati alla nuova chiave Passo 4: Elimina la vecchia chiave Dopo aver confermato che la vecchia chiave non è più in uso Elimina o disattiva la vecchia chiave in Impostazioni → API Documenta la rotazione per i tuoi archivi Processo di rotazione rapido (se compromessa) Se una chiave è sicuramente compromessa e devi agire immediatamente: Elimina prima la chiave compromessa in Impostazioni → API Crea una nuova chiave di sostituzione Distribuisci rapidamente la nuova chiave a tutte le applicazioni Accetta un breve downtime per prevenire accessi non autorizzati Monitora i log di utilizzo per individuare eventuali attività sospette Contatta l’assistenza se necessario Strategia di rotazione multi-ambiente Per i sistemi di produzione, usa un approccio a fasi: Settimana 1: Sviluppo Crea e distribuisci la nuova chiave all’ambiente di sviluppo Testa accuratamente Settimana 2: Collaudo Distribuisci la nuova chiave all’ambiente di staging Esegui test di integrazione Monitora eventuali problemi Settimana 3: Produzione Distribuisci la nuova chiave in produzione durante un periodo a basso traffico Monitora attentamente Mantieni la vecchia chiave attiva per 24-48 ore come fallback Settimana 4: Pulizia Verifica che la vecchia chiave non mostri attività Elimina la vecchia chiave Aggiorna la documentazione Esempio di automazione Script per aiutare a verificare che la rotazione della chiave sia completa: #!/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 Best practice Ruota regolarmente: Ogni 90 giorni per le chiavi di produzione Documenta le rotazioni: Mantieni un registro di quando le chiavi sono state ruotate e del perché Testa prima di eliminare: Verifica sempre che la nuova chiave funzioni prima di rimuovere la vecchia Usa più chiavi: Separare le chiavi per ambiente rende la rotazione più semplice Automatizza quando possibile: Usa strumenti di gestione dei segreti che supportano la rotazione automatica Checklist dopo la rotazione Conferma questi punti dopo la rotazione: ✅ Tutte le istanze di produzione che usano la nuova chiave ✅ Tutti gli ambienti staging/dev aggiornati (se usi la stessa chiave) ✅ Variabili d’ambiente aggiornate ✅ Secret CI/CD aggiornati ✅ Documentazione aggiornata ✅ Notifica ai membri del team ✅ Vecchia chiave eliminata ✅ Rotazione registrata per scopi di audit

Question 9

Come metto in sicurezza le mie credenziali?

Accepted Answer

Le tue chiavi API sono la porta d’accesso al tuo account Cathopic. Tenerle al sicuro previene accessi non autorizzati e protegge dalle frodi di fatturazione. La regola d’oro: tieni le chiavi segrete Tratta le tue chiavi API come password. Errori comuni da evitare: Inserire le chiavi direttamente nel codice sorgente Condividere le chiavi su Git o in altri sistemi di version control Usare le chiavi in JavaScript lato client o in app mobili Condividere le chiavi via email, Slack o app di messaggistica Salvare le chiavi in posizioni pubbliche (repo pubblici, wiki, ecc.) Usa le variabili d’ambiente Conserva le chiavi in variabili d’ambiente invece che nel codice: // file .env (aggiungi a .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Il tuo codice require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Questo separa i dati sensibili dal tuo codebase e rende più semplice la rotazione delle chiavi. Solo lato server Le chiamate API devono avvenire dai tuoi server backend, non dai browser o dalle app mobili. Se gli utenti hanno bisogno di accedere alle risorse di Cathopic: Crea un endpoint backend che utilizzi la tua chiave API Il tuo frontend chiama il TUO endpoint, non Cathopic direttamente Il tuo server convalida la richiesta dell’utente prima di chiamare Cathopic Limita per IP (se possibile) Alcune infrastrutture consentono la whitelist degli IP. Se le tue chiamate API provengono da IP noti: Configura le regole del firewall per limitare l’accesso in uscita Usa account di servizio dedicati con permessi minimi Monitora i log di accesso per attività insolite Se una chiave è compromessa Se sospetti che una chiave sia stata esposta: Genera immediatamente una nuova chiave API Aggiorna la tua applicazione con la nuova chiave Elimina la chiave compromessa Rivedi i log di utilizzo per attività sospette Contatta support se vedi addebiti non autorizzati Gestisci le tue chiavi in modo sicuro su Impostazioni → API.

Question 10

Errori comuni di autenticazione

Accepted Answer

Se hai difficoltà ad autenticarti con l’API di Cathopic, ecco i problemi più comuni e come risolverli. 401 Unauthorized L’errore di autenticazione più comune: HTTP 401 Unauthorized { "message": "Unauthorized" } Cause comuni: Header x-api-key mancante Chiave API non valida o scaduta Refuso nella chiave API Spazi bianchi prima/dopo la chiave Chiave non caricata dalla variabile d’ambiente Come risolvere: Verifica che il nome dell’header sia esattamente x-api-key (minuscolo) Copia di nuovo la tua chiave API da Impostazioni → API Controlla che le variabili d’ambiente siano caricate: console.log(process.env.CATHOPIC_API_KEY) Rimuovi gli spazi bianchi: apiKey.trim() Verifica che la chiave sia attiva (non eliminata o disattivata) Nome dell’header errato L’API richiede x-api-key, non altri nomi di header comuni: // ❌ SBAGLIATO Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRETTO x-api-key: sk_live_abc... Errore di token non autorizzato HTTP 401 Unauthorized { "error": "Unauthorized token" } Causa: La tua chiave API è stata disattivata o eliminata. Come risolvere: Controlla se la chiave è ancora attiva in Impostazioni → API Riattiva la chiave se era stata disattivata Genera una nuova chiave se quella vecchia è stata eliminata Variabile d’ambiente non caricata Il tuo codice non riesce a trovare la chiave API: // Restituisce undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Come risolvere: Node.js: // Assicurati che .env sia caricato require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; if (!apiKey) { throw new Error('CATHOPIC_API_KEY non impostata'); } 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 non impostata') Errore di esposizione lato client Stai cercando di usare la chiave API nel browser tramite JavaScript: // ❌ Questo fallirà (le chiavi non funzionano nei browser) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Come risolvere: Crea un endpoint lato server che faccia da proxy alle richieste verso l’API di Cathopic. Vedi "Come posso proteggere le mie credenziali?" per esempi. Errori CORS Se vedi errori CORS nella console del browser: Accesso a fetch è stato bloccato dalla policy CORS... Causa: Stai cercando di chiamare l’API direttamente da JavaScript lato client. Come risolvere: L’API di Cathopic è solo lato server. Devi fare da proxy alle richieste tramite il tuo backend. Test dell’autenticazione Test rapido per verificare la configurazione: curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: LA_TUA_CHIAVE" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Cerca una risposta HTTP 200 # Se 401, controlla attentamente la chiave Checklist di debug Se l’autenticazione continua a fallire: ☐ Il nome dell’header è x-api-key (sensibile alle maiuscole/minuscole) ☐ La chiave API è l’intera chiave (inizia con sk_live_ o simile) ☐ Nessun prefisso Bearer o virgolette attorno alla chiave ☐ La variabile d’ambiente è impostata e caricata ☐ La richiesta viene inviata dal server, non dal browser ☐ La chiave è attiva in Impostazioni → API ☐ Il metodo di pagamento è aggiunto e valido Se i problemi persistono, contatta l’assistenza per sviluppatori con: Il messaggio di errore Le ultime 4 cifre della tua chiave API Linguaggio di programmazione e framework Esempio di codice (senza esporre la tua chiave completa)

Question 11

Parametri di ricerca disponibili

Accepted Answer

L’endpoint /resources accetta diversi parametri per affinare i risultati della tua ricerca. Ricerca di base POST https://api.cathopic.com/resources { "query": "San Francesco", "page": 1, "page_size": 20, "order": "popular" } Parametri query (string, opzionale) Il termine di ricerca. Lascia vuoto per ottenere tutte le risorse. Esempi: "Vergine Maria", "Eucaristia", "croce" Supporta il matching fuzzy e la tolleranza per gli errori di battitura Cerca tra titoli, descrizioni e tag page (integer, predefinito: 1) Quale pagina dei risultati restituire. Inizia da 1. page_size (integer, predefinito: 20, max: 100) Numero di risultati per pagina. Il massimo è 100 per mantenere le prestazioni. order (string, predefinito: "popular") Come ordinare i risultati: popular - Prima le risorse più scaricate recent - Prima i caricamenti più recenti Struttura della risposta { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Titolo della risorsa", "description": "Descrizione della risorsa", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Esempi pratici Ottieni le prime 10 risorse più popolari sulla preghiera: { "query": "preghiera", "page": 1, "page_size": 10, "order": "popular" } Ottieni i caricamenti recenti, senza un termine di ricerca specifico: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Sfoglia la pagina 3 di immagini sui santi: { "query": "santi", "page": 3, "page_size": 20, "order": "popular" } Per un riferimento completo dell’API, visita api.cathopic.com/docs.

Question 12

Come scaricare immagini tramite API?

Accepted Answer

Chiarimento importante: l’API non consente il "download" nel senso tradizionale. Invece, fornisce URL permanenti a contenuti ottimizzati per il web che la tua applicazione serve agli utenti finali. Questo è disciplinato dalla nostra API License Agreement. NON scarichi file L’API Cathopic funziona in modo fondamentalmente diverso dai download tradizionali: Nessun trasferimento di file: non ricevi né memorizzi mai i file effettivi di immagine/video Accesso tramite URL: l’API fornisce URL che puntano a contenuti ospitati da Cathopic Solo ottimizzati per il web: i contenuti vengono serviti con una risoluzione adatta alla visualizzazione digitale Nessun file originale: gli originali ad alta risoluzione non sono mai accessibili tramite API Sempre ospitati: i contenuti restano sui server di Cathopic o su una CDN autorizzata Risoluzioni disponibili L’API fornisce tre dimensioni ottimizzate per il web: Small: adatte per miniature e piccoli embed (tipicamente ~400px di larghezza) Medium: adatte per contenuti web standard (tipicamente ~800px di larghezza) Large: qualità migliore per la visualizzazione web (tipicamente ~1200px di larghezza) Restrizioni critiche: I file originali ad alta risoluzione NON vengono MAI forniti Le risoluzioni sono ottimizzate per la visualizzazione su schermo, non per la stampa Le dimensioni dei file sono compresse per una consegna web veloce Non puoi richiedere risoluzioni personalizzate o qualità originale Per i termini completi, leggi l’API License Agreement e consulta la documentazione tecnica su api.cathopic.com/docs. Il download delle immagini prevede due passaggi: licenziare la risorsa con /confirm, quindi usare gli URL restituiti. Step 1: licenzia la risorsa Chiama /confirm per licenziare una risorsa per un utente finale specifico: POST https://api.cathopic.com/confirm x-api-key: YOUR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parametri: media_id - L’ID della risorsa dai risultati della tua ricerca usage_type - Sia "website" sia "email" client_identifier - ID univoco per il tuo utente finale Step 2: usa gli URL di download La risposta contiene URL permanenti in più formati: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Importante: memorizza gli URL Gli URL restituiti sono permanenti: salvali nel tuo database: // Dopo aver chiamato /confirm const response = await api.confirm(mediaId, userId); // Salva nel tuo database await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // La prossima volta, recupera dal DB invece di chiamare /confirm di nuovo Scegliere il formato giusto Formato AVIF: Dimensioni dei file più piccole (migliori prestazioni) Migliore compressione Consigliato per i browser moderni Non supportato nei browser più vecchi Formato JPEG: Compatibilità universale Dimensioni dei file più grandi Usalo come fallback per i browser più vecchi Promemoria critico ⚠️ Controlla sempre il tuo database prima di chiamare /confirm. Chiamarlo più volte per lo stesso utente e la stessa risorsa creerà addebiti duplicati. Documentazione completa su api.cathopic.com/docs.

Question 13

Gestione della paginazione e dell’ordinamento

Accepted Answer

L’API restituisce i risultati di ricerca a pagine. Ecco come navigare in modo efficiente tra grandi insiemi di risultati. Paginazione di base POST /resources { "query": "santi", "page": 1, "page_size": 20 } Risposta: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 elementi ... ] } La risposta ti dice che ci sono 1.523 risultati in totale e che stai visualizzando la pagina 1 con 20 elementi. Calcolo del numero totale di pagine const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 pagine Caricare la pagina successiva // Pagina successiva semplice currentPage++; // Oppure costruisci l’interfaccia di paginazione for (let page = 1; page <= totalPages; page++) { // Crea il pulsante della pagina } Ottimizzare la dimensione della pagina Scegli la dimensione della pagina in base al tuo caso d’uso: Pagine piccole (10-20 elementi): Caricamento iniziale più veloce Ideali per la ricerca rivolta agli utenti Richiedono più richieste all’API Pagine grandi (50-100 elementi): Meno richieste all’API Ideali per l’elaborazione in batch Richieste individuali più lente Il massimo è 100 elementi Opzioni di ordinamento Popolare (predefinito): { "order": "popular" } Restituisce prima le risorse scaricate di più. È la scelta migliore per mostrare contenuti di alta qualità, già validati. Recenti: { "order": "recent" } Restituisce prima i caricamenti più recenti. È utile per scoprire contenuti nuovi. Esempio di scorrimento infinito 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: 'preghiera', page: currentPage, page_size: pageSize, order: 'popular' }) }); const data = await response.json(); // Aggiungi i risultati alla tua UI appendResults(data.results); // Verifica se ci sono altre pagine const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Attiva allo scroll window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Consigli per le prestazioni Metti in cache i risultati localmente per evitare richieste ridondanti Usa dimensioni di pagina appropriate per il tuo caso d’uso Implementa stati di caricamento per una migliore esperienza utente Valuta la virtualizzazione per elenchi molto grandi Non caricare tutte le pagine insieme: carica su richiesta Per maggiori dettagli, consulta la documentazione completa su api.cathopic.com/docs.

Question 14

Come cercare nel catalogo e usare gli URL di anteprima di Cathopic

Accepted Answer

Usa GET /api/v2/catalog con catalog.read. Usa lo strato di ricerca fuzzy tollerante agli errori di battitura già esistente di Cathopic e carica gli stessi modelli canonici di contenuti multimediali usati dalla griglia del sito web. Parametri q oppure query: testo fino a 250 caratteri. type: foto, video, grafica, opera d’arte, ai, oppure tutti. orientation: orizzontale, verticale, quadrata, oppure tutti. sort: più_recente, popolare, oppure popolare_tutto_il_tempo. page, per_page fino a 50 e locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUsa gli URL di anteprima invariati Ogni risultato include preview.url e preview.transformation_url_template. Provengono esattamente dallo stesso presenter della griglia, dall’host CDN, dal percorso di storage e dalle regole di watermark usate su cathopic.com. Usali invariati così le integrazioni riutilizzano le chiavi di cache esistenti di Cloudflare. Non caricare un’altra copia o farne da proxy inutilmente. Non aggiungere parametri di query per forzare la cache. Sostituisci <OPTIONS> solo con opzioni immagine Cloudflare stabili. Le anteprime non consumano mai un download. already_licensed include le autorizzazioni individuali e del team condiviso.

Question 15

Come licenziare e scaricare una risorsa in modo sicuro

Accepted Answer

La creazione della licenza e la creazione dell’URL originale sono separate, così i retry sono sicuri e gli URL freschi non vengono mai addebitati di nuovo. 1. Crea la licenza POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Usa una chiave univoca di 8 fino a 160 caratteri ASCII stampabili per il tentativo di selezione logica e conservala quando riprovi. Una nuova licenza restituisce 201; un replay idempotente restituisce 200 con lo stesso ID della licenza. Cathopic verifica prima l’originale. In una singola transazione blocca l’abbonamento individuale o del team, controlla l’accesso ai contenuti e le eventuali quote condivise esistenti, consuma al massimo un download e registra l’entitlement, la cronologia e la licenza. 2. Richiedi l’URL originale POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENL’URL scade dopo cinque minuti. Richiedi un nuovo URL per un nuovo download; non crearne un’altra. Cathopic ricava il percorso di archiviazione e non accetta mai un percorso arbitrario. Errori importanti subscription_required: nessun accesso a pagamento attivo. media_type_not_in_plan: tipo non incluso. download_balance_exhausted: non restano download con piano limitato. file_unavailable: originale mancante; nessun addebito. idempotency_key_conflict: la chiave è stata usata per un altro ID media. Conserva il X-Request-Id per l’assistenza, ma non registrare mai token, segreti o URL firmati. Dopo risposte 429 o transienti 5xx, fai un backoff con jitter.

Question 16

Guida rapida OAuth 2.0 per le app connesse Cathopic

Accepted Answer

Le App Connesse Cathopic usano OAuth 2.0 Authorization Code con PKCE S256 obbligatorio. La stessa approvazione dello sviluppatore sblocca anche la API commerciale di Cathopic, ma le connessioni OAuth usano i token dell’utente e il piano dell’utente connesso, invece delle chiavi API e della fatturazione a consumo della API. 1. Ottenere accesso e registrare l’applicazione Invia la singola richiesta di accesso per sviluppatori tramite il modulo di contatto. Dopo che Cathopic approva l’account via email, apri Impostazioni → Developer / API → applicazioni OAuth, crea l’applicazione, registra i suoi callback esatti e gli scope richiesti, e salva il suo segreto una tantum se è riservata. 2. Scoprire il server di autorizzazione GET https://cathopic.com/.well-known/oauth-authorization-server3. Reindirizzare l’utente 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=enCostruisci un singolo URL; gli a capo servono solo a rendere l’esempio leggibile. Genera nuovi valori di state ad alta entropia e PKCE per ogni tentativo. ui_locales è opzionale e può richiedere una lingua supportata come en oppure es. Se è richiesto l’accesso, Cathopic riprende la stessa richiesta di autorizzazione e poi mostra la schermata delle autorizzazioni. 4. Validare il callback e scambiare il codice Confronta lo state restituito prima di scambiare il codice. L’URI di reindirizzamento deve corrispondere byte per byte. 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=VERIFIERLe applicazioni pubbliche omettono client_secret. Salva i token e i segreti riservati solo sul server e crittografali a riposo. I token di accesso durano 30 minuti; i token di refresh durano fino a 30 giorni e vengono ruotati quando vengono usati. Controlli comuni Un callback rifiutato di solito differisce dall’URI registrato per schema, host, porta, percorso, maiuscole/minuscole o barra finale. invalid_request prima del consenso significa che PKCE S256, la challenge o lo state sono mancanti o non validi. invalid_grant di solito significa che un codice o un token di refresh ruotato è stato riutilizzato, oppure che il callback o il verifier sono cambiati. Dopo un 401, aggiorna una volta; se l’aggiornamento fallisce, chiedi all’utente di riconnettersi. Un 403 significa che il token non dispone dello scope richiesto. Vedi il contratto OpenAPI completo e la guida dettagliata all’integrazione delle Connected Apps.

Question 17

Come collego Cathopic a un’altra applicazione?

Accepted Answer

Una piattaforma approvata può consentirti di usare il catalogo di Cathopic senza ricevere la tua password. Invia il tuo browser a una pagina sicura su cathopic.com, dove accedi e rivedi le autorizzazioni esatte richieste. Collega il tuo account Nell’altra applicazione, scegli il suo connettore Cathopic e fai clic su Collega oppure Accedi con Cathopic. Conferma che il browser sia su cathopic.com. Accedi a Cathopic se necessario. Cathopic torna alla stessa richiesta di autorizzazioni invece di aprire il tuo profilo. Leggi tutte le autorizzazioni. Possono includere l’identità dell’account, l’accesso al catalogo, il saldo dell’abbonamento o la possibilità di concedere in licenza risorse. Scegli Consenti l’accesso. Cathopic ti rimanda solo alla callback esatta registrata per quella applicazione. Lingua e sicurezza dell’account L’applicazione può richiedere una lingua supportata per le schermate di accesso e autorizzazioni. Cathopic mantiene quella lingua durante tutta la connessione. L’applicazione riceve token a breve durata, mai la tua password, e può eseguire solo le azioni elencate nella schermata di autorizzazione. Se non ti fidi della richiesta Scegli Annulla. Non approvare la connessione se l’applicazione è sconosciuta, le autorizzazioni sembrano non necessarie oppure il browser non mostra il dominio di Cathopic. Puoi revocare l’accesso in un secondo momento da Impostazioni → Developer / API → App connesse.

Question 18

Le app connesse usano i miei download e come posso disconnetterle?

Accepted Answer

La ricerca e la visualizzazione di anteprime con filigrana non consumano alcun download. Un download può essere consumato solo quando un’applicazione connessa chiede a Cathopic di concedere in licenza una risorsa a pagamento. Quando viene consumato un download La risorsa è a pagamento, il piano include il suo tipo e né tu né l’abbonamento del team attuale l’hanno mai concessa in licenza in precedenza. Il piano ha un saldo limitato. I piani illimitati registrano la licenza senza ridurre un numero. Il file originale è disponibile. Cathopic lo verifica prima di modificare il saldo. Quando non viene consumato alcun download aggiuntivo La risorsa è gratuita. Tu o un altro membro che usa lo stesso abbonamento del team l’ha già concessa in licenza. Richiedi un nuovo link di download per una licenza esistente. L’applicazione riprova la stessa richiesta con la stessa chiave di idempotenza. I membri del team consumano il saldo condiviso del proprietario del team. Cathopic è sempre la fonte di verità. Disconnetti un’applicazione Apri Impostazioni → Sviluppatore / API → App connesse. Esamina l’applicazione e le sue autorizzazioni. Fai clic Disconnetti e conferma. Tutti i token di accesso e di aggiornamento attivi per quell’applicazione vengono revocati immediatamente. Le licenze esistenti e la cronologia dei download restano.

Question 19

Codici di errore comuni dell’API

Accepted Answer

Comprendere le risposte di errore ti aiuta a risolvere i problemi rapidamente. Ecco i più comuni errori che potrai incontrare. 400 Bad Request { "error": "media_id is required" } Cause: Parametro obbligatorio mancante Formato del parametro non valido JSON malformato Soluzione: Verifica che il corpo della tua richiesta corrisponda alla specifica dell’API su api.cathopic.com/docs. 401 Unauthorized { "message": "Unauthorized" } or { "error": "Unauthorized token" } Cause: Chiave API mancante o non valida Chiave API disattivata Nome dell’header errato Soluzione: Verifica che l’header x-api-key sia corretto e che la chiave sia attiva in Impostazioni → API. 404 Not Found { "error": "No file found for media_id 1234" } or { "error": "Media item not found" } Cause: La risorsa non esiste La risorsa è stata eliminata media_id errato Soluzione: Verifica che il media_id esista cercando prima con /resources. 429 Too Many Requests { "error": "Limit exceed." } Cause: Troppe richieste in un breve periodo Limite di richieste superato Soluzione: Implementa un backoff esponenziale. Attendi e riprova aumentando i ritardi (1s, 2s, 4s, ecc.). 500 Internal Server Error { "error": "Internal server error" } Cause: Problema temporaneo del server Condizione imprevista Soluzione: Attendi un momento e riprova. Se il problema persiste, contatta support. Esempio di gestione degli errori 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; } } Per errori persistenti, consulta la documentazione completa dell’API oppure contatta il supporto.

Question 20

Errori di limitazione del numero di richieste

Accepted Answer

Se vedi 429 Too Many Requests, stai chiamando l’API troppo frequentemente. Ecco come gestirlo correttamente. L’errore HTTP 429 Too Many Requests { "error": "Limit exceed." } Perché succede Le limitazioni di velocità proteggono l’API da un uso eccessivo: Troppe richieste in un breve periodo Polling aggressivo o scraping Nessun ritardo tra le richieste Richieste concorrenti senza throttling Strategia di backoff esponenziale Il modo migliore per gestire le limitazioni di velocità è il backoff esponenziale: attendi più a lungo dopo ogni nuovo tentativo: 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'); } Prevenire le limitazioni di velocità Aggiungi ritardi tra le richieste: // Sbagliato: richieste a raffica for (const id of mediaIds) { await api.getResource(id); // Nessun ritardo } // Giusto: richieste con throttling for (const id of mediaIds) { await api.getResource(id); await sleep(500); // Ritardo di 500ms } Raggruppa le operazioni: // Elabora in batch da 10 con ritardi 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 tra i batch } } Usa la cache delle risposte: 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; } Cosa NON fare ❌ Riprova immediatamente senza ritardo ❌ Effettuare richieste in parallelo senza limiti ❌ Ignorare gli errori 429 ❌ Usare ritardi fissi e brevi (usa sempre il backoff esponenziale) Se i problemi persistono Contatta l’assistenza per gli sviluppatori se hai davvero bisogno di limiti di velocità più alti per il tuo caso d’uso. Fornisci dettagli su: La tua applicazione e il tuo caso d’uso Volume di richieste previsto Implementazione attuale (con backoff)

Question 21

Timeout e problemi di rete

Accepted Answer

I problemi di rete possono causare il fallimento delle richieste API. Ecco come gestire in modo appropriato i timeout e i problemi di connessione. Impostare timeout adeguati Imposta sempre dei timeout per evitare richieste bloccate: // JavaScript con 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('Richiesta scaduta dopo 30s'); } else { console.error('Errore di rete:', error); } throw error; } // Python con 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 secondi ) return response.json() except Timeout: print('Richiesta scaduta dopo 30s') raise except RequestException as e: print(f'Errore di rete: {e}') raise Errori di rete comuni Timeout di connessione: Impossibile stabilire la connessione al server Di solito è un problema di rete o del firewall Controlla la connessione a Internet Verifica che il firewall consenta HTTPS verso api.cathopic.com Timeout di lettura: Connessione stabilita ma nessuna risposta Il server potrebbe essere lento o sovraccarico Aumenta il timeout o riprova più tardi Errore di risoluzione DNS: Impossibile risolvere api.cathopic.com Problema del server DNS Riprova o controlla le impostazioni DNS Riprova con 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(`Tutti i ${maxRetries} tentativi non sono riusciti`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Tentativo ${attempt + 1} non riuscito. Riprovo tra ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Valori di timeout consigliati Timeout di connessione: 10 secondi Timeout di lettura: 30 secondi Ricerca /resources: 30 secondi /confirm licensing: 30 secondi Debug dei problemi di rete Usa curl per testare la connettività: # Test della connettività di base curl -v https://api.cathopic.com/resources # Test con timeout 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"}' Controlla: ✓ La risoluzione DNS di api.cathopic.com funziona ✓ La connessione SSL/TLS ha successo ✓ Ricezione della risposta HTTP ✓ Tempo di risposta ragionevole (<5s in genere) Se i problemi persistono, contatta support fornendo dettagli diagnostici di rete.

Question 22

Debugging delle richieste non riuscite

Accepted Answer

Quando le richieste non vanno a buon fine, un debugging sistematico aiuta a identificare rapidamente il problema. Abilita la registrazione dettagliata 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; } } Controlla prima queste cose 1. La chiave API è corretta: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. Il nome dell’header è esatto: // Deve essere in minuscolo 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Corretto 'X-API-Key': apiKey, // ✗ Errato 'api-key': apiKey, // ✗ Errato } 3. Il JSON è valido: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. La richiesta raggiunge il server: // Usa la scheda Network delle DevTools del browser oppure curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Errori comuni Content-Type errato: // ✗ Errato headers: { 'Content-Type': 'text/plain' } // ✓ Corretto headers: { 'Content-Type': 'application/json' } Non serializzare (stringify) il body: // ✗ Errato body: { query: 'test' } // ✓ Corretto body: JSON.stringify({ query: 'test' }) Usare GET invece di POST: // ✗ Tutti gli endpoint richiedono POST method: 'GET' // ✓ Corretto method: 'POST' Testa con una richiesta minima Riduci al minimo per isolare il problema: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Oggetto vuoto }); console.log(response.status); console.log(await response.json()); Se funziona, aggiungi gradualmente i parametri finché non si verifica l’errore. Confronta con un esempio funzionante Testa con curl per verificare la tua implementazione: 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}' Se curl funziona ma il tuo codice no, confronta gli header e il body esatti. Se sei ancora bloccato? Contatta l’assistenza per sviluppatori con: Messaggio di errore completo Header della richiesta (nascondi la tua chiave API completa) Body della richiesta Stato della risposta e body Linguaggio di programmazione e libreria HTTP Snippet di codice (senza esporre le credenziali)

Question 23

Come contattare l’assistenza per sviluppatori

Accepted Answer

Hai bisogno di aiuto per la tua integrazione API? Il nostro team di assistenza per sviluppatori è qui per aiutarti. Quando contattare l’assistenza Contattaci se riscontri: Problemi di autenticazione nonostante tu abbia seguito le guide Risposte di errore inattese Problemi di prestazioni o risposte lente Domande su fatturazione o utilizzo Necessità di limiti di velocità (rate limit) più alti Chiarimenti sui termini di licenza Aiuto per scenari di integrazione specifici Come contattarci Pagina di supporto: Visita cathopic.com/support e compila il modulo di contatto. Email (se fornita): Invia i dettagli direttamente all’indirizzo email dell’assistenza per sviluppatori indicato nel tuo dashboard API. Informazioni da includere Aiutaci ad aiutarti più velocemente fornendo: 1. Descrizione chiara del problema Cosa stai cercando di fare Cosa sta succedendo rispetto a ciò che ti aspetti Quando è iniziato il problema 2. Dettagli tecnici Linguaggio di programmazione e framework Libreria HTTP o SDK che stai utilizzando Ultime 4 cifre della tua chiave API Messaggi di errore (testo completo) Codici di stato HTTP 3. Esempio di codice (ripulito) // Rimuovi la tua chiave API completa! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Solo ultime 4 cifre 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Dettagli richiesta/risposta Header della richiesta Body della richiesta Stato della risposta Body della risposta Timestamp del problema Prima di contattare l’assistenza Prova prima queste opzioni per risparmiare tempo: Controlla la documentazione API Rivedi le domande in questa sezione di aiuto Testa con curl per isolare il problema Verifica che la tua chiave API sia attiva in Impostazioni → API Controlla che il tuo metodo di pagamento sia valido Tempo di risposta Ci impegniamo a rispondere alle richieste di assistenza per sviluppatori entro 24-48 ore nei giorni lavorativi. I problemi complessi potrebbero richiedere ulteriore tempo di analisi. Per problemi urgenti Se stai riscontrando un’interruzione critica in produzione: Contrassegna la tua richiesta di supporto come "Urgente" Fornisci l’email del tuo account per l’identificazione prioritaria Includi i dettagli dell’impatto (numero di utenti coinvolti, impatto sui ricavi, ecc.) Stato API Prima di segnalare un’interruzione, verifica se c’è un problema noto: Testa la connettività di base: curl https://api.cathopic.com/resources Controlla la nostra pagina di stato (se disponibile) Cerca annunci nel dashboard del tuo account Risorse aggiuntive Documentazione completa dell’API: api.cathopic.com/docs Dashboard dell’account: cathopic.com/settings/api Supporto generale: cathopic.com/support Informazioni sulla licenza: cathopic.com/legal/license Siamo qui per aiutarti a rendere la tua integrazione un successo!

Sviluppatore / API

Per iniziare

Chiavi API, fatturazione e sicurezza

Catalogo, ricerca e licenze

Applicazioni OAuth

App connesse

Risoluzione dei problemi