Question 1

Mi a Cathopic API?

Accepted Answer

Az API egy REST-alapú szolgáltatás, amely lehetővé teszi, hogy a Cathopic katolikus médiatárát közvetlenül beépítse alkalmazásaiba. Több ezer képhez, videóhoz és grafikához férhet hozzá programozott módon. Mit tehet Keresés és böngészés a teljes katalógusunkban Erőforrások licencelése az Ön végfelhasználói számára automatikusan Letöltés több formátumban, különböző felhasználási esetekhez optimalizálva Gazdag metaadatok elérése, beleértve a címkéket, leírásokat és liturgikus információkat REST architektúra Szabványos REST-elvek alapján készült: Alap URL: https://api.cathopic.com Adatformátum: JSON kérések és válaszok Hitelesítés: API-kulcs az x-api-key fejlécen keresztül HTTP metódus: POST az összes végponthoz Négy alapvető végpont POST /resources - Keresés a katalógusban POST /resource - Részletek lekérése egy adott elemről POST /confirm - Erőforrás licencelése és letöltési URL-ek lekérése POST /remove - Licenc leállítása, amikor már nincs rá szükség (csak weboldal) Teljes dokumentáció Minden, amire szüksége van, online elérhető: Interaktív API referencia: api.cathopic.com/docs Példák több programozási nyelven Részletes paraméter-specifikációk Hogyan kezdje el Vegye fel a kapcsolatot a csapatunkkal az API-hozzáférés igényléséhez Állítsa elő az API-kulcsát a Beállítások → API alatt Adjon meg egy fizetési módot a felhasználás alapú számlázáshoz Kezdje el az építést Tekintse meg a szakasz többi kérdését a hitelesítéssel, számlázással és a bevált gyakorlatokkal kapcsolatos részletekért. API Licencmegállapodás Az API minden használata a API Licencmegállapodásunk hatálya alá tartozik. A fontos tudnivalók: Csak digitális felhasználás: A tartalom kizárólag webes és e-mail környezetben jeleníthető meg Nincs fájlletöltés: A végfelhasználók nem tölthetik le vagy exportálhatják az eredeti fájlokat Tilos felhasználások: Az AI/ML betanítás, a nyomdai anyagok és az offline használat szigorúan tilos Felhasználás alapú számlázás: Csak a végfelhasználói által ténylegesen felhasznált tartalom után fizet Az API használatával elfogadja a licencmegállapodás összes feltételét Az API integrálása előtt: Tekintse át a teljes API Licencmegállapodást Ismerje meg a korlátozásokat és kötelezettségeket Győződjön meg arról, hogy az Ön felhasználási esete megfelel a csak digitális követelményeknek Tervezze meg az integrációt úgy, hogy a számlázáshoz pontosan nyomon tudja követni a felhasználást További részletekért lásd: Mit építhetek az API-val? (részletes korlátozásokat is tartalmaz) Hogyan működnek a licencek az API-n keresztül? (teljes licencelési részletek) Hogyan történik az API-használat számlázása? (a számlázási modell magyarázata)

Question 2

Mit építhetek az API-val?

Accepted Answer

A Cathopic API lehetővé teszi, hogy katolikus vizuális tartalmakat közvetlenül integrálj alkalmazásodba, weboldaladra vagy platformodra. Az API használata azonban szigorúan szabályozott a API Licencmegállapodás által, amely a felhasználást meghatározott digitális környezetekre korlátozza. Mit építhetsz Egyház- és plébániai irányítási rendszerek Lehetővé teszi, hogy a plébániák katolikus képeket adjanak a körleveleikhez és hírleveleikhez Lehetővé teszi az események népszerűsítését releváns vizuális tartalommal Olyan liturgikus képeket biztosít, amelyek illeszkednek az egyházi évhez Digitális kijelzőket hoz létre a plébániai közleményekhez Katolikus tartalomplatformok Blogolási platformok készítése katolikus szerzők számára, beépített képekkel Katolikus hírportálok létrehozása releváns vizuális elemekkel Devocionális alkalmazások fejlesztése napi képekkel és imákkal Kateketikai platformok tervezése vizuális taneszközökkel Email marketing eszközök Lehetővé teszi, hogy a lelkipásztori szolgálatok katolikus képekkel készítsenek hírleveleket Lehetővé teszi, hogy a vallási szervezetek email kampányokat tervezzenek Sablonok biztosítása beépített Cathopic-tartalommal Adománygyűjtő kampányok támogatása megfelelő vizuális elemekkel Weboldal-készítők és CMS Katolikus képek integrálása weboldal-készítő platformokba Tartalmi modulok biztosítása katolikus szervezetek számára Lehetővé teszi a Cathopic képek kiválasztását fogd és vidd módszerrel Kifejezetten katolikus lelkipásztori szolgálatokhoz készült sablonok létrehozása Esemény- és közösségi média menedzsment Segít a lelkipásztori szolgálatoknak közösségi média grafikai anyagokat készíteni (fájlok letöltése nélkül) Eseménymeghívó rendszerek tervezése katolikus képekkel Tartalomnaptárak felépítése liturgikus évszakok vizuális elemeivel Lehetővé teszi a szervezetek számára, hogy megfelelő képekkel ütemezzék a posztokat Fontos korlátozások, amelyeket be kell tartanod Az API Licenc szigorúan tilt bizonyos felhasználásokat. Ezen korlátozások megszegése azonnali megszüntetést vonhat maga után: ❌ AI/ML betanítás (ÖRÖKRE TILOS) Nem használható AI/ML modellek betanítására, finomhangolására vagy bármilyen AI/ML modellbe történő betáplálására Nem hozhat létre beágyazásokat (embeddings), adathalmazokat (datasets) vagy AI-hoz származtatott kivonatokat Ez a korlátozás határozatlan ideig fennmarad, még a megállapodás megszüntetése után is Minden gépi tanulási és mesterséges intelligencia formára vonatkozik ❌ Fájlletöltések és exportálás A végfelhasználók nem tölthetnek le vagy menthetnek el tartalmakat fájlként Nem biztosítható a „letöltés” vagy „exportálás” funkció A tartalomnak a Cathopicnál kell maradnia, vagy engedélyezett gyorsítótárban Csak webes optimalizálású URL-ek használhatók, nem az eredeti fájlok ❌ Nyomtatás és offline használat Nem használható nyomtatott anyagokban, brosúrákban vagy plakátokban Nincs offline reklám vagy fizikai termék Szabály szerint kizárólag digitális webes és email környezetekre korlátozva Nem építhető be olyan PDF-ekbe, amelyeket nyomtatásra szánnak ❌ Viszonteladás és továbbterjesztés Nem hozhatsz létre olyan termékeket, amelyek a Cathopic-tartalmat továbbértékesítik vagy újra terjesztik Nem hozhatsz létre stockfotó piactereket az API-nkkal Nem kínálhatod a tartalmat önálló termékként Be kell építeni egy nagyobb szolgáltatás részeként ❌ Módosítás és származékok Nem módosíthatod, nem alakíthatod át, és nem hozhatsz létre származékos műveket Nem alkalmazhatsz szűrőket vagy jelentős módosításokat A tartalmat az API által biztosított formában kell megjeleníteni Alapvető vágás és átméretezés megengedett az elrendezési célokhoz Csak webes és email környezetek Az API-n keresztül elért tartalom kizárólag a következőkben használható: Weboldalak: Nyilvános vagy privát webes oldalak Webalkalmazások: Böngészőalapú eszközök és platformok Email: Hírlevelek, kampányok és tranzakciós emailek Blogok: Online tartalomkezelő rendszerek Webes beágyazások: Ellenőrzött iframe vagy API-n keresztül szolgáltatott tartalom Fontos: A tartalmat kizárólag webes optimalizált felbontásban kell megjeleníteni. Az eredeti, nagy felbontású fájlok soha nem érhetők el az API-n keresztül. Technikai követelmények Az alkalmazásodnak: HTTPS-t kell használnia: Minden API-hívásnak és tartalomszolgáltatásnak biztonságosnak kell lennie Vízjel-kezelést kell megvalósítania: Vízjeles tartalommal kell kezdeni, és csak akkor kérj vízjel nélküli verziót, ha szükséges Az igénybevételt pontosan kell követnie: A számlázáshoz minden tartalomhasználatot naplózni kell A /confirm végpontot kell meghívnia: Amikor a végfelhasználó elköteleződik a tartalom használata mellett A /remove végpontot kell meghívnia: Amikor a tartalom már nincs használatban (leáll a számlázás) Meg kell akadályoznia a jogosulatlan hozzáférést: Védd az API-hitelesítő adataidat Be kell tartania a sebességkorlátokat: Kövesd a fiókodhoz beállított korlátokat Jogi kötelezettségeid Amikor integrálod az API-t, köteles vagy: Frissíteni a Felhasználási feltételeidet, hogy tájékoztasd a végfelhasználókat: A tartalom nem tölthető le, és nem használható az alkalmazásodon kívül A tartalom nem használható AI/ML célokra A tartalom a Cathopic és annak alkotói tulajdona A használatot számlázás és megfelelőség (compliance) céljából követjük Technikai vezérléseket kell bevezetni a megelőzéshez: Jobb gombos letöltések (ahol lehetséges) Az eredeti fájlok közvetlen URL-en keresztüli elérése Letöltést engedélyező böngészőbővítmények Használati naplókat kell fenntartani: Számlázási ellenőrzés Megfelelőségi auditok Vitarendezés Példák a megfelelőségi (kompatibilis) integrációkra ✅ Plébániai körlevélkészítő A plébániák digitális körleveleket hoznak létre katolikus képekkel A tartalom megjelenik a weboldalon és email hírlevelekben Nincs letöltési funkció biztosítva A számlázás plébániánként és képenként követi a használatot ✅ Lelkipásztori szolgálat email platform Vallási szervezetek email kampányokat terveznek Képek közvetlenül az emailekben jelennek meg API URL-ek segítségével A tartalommal elküldött emailek alapján történik a díjazás Nincs fájltárolás a végfelhasználók eszközein ✅ Katolikus CMS platform Weboldal-készítő beépített Cathopic-könyvtárral A felhasználók böngészik és kiválasztják a képeket az oldalaikhoz A tartalom beágyazása API-n keresztül szolgáltatott URL-ekkel történik Felhasználónként a használat napja alapján történik a díjazás Példák a tiltott integrációkra ❌ AI-alapú képgenerátor A Cathopic-tartalom használata AI modellek betanítására Adathalmazok létrehozása gépi tanuláshoz Hasonló képek generálása a tartalmunk alapján ❌ Nyomdai tervezőeszköz Lehetővé teszi a felhasználóknak, hogy nyomtatható plakátokat készítsenek Nagy felbontású nyomtatáshoz letöltést biztosít Nyomtatáshoz Cathopic-tartalmú PDF-eket hoz létre ❌ Stockfotó piactér A Cathopic-tartalom továbbértékesítése önálló termékként Származtatott stockfotó-gyűjtemények létrehozása A tartalom újraelosztása több ügyfélnek Mielőtt elkezdenél építeni Lényeges olvasnivaló: Tekintsd át a teljes API Licencmegállapodást Tanulmányozd a technikai dokumentációt itt: api.cathopic.com/docs Ismerd meg részletesen a számlázási modellt (lásd: Hogyan történik az API-használat számlázása?) Úgy tervezd meg az integrációt, hogy megfeleljen az összes korlátozásnak Ha kérdésed van, vedd fel velünk a kapcsolatot a support oldalon keresztül Ne feledd: Az API elérésével vagy használatával elfogadod az API Licencmegállapodás összes feltételét. A nem megfelelés azonnali megszüntetést és jogi következményeket vonhat maga után.

Question 3

Mik a korlátozások (rate limit)?

Accepted Answer

Jelenleg nem alkalmazunk szigorú, másodpercenkénti kérésekre vonatkozó korlátokat. Ugyanakkor elvárjuk a méltányos használatot annak érdekében, hogy mindenki számára megfelelő maradjon a szolgáltatás minősége. Jelenlegi megközelítés Ahelyett, hogy kemény korlátokat vezetnénk be, felelős használatra ösztönzünk: Ésszerűen oszd el a kéréseket Hibák esetén alkalmazz exponenciális visszalépést (exponential backoff) Cache-eld a válaszokat a felesleges, ismétlődő hívások elkerüléséhez Ha nagy forgalomra számítasz, vedd fel velünk a kapcsolatot Legjobb gyakorlatok Használj agresszív cache-t: Tárold el a keresési eredményeket a gyakori lekérdezésekhez A lekérés után tartsd helyben a média metaadatait Ne hívd meg többször ugyanarra a felhasználóra/erőforrásra a /confirm végpontot Futtasd együtt a műveleteket (batch): Csoportosítsd az összetartozó kéréseket Kis késleltetéseket alkalmazz a batch-ek között Korlátozd a párhuzamos kapcsolatokat (a 10–20 ésszerű) Kezeld a hibákat körültekintően: Implementálj újrapróbálási logikát exponenciális visszalépéssel Ne próbáld azonnal újra hiba esetén Rögzítsd a hibákat a monitorozáshoz Várható válaszidők /resources keresés: jellemzően 200–500 ms /resource részletek: 100 ms alatt /confirm licencelés: 300–800 ms Állítsd be az ügyfél oldali timeout-ot legalább 30 másodpercre, hogy a ritkán lassabb válaszokat is kezelni tudd. Ha elérsz korlátokat Egy 429 Too Many Requests hibát kapsz. Ilyenkor: // 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; } } } Monitorozd a használatodat Az API-tevékenységet itt követheted: Beállítások → API: Lásd az összes elküldött kérést Ellenőrizd az aktív licenc(ek)et Tekintsd át a használati trendeket Figyeld a szokatlan mintázatokat Nagyobb korlátokra van szükséged? Ha a jogos felhasználási eseted nagy kérésszámot igényel (>1M kérés/hónap), vedd fel csapatunkkal a kapcsolatot, hogy megbeszéljük: Az alkalmazásod és a forgalmi mintázatok Várható kérésszám Szükség esetén garantált sebességkorlátok

Question 4

Hogyan történik az API-használat díjszabása?

Accepted Answer

A Cathopic API egy „pay-as-you-go” (tényleges használat szerinti) díjszabási modellt alkalmaz, amely a végfelhasználók által ténylegesen felhasznált tartalom alapján kerül kiszámításra. A számlázási feltételek valamennyi esetben a API License Agreement (API licencmegállapodás) rendelkezései szerint alakulnak. Két számlázási modell A számlázás attól függ, hogyan fogyasztják a tartalmat a végfelhasználók: 1. Weboldalas használat (Days of Use modell) akkor alkalmazandó, amikor a tartalom weboldalakon, blogokban vagy webes alkalmazásokban jelenik meg naptári naponként kerül kiszámításra, amikor a végfelhasználó egy adott tartalmat elér Képlet: Összes Days of Use × (tárgyalt havi díj ÷ 30) A napi arányos számlázás biztosítja, hogy csak a tényleges használatért fizessen Külön kerül nyomon követésre végfelhasználónként és tartalmi elemenként 2. E-mailes használat (Per Email modell) akkor alkalmazandó, amikor a tartalom e-mail üzenetekbe kerül beágyazásra elküldött e-mail üzenetenként kerül felszámításra (nem címzettenként) egyszeri díj az adott e-mailhez tartozó tartalomért az API-hozzáférés beállítása során kerül tárgyalásra az ár A számlázás kezdete és vége A vízjellel ellátott tartalom ingyenes A tartalom kezdetben vízjellel jelenik meg A vízjeles előnézet nem generál díjakat Ideális arra, hogy a végfelhasználók el tudják böngészni a tartalmat, mielőtt elköteleződnének Tesztelési és próba célokra is használható A számlázás akkor indul, amikor a vízjelet eltávolítják A végfelhasználó úgy dönt, hogy a tartalmat vízjel nélkül használja Az alkalmazása meghívja a POST /confirm kérést, amely tartalmazza: media_id: A tartalom azonosítója usage_type: „website” vagy „email” client_identifier: A végfelhasználó egyedi azonosítója Az API visszaadja a végleges URL-eket a vízjel nélküli tartalomhoz A számlázás azonnal ettől a pillanattól kezdődik Ezektől az URL-eket és a használati adatokat el kell tárolnia a számlázás nyomon követéséhez A számlázás akkor áll le, amikor a tartalmat eltávolítják A végfelhasználó eltávolítja vagy abbahagyja a tartalom használatát Az alkalmazása meghívja a POST /remove kérést, amely tartalmazza: media_id: A tartalom azonosítója client_identifier: A végfelhasználó azonosítója Az adott konkrét használathoz tartozó számlázás leáll El kell törölnie a vízjel nélküli URL-eket az adatbázisából Példa weboldalas számlázásra Tegyük fel, hogy tárgyalt egy havi díjat a korlátlan tartalomhasználatra: Forgatókönyv: Az A plébánia a #12345-ös képet megjeleníti a honlapján 1. nap: Meghívja a /confirm kérést → a számlázás elindul 1–15. nap: A kép továbbra is a honlapon marad (15 days of use) 16. nap: A plébánia eltávolítja a képet, meghívja a /remove kérést → a számlázás leáll Kiszámítás: 15 nap × ( ÷ 30 nap) = Felszámítva: az adott konkrét használatra Ha a B plébánia ugyanazt a képet további 10 napig használja, azt külön nyomon követjük, és hozzáadódik a díjhoz. Példa e-mailes számlázásra Tegyük fel, hogy tárgyalt egy díjat --.05 / e-mail: Forgatókönyv: Egy szolgálat hírlevelet küld a #67890-es képpel Művelet: Meghívja a /confirm kérést a következővel: usage_type: "email" Eredmény: Egyszeri díj --.05 az adott e-mailhez Címzettek: Nem számít, hogy 100 vagy 10 000 embernek küldik Felszámítva: --.05 összesen (nem címzettenként) Havi számlázási felső korlátok A megállapodása tartalmazhat havi számlázási felső korlátokat: Megvédik Önt a váratlanul magas számláktól Amint eléri a felső korlátot, a további használat ingyenes lehet, vagy csökkentett díjjal történhet A konkrét felső korlát összegét az API-hozzáférés beállítása során tárgyalják meg Az összes végfelhasználó összesített havi díjaira vonatkozik Számlázás és fizetés Számlaküldési ütemezés A számlákat havonta, az adott hónap első 10 napján belül állítják ki Az előző hónap összes használatát lefedi A használat részletes bontása végfelhasználónként és tartalmi elemenként Az API-fiókjához tartozó e-mail címre kerül elküldésre Fizetési feldolgozás A fizetések kizárólag a Stripe-on keresztül kerülnek feldolgozásra Automatikus terhelés a regisztrált fizetési módra Mindig érvényes fizetési információkat kell fenntartania A sikeres fizetés után automatikusan megküldjük a nyugtákat Fizetési sikertelenségek Ha a fizetés sikertelen, a rendszer 4 alkalommal próbálkozik újra Ön e-mail értesítéseket kap a fizetési problémákról Ha az összes újrapróbálkozás sikertelen, az API-hozzáférés felfüggesztésre kerül A hozzáférés a sikeres fizetés után azonnal helyreáll Az esedékes, de ki nem fizetett számlák kamatot halmozhatnak fel Az Ön nyomonkövetési felelősségei Meg kell őriznie a következőkről a pontos nyilvántartást: Használati naplók: mikor lett a tartalom megerősítve és mikor lett eltávolítva Végfelhasználói azonosítók: mely felhasználók mely tartalmakat értek el Tartalomazonosítók: mely médiatartalmakat használták Használati típusok: weboldal vs. e-mail az egyes használatoknál Dátumok: a weboldalas használat kezdő- és befejező dátuma URL-ek: a folyamatban lévő használathoz tárolt vízjel nélküli URL-ek Ezek a naplók elengedhetetlenek a következőkhöz: A havi számlák ellenőrzése Számlázási viták rendezése A Cathopic által végzett megfelelőségi auditok Saját belső riportolásához Használati jelentések elérése Valós időben nyomon követheti az API-használatát: Menjen ide: Beállítások → API Tekintse meg a „On-demand usage” (igény szerinti használat) szakaszt Lássa az aktuális számlázási időszak statisztikáit: Az eddig felhalmozott teljes költség Weboldalas használatok száma E-mailes használatok száma Kattintson a „View detailed report” (részletes jelentés megtekintése) gombra a következők szerinti bontáshoz: Végfelhasználó (client identifier) Tartalmi elem Használati típus Dátumtartomány Egyedi költségek Jelentések exportálása CSV formátumban a nyilvántartásához Árak tárgyalása Az API árazása minden ügyfél számára egyedi: Az árakat az API-hozzáférés iránti kérelem folyamatában tárgyalják meg Az Ön várható használati volumenén alapul Az Ön konkrét felhasználási esetén és az integráció típusán alapul Magas használatú alkalmazások esetén tartalmazhat mennyiségi kedvezményeket Az előre kiszámítható költségek érdekében tárgyalhatók havi felső korlátok Az árak egyeztetéséhez: Keresse fel a támogatási oldalunkat Válassza az „API access request” (API-hozzáférés iránti kérelem) lehetőséget Ismertesse az integrációját és a várható használatot Csapatunk egyedi árajánlatot ad A teljes licenc megértése A számlázás csak egy része az API-megállapodásnak. Tekintse át a teljes feltételeket: Olvassa el a teljes API License Agreement (API licencmegállapodás) dokumentumot Ismerje meg a használati korlátozásokat (csak digitális, nincs AI/ML, nincs letöltés) Ismerje meg a nyomon követéssel és jelentéstétellel kapcsolatos kötelezettségeit Tekintse át a szellemi tulajdonra és a megszüntetésre vonatkozó rendelkezéseket A megvalósítás technikai részleteihez: Tekintse meg a /confirm és /remove végpontokat a api.cathopic.com/docs oldalon Értse meg, hogyan kell kiszámítani a használatot az adott integrációja alapján Tekintse át a pontos számlázás nyomon követésének bevált gyakorlatait Ne feledje: A pontos használat nyomon követése az Ön felelőssége. Tartson részletes naplókat annak érdekében, hogy a számlázás és a licencmegállapodással való megfelelés helyes legyen.

Question 5

Hogyan kérj fejlesztői hozzáférést az API-hoz és az OAuth-hoz

Accepted Answer

A Cathopic egyszer felülvizsgál egy fejlesztői fiókot. Ez az egyetlen jóváhagyás feloldja a kereskedelmi API-t és az OAuth alkalmazáskezelést is; nem kell külön kérelmeket benyújtani. A jóváhagyás után az API-kulcsokat és az OAuth-hitelesítő adatokat a Cathopic Beállításokban hozhatod létre és kezelheted. A fejlesztőknek soha nincs szükségük Cathopic-kiszolgálóparancsra vagy infrastruktúra-hozzáférésre. 1. Készítsd elő a Cathopic-fiókodat Hozz létre egy Cathopic-fiókot, ellenőrizd az e-mail címét, és győződj meg róla, hogy a kérésben szereplő felhasználónév és e-mail pontosan ugyanaz, mint az adott fiókban. 2. Küldd el a fejlesztői kérelmet Nyisd meg a Cathopic kapcsolatfelvételi űrlapot. Válaszd a Fejlesztői hozzáférés kérése. Erősítsd meg a Cathopic felhasználónevet, és írd le a terméket, a szervezetet, valamint a tervezett katalógushasználatot. Küldd el az űrlapot. A kérelem megjelenik a Cathopic belső felülvizsgálati irányítópultján. 3. Megkapod a döntést A Cathopic felülvizsgálja a fiókot és az alkalmazási esetet. Jóváhagyás esetén a fejlesztő e-mailt kap a következő lépésekkel, valamint egy hivatkozást a(z) Beállítások → Developer / API → OAuth alkalmazások. Ha további információra van szükség, a Cathopic felveszi a kapcsolatot a kérelemben megadott e-mail címen. 4. Hozd létre az alkalmazást Válassz titkos (confidential) webalkalmazást, ha a terméknek biztonságos háttérrendszere van, vagy nyilvános PKCE-alkalmazást böngészőben futó, mobil vagy asztali kliensekhez. Add meg a nyilvános nevét, leírását, weboldalát, adatvédelmi szabályzatát, biztonsági kapcsolattartót, a pontos visszahívási (callback) URL-eket, és csak azokat a scope-okat, amelyekre szüksége van. 5. Tárold a hitelesítő adatokat A client ID azonosítja az integrációt, és az adott termék összes felhasználója megkapja. A felhasználói engedélyezés és a tokenek minden egyes Cathopic-fiók esetén külön maradnak. A titkos client secretet csak egyszer jelenítjük meg, és azt az alkalmazás kiszolgálóján titkosítani kell. Soha ne tedd bele böngészőoldali kódba, generált weboldalakba, naplókba, ügyfélszolgálati üzenetekbe vagy nyilvános adattárba. Ugyanezen az oldalon a jóváhagyott fejlesztő szerkesztheti a callback-eket és a scope-okat, rotálhatja a titkos secretet, vagy visszavonhatja az alkalmazást.

Question 6

Hogyan működnek az API-kulcsok?

Accepted Answer

Az API-kulcsok az Ön hitelesítési adatai a Cathopic API eléréséhez. Annak megértése, hogy hogyan működnek, elengedhetetlen a biztonságos és hatékony API-integrációhoz. Mi az az API-kulcs? Az API-kulcs egy egyedi titkos token, amely azonosítja az alkalmazását, és feljogosítja a Cathopic API elérésére: Egy hosszú, betűkből és számokból álló karakterlánc (pl. sk_live_abc123xyz789...) Egyszerre szolgál hitelesítésre és jogosultságkezelésre A Cathopic-fiókjához és számlázásához van kötve Lehet aktív vagy inaktív A kulcsok életciklusa Létrehozás: Kulcsokat a Beállítások → API menüpontban generáljon Adjon minden kulcsnak leíró nevet ("Production Website", "Staging", "Mobile App") Azonnal másolja ki a teljes kulcsot – csak egyszer jelenik meg Tárolja biztonságosan (környezeti változók, secrets manager, jelszókezelő) Használat: Minden kérésnél vegye fel az x-api-key HTTP fejlécbe A kulcsokat a szerver oldalon ellenőrzik minden egyes kérésnél Az összes API-használat nyomon követésre kerül, és a fiókjához kerül számlázásra Inaktiválás: A kulcsok törlés nélkül ideiglenesen letilthatók Hasznos hibakereséshez vagy egy adott integráció szüneteltetéséhez Bármikor újraaktiválhatók Törlés: Véglegesen eltávolítja a kulcsot Nem vonható vissza, és nem állítható helyre Az ezzel a kulccsal küldött összes kérés azonnal sikertelen lesz Kulcskezelési irányelvek Biztonság: Soha ne mentse a kulcsokat verziókezelésbe: Használjon .env fájlokat, és adja hozzá őket a .gitignore-hoz Soha ne tegye ki ügyféloldali kódban: Az API-kulcsokat csak szerveroldalon szabad használni Használjon környezeti változókat: A kulcsokat a process.env.CATHOPIC_API_KEY vagy ennek megfelelő változóban tárolja Rendszeres rotáció: Időszakonként cserélje a kulcsokat (negyedévente vagy csapattag-váltás után) Külön kulcsok környezetenként: Külön kulcsok a fejlesztéshez, a staginghez és a produkcióhoz Szervezés: Leíró nevek: A kulcsokat a céljuk szerint nevezze el: "Production Website", "iOS App", "Email System" Tulajdonjog dokumentálása: Kövesse nyomon, hogy melyik csapattag hozta létre az egyes kulcsokat Rendszeres auditok: Tekintse át az aktív kulcsokat havonta, és távolítsa el a nem használtakat Több API-kulcs Különböző célokra több API-kulcsot is létrehozhat: Környezetenként: Külön kulcsok a fejlesztéshez, a staginghez és a produkcióhoz Alkalmazásonként: Külön kulcsok a weboldalhoz, a mobilalkalmazáshoz és a belső eszközökhöz Csapattagonként: Egyéni kulcsok a fejlesztőknek (könnyebb nyomon követni és visszavonni) A fiókja alatti összes kulcs ugyanahhoz a számlázáshoz tartozik. Az összes kulcsról származó használat összeadódik a havi számláján. Kulcshasználat figyelése Az egyes kulcsok aktivitását kövesse nyomon: Menjen a Beállítások → API menüpontba Tekintse meg az összes kulcs listáját az utoljára használt dátumokkal Kattintson egy kulcsra a részletes használati statisztikák megtekintéséhez Figyelje a szokatlan aktivitást Mit tegyen, ha egy kulcs kompromittálódott? Ha úgy gondolja, hogy egy API-kulcs nyilvánosságra került: Azonnal törölje vagy tiltsa le a kulcsot a Beállítások → API menüpontban Készítsen egy új, helyettesítő kulcsot Frissítse az alkalmazását az új kulccsal Ellenőrizze a használati naplókat bármilyen gyanús tevékenység miatt Ha jogosulatlan használatot lát, lépjen kapcsolatba a támogatással Példa: Kulcsok biztonságos tárolása Node.js környezeti változókkal: // .env fájl (add hozzá a .gitignore!-hoz!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // A kódja 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 környezeti változókkal: 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

Hogyan hitelesítem a kéréseket?

Accepted Answer

A Cathopic API-hoz intézett minden kérést hitelesíteni kell az API-kulcsoddal. Így kell helyesen hitelesíteni az API-hívásaidat. Hitelesítési módszer A Cathopic API API-kulcsos hitelesítést használ HTTP-fejléceken keresztül: Fejléc neve: x-api-key Fejléc értéke: A teljes API-kulcsod Szükséges ehhez: Az összes API-végpont Kis- és nagybetűre érzékeny: A fejlécneveknek és az értékeknek pontosan egyezniük kell Alap hitelesítési példa 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); ?> Hitelesítési hibák Ha a hitelesítés sikertelen, hibaüzenetet kapsz: Hiányzó API-kulcs: HTTP 401 Unauthorized { "message": "Unauthorized" } Érvénytelen API-kulcs: HTTP 401 Unauthorized { "message": "Unauthorized" } Inaktív API-kulcs: HTTP 401 Unauthorized { "error": "Unauthorized token" } Fontos emlékeztetők Biztonság: Soha ne kódold be a kulcsokat: Használj környezeti változókat vagy biztonságos beállítást Csak szerveroldalon: Soha ne tegyél API-kulcsokat kliensoldali JavaScriptbe Csak HTTPS-t használj: A HTTP-n keresztül továbbított API-kulcsok sebezhetőek Rendszeres rotáció: Biztonság érdekében időnként cseréld a kulcsokat Hibakezelés: Ellenőrizd az állapotkódokat: Mindig ellenőrizd a HTTP-válasz állapotát Hitelesítési hibák naplózása: Kövesd a sikertelen próbálkozásokat biztonsági megfigyeléshez Újrapróbálkozási logika bevezetése: Átmeneti hibák esetén exponenciális backoff-fal Előzetes ellenőrzés küldés előtt: Győződj meg róla, hogy az API-kulcs helyesen van betöltve Hitelesítés tesztelése Gyors teszt annak ellenőrzésére, hogy az API-kulcsod működik-e: 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}' Várt válasz (siker): { "total": 1234, "page": 1, "page_size": 1, "results": [ ... ] } Gyakori hibák Helytelen fejlécnév: A következő kell legyen: x-api-key, nem pedig api-key vagy Authorization Helytelen értékformátum: Használd a teljes kulcsot változtatás nélkül, ne tegyél elé "Bearer" előtagot Záró szóköz: Használat előtt vágd le az API-kulcs értékéből a felesleges szóközöket A kulcs nincs betöltve: Ellenőrizd, hogy a környezeti változó helyesen van-e beállítva Hitelesítési problémák elhárításához lásd ebben a szakaszban a "Gyakori hitelesítési hibák" című részt.

Question 8

Hogyan forgassak (rotáljak) API-kulcsot?

Accepted Answer

Az API-kulcsok rendszeres rotálása fontos biztonsági gyakorlat. Így tudod biztonságosan rotálni a kulcsaidat anélkül, hogy megzavarnád a szolgáltatásodat. Miért rotálj API-kulcsokat? Biztonsági alapelv: Korlátozza az expozíciót, ha egy kulcs valaha kompromittálódik Csapatváltozások: Amikor fejlesztők kilépnek vagy szerepkört váltanak Gyanús kompromittálódás: Ha úgy gondolod, hogy egy kulcs nyilvánosságra kerülhetett Megfelelőség (compliance): Egyes biztonsági irányelvek időszakos kulcsrotálást írnak elő Környezetváltás: Amikor infrastruktúrát migrálsz vagy refaktorálsz Szokásos rotálási folyamat (kiesés nélkül) 1. lépés: Hozz létre egy új kulcsot Lépj be a Beállítások → API menüpontba Kattints a "Új API-kulcs létrehozása" gombra Adj neki leíró nevet (pl. "Production Web v2") Másold ki az új kulcsot azonnal – csak egyszer jelenik meg Tárold biztonságosan 2. lépés: Frissítsd az alkalmazásodat Telepítsd az új kulcsot az alkalmazásodba (környezeti változók, secrets manager stb.) Indítsd újra az alkalmazásodat, hogy betöltse az új kulcsot Ellenőrizd, hogy az új kulcs megfelelően működik Figyeld az esetleges hibákat 3. lépés: Kövesd átmenetet Ideiglenesen tartsd mindkét kulcsot aktívan Nézd meg a Beállítások → API oldalon a "Last used" (Legutóbb használt) dátumokat Várj, amíg a régi kulcsnál nem látszik legutóbbi aktivitás Győződj meg róla, hogy minden példány/szolgáltatás az új kulcsra váltott 4. lépés: Töröld a régi kulcsot Miután megerősítetted, hogy a régi kulcs már nincs használatban Töröld vagy deaktiváld a régi kulcsot a Beállítások → API menüpontban Dokumentáld a rotálást a nyilvántartásaidhoz Gyors rotálási folyamat (ha kompromittálódott) Ha egy kulcs biztosan kompromittálódott, és azonnal lépned kell: Töröld először a kompromittált kulcsot a Beállítások → API menüpontban Hozz létre egy új, helyettesítő kulcsot Gyorsan telepítsd az új kulcsot az összes alkalmazásba Fogadj el rövid kiesést a jogosulatlan hozzáférés megelőzéséhez Figyeld a használati naplókat bármilyen gyanús tevékenység miatt Ha szükséges, vedd fel a kapcsolatot a támogatással Több környezetre kiterjedő rotálási stratégia Termelési (production) rendszereknél alkalmazz fázisolt megközelítést: 1. hét: Fejlesztés (Development) Hozz létre és telepítsd az új kulcsot a dev környezetbe Teszteld alaposan 2. hét: Staging Telepítsd az új kulcsot a staging környezetbe Futtass integrációs teszteket Figyeld a problémákat 3. hét: Termelés (Production) Telepítsd az új kulcsot a production környezetbe alacsony forgalmú időszakban Figyeld szorosan Tartsd a régi kulcsot aktívan 24–48 óráig visszaesési (fallback) lehetőségként 4. hét: Takarítás (Cleanup) Ellenőrizd, hogy a régi kulcsnál nincs aktivitás Töröld a régi kulcsot Frissítsd a dokumentációt Automatizálási példa Szkript, amely segít ellenőrizni, hogy a kulcsrotálás teljes: #!/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 Legjobb gyakorlatok Rotáld rendszeresen: Minden 90 napban a production kulcsoknál Dokumentáld a rotálásokat: Vezess naplót arról, mikor rotáltad a kulcsokat és miért Tesztelj törlés előtt: Mindig ellenőrizd, hogy az új kulcs működik, mielőtt eltávolítanád a régit Használj több kulcsot: Környezetenként külön kulcsokkal könnyebb a rotálás Automatizálj, ahol lehetséges: Használj secrets management eszközöket, amelyek támogatják az automatikus rotálást Rotálás utáni ellenőrzőlista A rotálás után erősítsd meg ezeket: ✅ Minden production példány az új kulcsot használja ✅ Minden staging/dev környezet frissítve van (ha ugyanazt a kulcsot használod) ✅ A környezeti változók frissítve vannak ✅ A CI/CD secrets frissítve vannak ✅ A dokumentáció frissítve van ✅ A csapattagok értesítve lettek ✅ A régi kulcs törölve lett ✅ A rotálás naplózva van audit célokra

Question 9

Hogyan biztosíthatom a hitelesítő adataimat?

Accepted Answer

Az API-kulcsai a Cathopic-fiókjának kapuja. Ha biztonságban tartja őket, megelőzheti a jogosulatlan hozzáférést, és védelmet nyújt a számlázási csalások ellen. Az aranyszabály: a kulcsok maradjanak titokban Az API-kulcsait úgy kezelje, mint a jelszavakat. Kerülendő gyakori hibák: A kulcsok beégetése közvetlenül a forráskódba A kulcsok elmentése Gitbe vagy más verziókezelő rendszerbe A kulcsok használata kliensoldali JavaScriptben vagy mobilalkalmazásokban Kulcsok megosztása e-mailben, Slacken vagy üzenetküldő alkalmazásokon keresztül A kulcsok nyilvános helyen tárolása (nyilvános repók, wikik stb.) Környezeti változók használata A kulcsokat a kódban tárolás helyett környezeti változókban tárolja: // .env fájl (add hozzá a .gitignore-hoz!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // A kódod require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Ezzel elkülöníti az érzékeny adatokat a kódbázistól, és megkönnyíti a kulcsok rotációját. Csak szerveroldalon Az API-hívásokat a háttérszervereiről kell indítani, nem böngészőkből vagy mobilalkalmazásokból. Ha a felhasználóknak hozzá kell férniük a Cathopic erőforrásaihoz: Hozzon létre egy olyan backend végpontot, amely a saját API-kulcsát használja A frontend a SAJÁT végpontját hívja, nem közvetlenül a Cathopicot A szervere érvényesíti a felhasználói kérést, mielőtt a Cathopicot hívná Korlátozás IP alapján (ha lehetséges) Néhány infrastruktúra lehetővé teszi az IP-címek engedélyezőlistáját (whitelist). Ha az API-hívásai ismert IP-címekről érkeznek: Állítson be tűzfal-szabályokat a kimenő hozzáférés korlátozására Használjon dedikált szolgáltatásfiókokat minimális jogosultságokkal Figyelje a hozzáférési naplókat a szokatlan tevékenységekért Ha egy kulcs kompromittálódott Ha azt gyanítja, hogy egy kulcs nyilvánosságra került: Azonnal hozzon létre egy új API-kulcsot Frissítse az alkalmazását az új kulccsal Törölje a kompromittálódott kulcsot Ellenőrizze a felhasználási naplókat gyanús tevékenységek után Vegye fel a kapcsolatot a támogatással, ha jogosulatlan terheléseket lát A kulcsait biztonságosan kezelheti itt: Beállítások → API.

Question 10

Gyakori hitelesítési hibák

Accepted Answer

Ha gondot okoz a Cathopic API-val történő hitelesítés, az alábbiak a leggyakoribb hibák, és a megoldásuk. 401 Unauthorized A leggyakoribb hitelesítési hiba: HTTP 401 Unauthorized { "message": "Unauthorized" } Gyakori okok: Hiányzik az x-api-key fejléc Érvénytelen vagy lejárt API-kulcs Elírás az API-kulcsban Szóköz a kulcs előtt/után A kulcs nincs betöltve környezeti változóból Hogyan javítsd: Ellenőrizd, hogy a fejléc neve pontosan x-api-key (kisbetű/nagybetű érzékeny) Másold ki újra az API-kulcsodat innen: Beállítások → API Ellenőrizd, hogy a környezeti változók betöltődnek: console.log(process.env.CATHOPIC_API_KEY) Vágd le a felesleges szóközöket: apiKey.trim() Ellenőrizd, hogy a kulcs aktív (nincs törölve vagy letiltva) Helytelen fejlécnév Az API a x-api-key-t igényli, nem más gyakori fejlécneveket: // ❌ HELYTELEN Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ HELYES x-api-key: sk_live_abc... Unauthorized token hiba HTTP 401 Unauthorized { "error": "Unauthorized token" } Ok: Az API-kulcsot letiltották vagy törölték. Hogyan javítsd: Ellenőrizd, hogy a kulcs még mindig aktív-e itt: Beállítások → API Ha letiltották, aktiváld újra a kulcsot Új kulcsot generálj, ha a régi törölve lett Nem betöltött környezeti változó A kódod nem találja az API-kulcsot: // undefined értéket ad vissza const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Hogyan javítsd: Node.js: // Győződj meg róla, hogy a .env be van töltve 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') Ügyféloldali (client-side) kitettségi hiba Próbálod az API-kulcsot böngészőben futó JavaScriptben használni: // ❌ Ez hibázni fog (a kulcsok nem működnek böngészőkben) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Hogyan javítsd: Hozz létre egy szerveroldali végpontot, amely proxyzza a kéréseket a Cathopic API felé. Lásd a "Hogyan biztosíthatom a hitelesítő adataimat?" részt példákért. CORS hibák Ha CORS hibákat látsz a böngésző konzoljában: Az Access to fetch blokkolva lett a CORS házirend miatt... Ok: Azt próbálod közvetlenül, ügyféloldali JavaScriptből meghívni, nem pedig szerverről. Hogyan javítsd: A Cathopic API csak szerveroldali. A kéréseket a saját backendeden keresztül kell proxyznod. Hitelesítés tesztelése Gyors teszt a beállítás ellenőrzéséhez: curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Nézd az HTTP 200 válasz státuszt # Ha 401, ellenőrizd alaposan a kulcsot Hibaelhárítási ellenőrzőlista Ha a hitelesítés továbbra is sikertelen: ☐ A fejléc neve x-api-key (kis- és nagybetű érzékeny) ☐ Az API-kulcs a teljes kulcs ( sk_live_-val vagy hasonlóval kezdődik) ☐ Nincs Bearer előtag, és nincs idézőjel a kulcs körül ☐ A környezeti változó be van állítva és be van töltve ☐ A kérés szerveroldalról megy, nem böngészőből ☐ A kulcs aktív itt: Beállítások → API ☐ A fizetési mód hozzá van adva és érvényes Ha a problémák továbbra is fennállnak, vedd fel a kapcsolatot a fejlesztői támogatással a következőkkel: A hibaüzenet Az API-kulcsod utolsó 4 számjegye Programozási nyelv és keretrendszer Példa kód (a teljes kulcs felfedése nélkül)

Question 11

Elérhető keresési paraméterek

Accepted Answer

A /resources végpont több paramétert is elfogad, amelyekkel pontosíthatja a keresési találatokat. Alap keresés POST https://api.cathopic.com/resources { "query": "Szent Ferenc", "page": 1, "page_size": 20, "order": "popular" } Paraméterek query (string, opcionális) A keresési kifejezés. Hagyja üresen az összes erőforrás megjelenítéséhez. Példák: "Szűz Mária", "Eucharisztia", "kereszt" Fuzzy egyezést és gépelési hibák tűrését is támogatja A címekben, leírásokban és címkékben keres page (egész szám, alapértelmezett: 1) Az eredmények melyik oldalát adja vissza. 1-től indul. page_size (egész szám, alapértelmezett: 20, max: 100) Eredmények száma oldalonként. A maximális érték 100, a teljesítmény fenntartása érdekében. order (string, alapértelmezett: "popular") Az eredmények rendezése: popular - Először a legtöbbször letöltött erőforrások recent - Először a legújabb feltöltések Válaszstruktúra { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Erőforrás címe", "description": "Erőforrás leírása", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Gyakorlati példák Az első 10 legnépszerűbb imádsággal kapcsolatos erőforrás lekérése: { "query": "imádság", "page": 1, "page_size": 10, "order": "popular" } Legutóbbi feltöltések lekérése, nincs konkrét keresési kifejezés: { "query": "", "page": 1, "page_size": 50, "order": "recent" } 3. oldal megtekintése a szentekről szóló képekből: { "query": "szentek", "page": 3, "page_size": 20, "order": "popular" } A teljes API-hivatkozásért látogasson el ide: api.cathopic.com/docs.

Question 12

Hogyan tölthetek le képeket API-n keresztül?

Accepted Answer

Fontos pontosítás: Az API nem teszi lehetővé a „letöltést” a hagyományos értelemben. Ehelyett tartós (permanens) URL-eket ad olyan, webre optimalizált tartalomhoz, amelyet az alkalmazásod a végfelhasználóknak szolgál ki. Ennek feltételeit a API License Agreement szabályozza. NEM töltesz le fájlokat A Cathopic API alapvetően másképp működik, mint a hagyományos letöltések: Nincs fájlátvitel: Soha nem kapod meg és nem tárolod a tényleges kép/videó fájlokat URL-alapú hozzáférés: Az API olyan URL-eket ad, amelyek a Cathopic által hosztolt tartalomra mutatnak Csak webre optimalizált: A tartalom olyan felbontásban kerül kiszolgálásra, amely digitális megjelenítésre alkalmas Nincsenek eredeti fájlok: A nagy felbontású eredetik soha nem érhetők el API-n keresztül Mindig hosztolt: A tartalom a Cathopic szerverein vagy egy engedélyezett CDN-en marad Elérhető felbontások Az API három webre optimalizált méretet biztosít: Kis méret: Alkalmas miniatűrökhez és kis beágyazásokhoz (jellemzően ~400 px széles) Közepes méret: Jó általános webes tartalomhoz (jellemzően ~800 px széles) Nagy méret: A legjobb minőség webes megjelenítéshez (jellemzően ~1200 px széles) Fontos korlátozások: A nagy felbontású eredeti fájlokkal SOHA nem szolgálunk A felbontások képernyőmegjelenésre vannak optimalizálva, nem nyomtatásra A fájlméretek tömörítettek a gyors webes kézbesítéshez Nem kérhetsz egyedi felbontásokat vagy eredeti minőséget A teljes feltételekért olvasd el a teljes API License Agreement dokumentumot, és tekintsd át a technikai dokumentációt itt: api.cathopic.com/docs. A képek letöltése két lépésből áll: a forrás licencelése a /confirm segítségével, majd a visszaadott URL-ek használata. 1. lépés: Licenceld a forrást Hívd meg a /confirm metódust egy adott végfelhasználó számára történő licenceléshez: POST https://api.cathopic.com/confirm x-api-key: YOUR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Paraméterek: media_id - A keresési találatokból származó forrásazonosító usage_type - „website” vagy „email” client_identifier - A végfelhasználód egyedi azonosítója 2. lépés: Használd a letöltési URL-eket A válasz több formátumban tartalmaz tartós URL-eket: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Fontos: Tárold az URL-eket A visszaadott URL-ek tartósak – tárold őket az adatbázisodban: // Miután meghívtad a /confirm-et const response = await api.confirm(mediaId, userId); // Tárold az adatbázisban await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Legközelebb az adatbázisból vedd ki, ne hívd meg újra a /confirm-et A megfelelő formátum kiválasztása AVIF formátum: Kisebb fájlméretek (jobb teljesítmény) Jobb tömörítés Ajánlott a modern böngészők számára Nem támogatott a régebbi böngészőkben JPEG formátum: Általános kompatibilitás Nagyobb fájlméretek Használd tartalékként a régebbi böngészők esetén Fontos emlékeztető ⚠️ Mindig ellenőrizd az adatbázisodat, mielőtt meghívnád a /confirm-et. Ha ugyanarra a felhasználóra és forrásra többször is meghívod, az duplikált díjakat eredményez. Teljes dokumentáció: api.cathopic.com/docs.

Question 13

Lapozás és rendezés kezelése

Accepted Answer

Az API a keresési találatokat lapokban adja vissza. Így navigálhatsz hatékonyan a nagy találati listák között. Alapvető lapozás POST /resources { "query": "saints", "page": 1, "page_size": 20 } Válasz: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 találat ... ] } A válasz megmutatja, hogy összesen 1 523 találat van, és éppen az 1. oldalt nézed 20 találattal. Az összes oldalszám kiszámítása const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 oldal Következő oldal betöltése // Egyszerű következő oldal currentPage++; // Vagy lapozó felület felépítése for (let page = 1; page <= totalPages; page++) { // Lap gomb létrehozása } Az oldalméret optimalizálása Válassz oldalméretet a felhasználási eseted alapján: Kis oldalak (10-20 találat): Gyorsabb kezdeti betöltés Jó felhasználói felületi kereséshez Több API-kérés szükséges Nagy oldalak (50-100 találat): Kevesebb API-kérés Jó kötegelt feldolgozáshoz Lassabb egyedi kérések Maximálisan 100 találat Rendezési lehetőségek Népszerű (alapértelmezett): { "order": "popular" } Először a legtöbbször letöltött erőforrásokat adja vissza. A legjobb a magas minőségű, bevált tartalmak megjelenítéséhez. Legutóbbi: { "order": "recent" } Először a legújabb feltöltéseket adja vissza. Jó a friss tartalmak felfedezéséhez. Végtelen görgetés példa 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(); // Eredmények hozzáadása a felhasználói felülethez appendResults(data.results); // Ellenőrzés, hogy vannak-e még oldalak const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Betöltés indítása görgetéskor window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Teljesítmény-tanácsok Cache-eld a találatokat helyben, hogy elkerüld a felesleges kéréseket Használj a felhasználási esetedhez illő oldalméreteket Alkalmazz betöltési állapotokat a jobb felhasználói élményért Nagyon nagy listáknál fontold meg a virtualizációt Ne tölts le egyszerre az összes oldalt – csak igény szerint További részletekért lásd a teljes dokumentációt itt: api.cathopic.com/docs.

Question 14

Hogyan keresd meg a katalógust, és hogyan használd a Cathopic előnézeti URL-eket

Accepted Answer

Használd GET /api/v2/catalog a catalog.readjogosultsággal. A Cathopic meglévő, elgépelés-tűrő fuzzy keresési rétegét használja, és ugyanazokat a weboldalrácson használt kanonikus médiamodelleket tölti fel. Paraméterek q vagy query: legfeljebb 250 karakteres szöveg. type: fotó, videó, grafika, alkotás, ai, vagy mindegyik. orientation: fekvő, álló, négyzet, vagy mindegyik. sort: legutóbbi, népszerű, vagy népszerű_alltime. page, per_page : legfeljebb 50, és locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENHasználd az előnézeti URL-eket változtatás nélkül Minden találat tartalmazza preview.url és preview.transformation_url_template. Ugyanabból a rácsmegjelenítőből, CDN-gazdagépből, tárolási útvonalból és vízjel-szabályokból származnak, amelyeket a cathopic.com-on használnak. Használd őket változtatás nélkül, hogy az integrációk újrahasznosítsák a meglévő Cloudflare cache-kulcsokat. Ne tölts fel egy másik példányt, és ne proxyzd feleslegesen. Ne adj hozzá cache-busztoló lekérdezési paramétereket. Cseréld <OPTIONS> csak stabil Cloudflare képes beállításokra. Az előnézetek soha nem fogyasztanak letöltést. already_licensed egyéni és megosztott csapatjogosultságokat is tartalmaz.

Question 15

Hogyan lehet biztonságosan licencelni és letölteni egy erőforrást

Accepted Answer

A licenc létrehozása és az eredeti URL létrehozása külön van választva, így az újrapróbálások biztonságosak, és a friss URL-ek soha nem számítanak fel újra. 1. Hozd létre a licencet POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Használj egyedi kulcsot 8 és 160 közötti nyomtatható ASCII karakterből a logikai kiválasztási kísérlethez, és tartsd meg újrapróbáláskor is. Az új licenc 201-et ad vissza; az idempotens újrajátszás 200-at ad vissza ugyanazzal a licenc-azonosítóval. A Cathopic először ellenőrzi az eredetit. Egyetlen tranzakcióban zárolja az egyéni vagy csapat-előfizetést, ellenőrzi a média-hozzáférést és a meglévő megosztott jogosultságokat, legfeljebb egy letöltést fogyaszt, és rögzíti a jogosultságot, az előzményeket és a licencet. 2. Kérd le az eredeti URL-t POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENAz URL öt perc után lejár. Új letöltéshez kérj új URL-t; ne hozz létre új licencet. A Cathopic a tárolási útvonalat származtatja, és soha nem fogad el tetszőleges útvonalat. Fontos hibák subscription_required: nincs aktív, fizetős hozzáférés. media_type_not_in_plan: a típus nincs benne. download_balance_exhausted: nincs több letöltés a korlátozott csomagban. file_unavailable: az eredeti hiányzik; nincs díj. idempotency_key_conflict: a kulcs egy másik médiaazonosítóhoz lett használva. Tartsd meg a X-Request-Id támogatáshoz, de soha ne naplózz tokeneket, titkokat vagy aláírt URL-eket. 429 vagy átmeneti 5xx válaszok esetén lépj vissza jitterrel.

Question 16

OAuth 2.0 gyorsútmutató Cathopic Connected Appokhoz

Accepted Answer

A Cathopic Connected Apps OAuth 2.0 Authorization Code-ot használ kötelező PKCE S256-tal. Ugyanez a fejlesztői jóváhagyás feloldja a Cathopic kereskedelmi API-ját is, de az OAuth-kapcsolatok felhasználói tokeneket és a kapcsolódó felhasználó csomagját használják az API-kulcsok és a méréses API-számlázás helyett. 1. Szerezzen hozzáférést és regisztrálja az alkalmazást A fejlesztői hozzáférés iránti egyetlen kérelmet küldje be a kapcsolati űrlapon keresztül. Miután a Cathopic e-mailben jóváhagyja a fiókot, nyissa meg Beállítások → Fejlesztő / API → OAuth alkalmazások, hozzon létre egy alkalmazást, regisztrálja a pontos callback-eket és a szükséges scope-okat, majd ha bizalmas, tárolja az egyszeri titkát. 2. Az engedélyezési szerver felfedezése GET https://cathopic.com/.well-known/oauth-authorization-server3. A felhasználó átirányítása 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=enKészítsen egyetlen URL-t; a sortörések csak az olvashatóságot szolgálják. Minden próbálkozáshoz generáljon új, nagy entrópiájú state és PKCE értékeket. ui_locales opcionális, és kérhet egy támogatott nyelvet, például en vagy es. Ha a bejelentkezés szükséges, a Cathopic folytatja ugyanazt az engedélyezési kérést, majd megjeleníti a jogosultsági képernyőt. 4. A callback érvényesítése és a kód kicserélése A kód kicserélése előtt hasonlítsa össze a visszakapott state-et. Az átirányítási URI-nak byte-ról byte-ra meg kell egyeznie. 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=VERIFIERA nyilvános alkalmazások kihagyják client_secret. A tokeneket és a bizalmas titkokat csak a szerveren tárolja, és nyugalmi állapotban titkosítsa. A hozzáférési tokenek élettartama 30 perc; a frissítési tokeneké legfeljebb 30 nap, és a felhasználáskor rotálni kell. Gyakori ellenőrzések A visszautasított callback általában a regisztrált URI-tól eltér a séma, a hoszt, a port, az útvonal, a kis- és nagybetűk vagy a záró perjel miatt. invalid_request a beleegyezés előtti azt jelenti, hogy a PKCE S256, a challenge vagy a state hiányzik, vagy érvénytelen. invalid_grant gyakran azt jelenti, hogy egy kód vagy egy rotált frissítési token újra lett felhasználva, vagy a callback vagy a verifier megváltozott. Egy 401 után frissítsen egyszer; ha a frissítés sikertelen, kérje meg a felhasználót, hogy csatlakozzon újra. A 403 azt jelenti, hogy a token nem rendelkezik a szükséges scope-pal. Tekintse meg a teljes OpenAPI szerződést és a részletes útmutatót a Connected Apps integrációhoz.

Question 17

Hogyan csatlakoztathatom a Cathopicot egy másik alkalmazáshoz?

Accepted Answer

A jóváhagyott platform lehetővé teszi, hogy a Cathopic katalógusát úgy használja, hogy nem kell megkapnia a jelszavát. A böngészőjét egy biztonságos oldalra irányítja itt: cathopic.com, ahol bejelentkezik, és áttekinti a kért jogosultságokat. Fiók csatlakoztatása A másik alkalmazásban válassza ki annak Cathopic csatlakozóját, majd kattintson Csatlakozás vagy Bejelentkezés Cathopic-kal. Erősítse meg, hogy a böngésző ezen van cathopic.com. Szükség esetén jelentkezzen be a Cathopicba. A Cathopic visszavisz ugyanarra a jogosultságkérésre, nem pedig a profilját nyitja meg. Olvassa el az összes jogosultságot. Ezek tartalmazhatják a fiókazonosságot, a katalógus elérését, az előfizetés egyenlegét vagy a források licencelésének lehetőségét. Válassza Hozzáférés engedélyezése. A Cathopic csak az adott alkalmazáshoz regisztrált pontos visszahívási (callback) címre küldi vissza. Nyelv és fiók biztonsága Az alkalmazás a bejelentkezési és jogosultsági képernyőkön támogatott nyelvet kérhet. A Cathopic ezt a nyelvet a teljes csatlakozás során megőrzi. Az alkalmazás rövid élettartamú tokeneket kap, soha nem a jelszavát, és csak a jogosultsági képernyőn felsorolt műveleteket tudja végrehajtani. Ha nem bízik a kérelemben Válassza Mégse. Ne hagyja jóvá a csatlakozást, ha az alkalmazás ismeretlen, a jogosultságok feleslegesnek tűnnek, vagy a böngésző nem a Cathopic domaint jeleníti meg. Később visszavonhatja a hozzáférést innen: Beállítások → Fejlesztő / API → Csatlakoztatott alkalmazások.

Question 18

A csatlakoztatott alkalmazások felhasználják a letöltéseimet, és hogyan tudom leválasztani őket?

Accepted Answer

A vízjellel ellátott előnézetek keresése és megjelenítése soha nem fogyaszt el letöltést. Letöltés csak akkor fogy el, amikor egy csatlakoztatott alkalmazás a Cathopicot arra kéri, hogy licenceljen egy fizetős erőforrást. Amikor egy letöltés felhasználásra kerül Az erőforrás fizetős, az előfizetés tartalmazza annak típusát, és sem Ön, sem a jelenlegi csapat előfizetése nem licencelte azt korábban. Az előfizetésnek korlátozott a kerete. A korlátlan csomagok a licencet úgy rögzítik, hogy nem csökkentenek egy darabszámot. Az eredeti fájl elérhető. A Cathopic ezt ellenőrzi, mielőtt módosítaná a keretet. Amikor nem fogy el további letöltés Az erőforrás ingyenes. Ön vagy egy másik csapattag ugyanazzal a csapat-előfizetéssel már korábban licencelte. Új letöltési linket kér egy meglévő licenchez. Az alkalmazás ugyanazzal az idempotencia-kulccsal újrapróbálja ugyanazt a kérést. A csapattagok a csapat tulajdonosának megosztott keretét használják fel. A Cathopic mindig az igazság forrása. Egy alkalmazás leválasztása Megnyitás Beállítások → Fejlesztő / API → Csatlakoztatott alkalmazások. Tekintse át az alkalmazást és annak jogosultságait. Kattintson Leválasztás és erősítse meg. Az adott alkalmazáshoz tartozó minden aktív hozzáférési és frissítési token azonnal visszavonásra kerül. A meglévő licencek és a letöltési előzmények megmaradnak.

Question 19

Gyakori API-hibaüzenetek

Accepted Answer

A hibaüzenetek megértése segít gyorsan elhárítani a problémákat. Íme a leggyakoribb hibák, amelyekkel találkozni fog. 400 Hibás kérés (Bad Request) { "error": "media_id is required" } Okok: Hiányzó kötelező paraméter Érvénytelen paraméterformátum Rossz formátumú JSON Javítás: Ellenőrizze, hogy a kéréstörzse megfelel-e az API-specifikációnak ezen a címen: api.cathopic.com/docs. 401 Jogosulatlan (Unauthorized) { "message": "Unauthorized" } vagy { "error": "Unauthorized token" } Okok: Hiányzó vagy érvénytelen API-kulcs Letiltott API-kulcs Helytelen fejlécnév Javítás: Ellenőrizze, hogy a x-api-key fejléc helyes-e, és a kulcs aktív-e a Beállítások → API alatt. 404 Nem található (Not Found) { "error": "No file found for media_id 1234" } vagy { "error": "Media item not found" } Okok: A forrás nem létezik A forrást törölték Helytelen media_id Javítás: Ellenőrizze, hogy a media_id létezik-e úgy, hogy először kereséssel ellenőrzi: /resources. 429 Túl sok kérés (Too Many Requests) { "error": "Limit exceed." } Okok: Túl sok kérés rövid idő alatt Átlépte a sebességkorlátot (rate limit) Javítás: Alkalmazzon exponenciális visszalépést (exponential backoff). Várjon, majd próbálja újra növekvő késleltetéssel (1s, 2s, 4s, stb.). 500 Belső szerverhiba (Internal Server Error) { "error": "Internal server error" } Okok: Ideiglenes szerverprobléma Váratlan körülmény Javítás: Várjon egy pillanatot, majd próbálja újra. Ha továbbra is fennáll, lépjen kapcsolatba a támogatással. Hiba kezelésének példa 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; } } Ha a hibák tartósan fennállnak, ellenőrizze a teljes API-dokumentációt, vagy lépjen kapcsolatba a támogatással.

Question 20

Sebességkorlátozási (rate limit) hibák

Accepted Answer

Ha 429 Too Many Requests üzenetet látsz, akkor túl gyakran hívod az API-t. Így kezeld ezt helyesen. Az error HTTP 429 Too Many Requests { "error": "Limit exceed." } Miért történik ez? A sebességkorlátok (rate limit) megvédik az API-t a túlzott használattól: Túl sok kérés rövid idő alatt Agresszív lekérdezés (polling) vagy adatgyűjtés (scraping) Nincs késleltetés a kérések között Párhuzamos kérések korlátozás (throttling) nélkül Exponenciális visszalépés (exponential backoff) stratégia A sebességkorlátok kezelésének legjobb módja az exponenciális visszalépés: minden újrapróbálkozás után egyre hosszabb várakozás: 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'); } A sebességkorlátok megelőzése Késleltess a kérések között: // Rossz: gyors egymásutáni kérések for (const id of mediaIds) { await api.getResource(id); // Nincs késleltetés } // Jó: korlátozott (throttled) kérések for (const id of mediaIds) { await api.getResource(id); await sleep(500); // 500ms késleltetés } Végezd kötegekben (batch): // Feldolgozás 10-as kötegekben késleltetésekkel 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 késleltetés a kötegek között } } Cache-eld (gyorsítótárazd) a válaszokat: 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; } Mit NE tegyél ❌ Azonnal újrapróbálkozás késleltetés nélkül ❌ Korlátlanul párhuzamos kérések indítása ❌ A 429-es hibák figyelmen kívül hagyása ❌ Fix, rövid késleltetések használata (mindig exponenciális backoff-ot használj) Ha továbbra is problémák vannak Ha a felhasználási esetedhez valóban magasabb sebességkorlátokra van szükséged, vedd fel a kapcsolatot a fejlesztői támogatással. Add meg a következő részleteket: Az alkalmazásod és a felhasználási eseted Az elvárt kérésszám Jelenlegi megvalósítás (backoff-fal)

Question 21

Időtúllépés és hálózati problémák

Accepted Answer

A hálózati problémák miatt az API-kérések sikertelenek lehetnek. Így kezeld az időtúllépéseket és a kapcsolódási gondokat kulturáltan. Megfelelő időtúllépések beállítása Mindig állíts be időtúllépést, hogy elkerüld a „beragadó” kéréseket: // JavaScript a fetch-sel 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('A kérés 30s után időtúllépett'); } else { console.error('Hálózati hiba:', error); } throw error; } // Python a requests-szel 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 másodperc ) return response.json() except Timeout: print('A kérés 30s után időtúllépett') raise except RequestException as e: print(f'Hálózati hiba: {e}') raise Gyakori hálózati hibák Kapcsolódási időtúllépés: Nem sikerül kapcsolatot létesíteni a szerverrel Leggyakrabban hálózati vagy tűzfal-probléma Ellenőrizd az internetkapcsolatot Ellenőrizd, hogy a tűzfal engedi-e a HTTPS-t a következőhöz: api.cathopic.com Olvasási időtúllépés: A kapcsolat létrejött, de nincs válasz A szerver lehet lassú vagy túlterhelt Növeld az időtúllépést, vagy próbáld újra később DNS-feloldási hiba: Nem sikerül feloldani az api.cathopic.com címet DNS-kiszolgáló probléma Próbáld újra, vagy ellenőrizd a DNS-beállításokat Újrapróbálkozás fokozatos várakozással (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(`Az összes ${maxRetries} próbálkozás sikertelen volt`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`A(z) ${attempt + 1}. próbálkozás sikertelen. Újrapróbálás ${waitTime} ms múlva...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Ajánlott időtúllépési értékek Kapcsolódási időtúllépés: 10 másodperc Olvasási időtúllépés: 30 másodperc /resources keresés: 30 másodperc /confirm licensing: 30 másodperc Hálózati problémák hibakeresése A kapcsolat teszteléséhez használd a curl-t: # Alap kapcsolat tesztelése curl -v https://api.cathopic.com/resources # Teszt időtúllépéssel 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"}' Ellenőrizd: ✓ Az api.cathopic.com feloldása (DNS) ✓ Az SSL/TLS kapcsolat sikeres ✓ HTTP válasz érkezik ✓ A válaszidő ésszerű (<5s általában) Ha a problémák továbbra is fennállnak, vedd fel a kapcsolatot a támogatással a hálózati diagnosztikai részletekkel.

Question 22

Hibás kérések hibakeresése

Accepted Answer

Ha a kérések sikertelenek, a módszeres hibakeresés segít gyorsan azonosítani a problémát. 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; } } Először ezeket ellenőrizze 1. Az API-kulcs helyes: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. A fejléc neve pontos: // A 'x-api-key' kisbetűsnek kell lennie headers: { 'x-api-key': apiKey, // ✓ Helyes 'X-API-Key': apiKey, // ✗ Rossz 'api-key': apiKey, // ✗ Rossz } 3. A JSON érvényes: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. A kérés eljut a szerverhez: // Használja a böngésző DevTools „Network” (Hálózat) lapját, vagy curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Gyakori hibák Rossz Content-Type: // ✗ Rossz headers: { 'Content-Type': 'text/plain' } // ✓ Helyes headers: { 'Content-Type': 'application/json' } Nem stringgé alakított body: // ✗ Rossz body: { query: 'test' } // ✓ Helyes body: JSON.stringify({ query: 'test' }) GET használata POST helyett: // ✗ Minden végpont POST-ot igényel method: 'GET' // ✓ Helyes method: 'POST' Próbálja ki minimális kéréssel Egyszerűsítse a lehető legkevesebbre, hogy elkülönítse a problémát: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Üres objektum }); console.log(response.status); console.log(await response.json()); Ha ez működik, fokozatosan adja vissza a paramétereket, amíg el nem kezd hibázni. Hasonlítsa össze egy működő példával Próbálja ki curl-lel, hogy ellenőrizze a megvalósítását: 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}' Ha curl működik, de a kódja nem, hasonlítsa össze a pontos fejléc(ek)et és a body-t. Még mindig elakad? Vegye fel a kapcsolatot a fejlesztői támogatással, és küldje el: Teljes hibaüzenet Kérés fejléc(ek) (rejtse el a teljes API-kulcsát) Kérés body Válasz státusza és body-ja Programozási nyelv és HTTP-könyvtár Kódrészlet (a hitelesítő adatok felfedése nélkül)

Question 23

Hogyan léphet kapcsolatba a fejlesztői támogatással

Accepted Answer

Segítségre van szüksége az API-integrációhoz? A fejlesztői támogatási csapatunk készen áll, hogy segítsen. Mikor érdemes kapcsolatba lépni a támogatással Forduljon hozzánk, ha a következők valamelyikét tapasztalja: Hitelesítési problémák, annak ellenére, hogy követte a leírásokat Váratlan hibaüzenetek Teljesítményproblémák vagy lassú válaszok Kérdései vannak a számlázással vagy a felhasználással kapcsolatban Magasabb sebességkorlátokra van szüksége Részletezésre van szükség a licencelési feltételekkel kapcsolatban Segítségre van szüksége konkrét integrációs helyzetekhez Hogyan léphet kapcsolatba velünk Támogatási oldal: Keresse fel a cathopic.com/support oldalt, és töltse ki a kapcsolatfelvételi űrlapot. Email (ha megadta): A részleteket közvetlenül küldje el a fejlesztői támogatásnak a saját API irányítópultján feltüntetett e-mail címére. Mit érdemes megadni Segítsen nekünk abban, hogy gyorsabban tudjunk segíteni az alábbiak megadásával: 1. A probléma egyértelmű leírása Mit szeretne elérni Mi történik a várakozásaihoz képest Mikor kezdődött a probléma 2. Technikai részletek Programozási nyelv és keretrendszer Az általunk használt HTTP-könyvtár vagy SDK Az API-kulcsának utolsó 4 számjegye Hibaüzenetek (teljes szöveg) HTTP állapotkódok 3. Kódpélda (megtisztítva) // Ne adja meg a teljes API-kulcsát! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Csak az utolsó 4 számjegy 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Kérés/válasz részletei Kérés fejléc(ek) Kérés törzse Válasz állapota Válasz törzse A probléma időpontja Mielőtt kapcsolatba lépne a támogatással Először próbálja ki ezeket, hogy időt takarítson meg: Ellenőrizze a API dokumentációt Tekintse át a súgó ezen részében található kérdéseket Teszteljen curl-lel a probléma elkülönítéséhez Ellenőrizze, hogy az API-kulcsa aktív a Beállítások → API alatt Ellenőrizze, hogy a fizetési mód érvényes Válaszidő Célunk, hogy a fejlesztői támogatási megkeresésekre munkanapokon belül 24–48 órán belül válaszoljunk. Összetett problémák további vizsgálati időt igényelhetnek. Sürgős esetek Ha kritikus, éles környezetet érintő kiesést tapasztal: Jelölje meg a támogatási kérését „Sürgős”-ként Adja meg a fiók e-mail címét a gyors azonosításhoz Tüntesse fel a hatás részleteit (az érintett felhasználók száma, bevételkiesés stb.) API állapot Mielőtt kiesést jelentene, ellenőrizze, hogy van-e ismert probléma: Alap kapcsolat tesztelése: curl https://api.cathopic.com/resources Ellenőrizze az állapotoldalunkat (ha elérhető) Keressen bejelentéseket az irányítópultján További erőforrások Teljes API dokumentáció: api.cathopic.com/docs Fiók irányítópult: cathopic.com/settings/api Általános támogatás: cathopic.com/support Licencinformáció: cathopic.com/legal/license Ott vagyunk, hogy segítsünk abban, hogy az integrációja sikeres legyen!

Fejlesztő / API

Kezdő lépések

API-kulcsok, számlázás és biztonság

Katalógus, keresés és licencelés

OAuth-alkalmazások

Csatlakoztatott alkalmazások

Hibaelhárítás