Question 1

Czym jest API Cathopic?

Accepted Answer

Nasze API to usługa REST, która pozwala zintegrować bibliotekę katolickich mediów Cathopic bezpośrednio z Twoimi aplikacjami. Uzyskaj programowo dostęp do tysięcy obrazów, wideo i grafik. Co możesz zrobić Wyszukiwać i przeglądać w ramach pełnego katalogu Automatycznie licencjonować zasoby dla Twoich użytkowników końcowych Pobierać w wielu formatach zoptymalizowanych pod różne zastosowania Uzyskiwać dostęp do bogatych metadanych, w tym tagów, opisów i informacji liturgicznych Architektura REST Zbudowane w oparciu o standardowe zasady REST: Adres bazowy: https://api.cathopic.com Format danych: żądania i odpowiedzi w formacie JSON Uwierzytelnianie: klucz API w nagłówku x-api-key Metoda HTTP: POST dla wszystkich endpointów Cztery kluczowe endpointy POST /resources - Wyszukiwanie w katalogu POST /resource - Pobieranie szczegółów dotyczących konkretnego elementu POST /confirm - Licencjonowanie zasobu i uzyskanie adresów URL do pobrania POST /remove - Zatrzymanie licencjonowania, gdy nie jest już potrzebne (tylko strona internetowa) Kompletna dokumentacja Wszystko, czego potrzebujesz, jest dostępne online: Interaktywna referencja API: api.cathopic.com/docs Przykłady kodu w wielu językach Szczegółowe specyfikacje parametrów Jak zacząć Skontaktuj się z naszym zespołem, aby poprosić o dostęp do API Wygeneruj swój klucz API w Ustawienia → API Dodaj metodę płatności do rozliczeń za użycie Rozpocznij budowanie Sprawdź pozostałe pytania w tej sekcji, aby uzyskać szczegóły dotyczące uwierzytelniania, rozliczeń i najlepszych praktyk. Umowa licencyjna API Wszelkie korzystanie z API podlega naszej Umowie licencyjnej API. Kluczowe punkty, które należy zrozumieć: Wyłącznie użycie cyfrowe: treści mogą być wyświetlane jedynie w środowiskach internetowych i e-mail Brak pobierania plików: użytkownicy końcowi nie mogą pobierać ani eksportować oryginalnych plików Zabronione zastosowania: szkolenie AI/ML, materiały drukowane oraz użycie offline są surowo zabronione Rozliczenia oparte na użyciu: płacisz tylko za faktyczne wykorzystanie treści przez Twoich użytkowników końcowych Korzystając z API, akceptujesz wszystkie warunki umowy licencyjnej Przed integracją API: Przeczytaj całą Umowę licencyjną API Zrozum ograniczenia i obowiązki Upewnij się, że Twoje zastosowanie jest zgodne z wymaganiami dotyczącymi użycia wyłącznie cyfrowego Zaplanuj integrację tak, aby dokładnie śledzić użycie na potrzeby rozliczeń Aby uzyskać więcej informacji, zobacz: Co mogę zbudować dzięki API? (zawiera szczegółowe ograniczenia) Jak działają licencje przez API? (pełne szczegóły licencjonowania) Jak rozliczane jest użycie API? (wyjaśnienie modelu rozliczeń)

Question 2

Co mogę zbudować za pomocą API?

Accepted Answer

Cathopic API pozwala zintegrować katolickie treści wizualne bezpośrednio z Twoją aplikacją, stroną internetową lub platformą. Jednak korzystanie z API jest ściśle regulowane przez nasze API License Agreement, które ogranicza użycie do określonych środowisk cyfrowych. Co możesz zbudować Systemy zarządzania parafią i Kościołem Umożliwienie parafiom dodawania katolickich obrazów do biuletynów i newsletterów Ułatwienie promocji wydarzeń dzięki odpowiednim treściom wizualnym Dostarczanie obrazów liturgicznych dopasowanych do kalendarza kościelnego Tworzenie cyfrowych wyświetlaczy do ogłoszeń parafialnych Platformy treści katolickich Budowanie platform blogowych dla katolickich autorów z zintegrowanymi obrazami Tworzenie katolickich serwisów informacyjnych z odpowiednimi wizualizacjami Opracowywanie aplikacji dewocyjnych z codziennymi obrazami i modlitwami Projektowanie platform katechetycznych z wizualnymi pomocami dydaktycznymi Narzędzia do marketingu e-mailowego Umożliwienie duszpasterstwom tworzenia newsletterów z katolickimi obrazami Ułatwienie organizacjom religijnym projektowania kampanii e-mailowych Dostarczanie szablonów z zintegrowanymi treściami Cathopic Wsparcie kampanii fundraisingowych odpowiednimi wizualizacjami Kreatory stron internetowych i CMS Integracja katolickich obrazów w platformach do budowania stron Dostarczanie modułów treści dla organizacji katolickich Włączanie wyboru obrazów metodą „przeciągnij i upuść” z Cathopic Tworzenie szablonów specjalnie dla duszpasterstw katolickich Zarządzanie wydarzeniami i mediami społecznościowymi Pomoc duszpasterstwom w tworzeniu grafik do mediów społecznościowych (bez pobierania plików) Projektowanie systemów zaproszeń na wydarzenia z katolickimi obrazami Budowanie kalendarzy treści z wizualizacjami okresu liturgicznego Umożliwienie organizacjom planowania postów z odpowiednimi obrazami Krytyczne ograniczenia, których musisz przestrzegać Licencja API ściśle zakazuje niektórych zastosowań. Naruszenie tych ograniczeń może skutkować natychmiastowym zakończeniem: ❌ Trening AI/ML (ZAKAZ PERMANENTNY) Nie można używać do trenowania, strojenia (fine-tuning) ani podawania jakichkolwiek modeli AI/ML Nie można tworzyć osadzeń (embeddings), zbiorów danych ani pochodnych wyciągów dla AI To ograniczenie obowiązuje bezterminowo, nawet po zakończeniu umowy Dotyczy wszystkich form uczenia maszynowego i sztucznej inteligencji ❌ Pobieranie plików i eksport Użytkownicy końcowi nie mogą pobierać ani zapisywać treści jako plików Nie można udostępniać funkcji „pobierz” ani „eksportuj” Treści muszą pozostać hostowane przez Cathopic lub w autoryzowanej pamięci podręcznej (cache) Można używać wyłącznie adresów URL zoptymalizowanych pod WWW, a nie oryginalnych plików ❌ Druk i użycie offline Nie można używać w materiałach drukowanych, broszurach ani plakatach Brak reklam offline ani produktów fizycznych Ściśle ograniczone do środowisk cyfrowych: WWW i e-mail Nie można włączać do plików PDF przeznaczonych do druku ❌ Odsprzedaż i redystrybucja Nie można tworzyć produktów, które odsprzedają lub redystrybuują treści Cathopic Nie można budować marketplace’ów ze zdjęciami stockowymi przy użyciu naszego API Nie można oferować treści jako samodzielnego produktu Treści muszą być zintegrowane jako część większej usługi ❌ Modyfikacje i utwory zależne Nie można zmieniać, przekształcać ani tworzyć utworów zależnych Nie można stosować filtrów ani istotnych modyfikacji Treści muszą być wyświetlane w postaci udostępnionej przez API Podstawowe kadrowanie i zmiana rozmiaru są dozwolone w celach układu Tylko środowiska WWW i e-mail Treści dostępne przez API mogą być wyłącznie używane w: Stronach internetowych: publicznych lub prywatnych stronach WWW Aplikacjach webowych: narzędzia i platformy działające w przeglądarce E-mail: newsletterach, kampaniach i e-mailach transakcyjnych Blogach: systemach zarządzania treścią online Osadzeniach webowych (web embeds): kontrolowane osadzenie w iframe lub treści dostarczane przez API Ważne: Treści muszą być wyświetlane wyłącznie w rozdzielczości zoptymalizowanej pod WWW. Oryginalne pliki w wysokiej rozdzielczości nigdy nie są dostępne przez API. Wymagania techniczne Twoja aplikacja musi: Używać HTTPS: wszystkie wywołania API i dostarczanie treści muszą być bezpieczne Wdrożyć obsługę znaków wodnych: zacznij od treści ze znakiem wodnym, a treści bez znaku wodnego zamawiaj tylko wtedy, gdy jest to potrzebne Dokładnie śledzić użycie: rejestruj całe użycie treści na potrzeby rozliczeń Wywołać endpoint /confirm: gdy użytkownik końcowy zobowiąże się do korzystania z treści Wywołać endpoint /remove: gdy treść nie jest już używana (zatrzymanie rozliczeń) Zapobiegać nieautoryzowanemu dostępowi: chroń swoje poświadczenia (credentials) API Przestrzegać limitów: stosuj limity ustawione dla Twojego konta Twoje obowiązki prawne Gdy integrujesz API, musisz: Zaktualizować swoje Warunki korzystania (Terms of Use), aby poinformować użytkowników końcowych: Treści nie mogą być pobierane ani używane poza Twoją aplikacją Treści nie mogą być używane do celów AI/ML Treści są własnością Cathopic i ich twórców Użycie jest śledzone na potrzeby rozliczeń i zgodności Wdrożyć kontrole techniczne, aby zapobiec: Pobieraniu przez kliknięcie prawym przyciskiem (o ile to możliwe) Bezpośredniemu dostępowi do oryginalnych plików przez URL Rozszerzeniom przeglądarki umożliwiającym pobieranie Utrzymywać logi użycia dla: Weryfikacji rozliczeń Audytów zgodności Rozwiązywania sporów Przykłady dozwolonych integracji ✅ Kreator biuletynu parafialnego Parafie tworzą cyfrowe biuletyny z katolickimi obrazami Treści wyświetlają się na stronie internetowej i w newsletterach e-mail Nie udostępnia się funkcji pobierania Rozliczenia śledzą użycie osobno dla każdej parafii i dla każdego obrazu ✅ Platforma e-mail dla duszpasterstwa Organizacje religijne projektują kampanie e-mailowe Obrazy są dostarczane bezpośrednio w e-mailach za pomocą adresów URL API Rozliczanie za e-mail wysłany z treścią Brak przechowywania plików na urządzeniach użytkowników końcowych ✅ Platforma CMS katolickiego Kreator stron z zintegrowaną biblioteką Cathopic Użytkownicy przeglądają i wybierają obrazy do swoich stron Treści są osadzane za pomocą adresów URL dostarczanych przez API Rozliczanie za dzień użycia przypadający na użytkownika Przykłady integracji zabronionych ❌ Generator obrazów oparty na AI Używanie treści Cathopic do trenowania modeli AI Tworzenie zbiorów danych do uczenia maszynowego Generowanie podobnych obrazów na podstawie naszych treści ❌ Narzędzie do projektowania do druku Umożliwienie użytkownikom tworzenia plakatów do druku Udostępnianie pobierania do druku w wysokiej rozdzielczości Tworzenie plików PDF z treściami Cathopic do druku ❌ Marketplace ze zdjęciami stockowymi Odsprzedawanie treści Cathopic jako samodzielnych produktów Tworzenie kolekcji zdjęć stockowych będących utworami zależnymi Redystrybucja treści do wielu klientów Zanim zaczniesz budować Niezbędna lektura: Przejrzyj kompletne API License Agreement Zapoznaj się z dokumentacją techniczną na stronie api.cathopic.com/docs Zrozum szczegółowo model rozliczeń (zobacz How is API usage billed?) Zaplanować integrację tak, aby spełniała wszystkie ograniczenia Skontaktuj się z nami przez support, jeśli masz pytania Pamiętaj: uzyskując dostęp do API lub z niego korzystając, akceptujesz wszystkie warunki w API License Agreement. Brak zgodności może skutkować natychmiastowym zakończeniem oraz konsekwencjami prawnymi.

Question 3

Jakie są limity zapytań?

Accepted Answer

Obecnie nie egzekwujemy ścisłych limitów liczby żądań na sekundę. Oczekujemy jednak rozsądnego korzystania, aby utrzymać jakość usługi dla wszystkich. Obec podejście Zamiast twardych limitów zachęcamy do odpowiedzialnego użycia: Odstawiaj swoje żądania w rozsądnych odstępach Stosuj wykładnicze opóźnianie (exponential backoff) w razie wystąpienia błędów Buforuj odpowiedzi, aby uniknąć zbędnych wywołań Skontaktuj się z nami, jeśli przewidujesz duży ruch Dobre praktyki Buforuj intensywnie: Zapisuj wyniki wyszukiwania dla typowych zapytań Przechowuj lokalnie metadane multimediów po pobraniu Nie wywołuj /confirm wielokrotnie dla tego samego użytkownika/zasobu Grupuj operacje: Łącz ze sobą powiązane żądania Dodawaj krótkie opóźnienia między partiami Ogranicz liczbę jednoczesnych połączeń (10–20 jest rozsądne) Obsługuj błędy z wyczuciem: Wdroż logikę ponawiania z wykładniczym opóźnianiem Nie ponawiaj natychmiast po niepowodzeniu Rejestruj błędy w celu monitorowania Oczekiwany czas odpowiedzi /resources search: zwykle 200–500 ms /resource details: poniżej 100 ms /confirm licensing: 300–800 ms Ustaw timeout po stronie klienta na co najmniej 30 sekund, aby obsłużyć sporadycznie wolniejsze odpowiedzi. Co jeśli trafisz na limity Otrzymasz błąd 429 Too Many Requests. Gdy to się wydarzy: // 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; } } } Monitoruj swoje użycie Śledź aktywność API w Ustawienia → API: Zobacz łączną liczbę wykonanych żądań Sprawdź aktywne licencje Przejrzyj trendy użycia Monitoruj nietypowe wzorce Potrzebujesz wyższych limitów? Jeśli uzasadnione zastosowanie wymaga dużej liczby żądań (>1 mln żądań/miesiąc), skontaktuj się z naszym zespołem, aby omówić: Twoją aplikację i wzorce ruchu Oczekiwaną liczbę żądań Gwarantowane limity szybkości, jeśli będą potrzebne

Question 4

Jak naliczane jest korzystanie z API?

Accepted Answer

API Cathopic korzysta z modelu rozliczeń typu „pay-as-you-go”, opartego na rzeczywistym wykorzystaniu treści przez użytkowników końcowych. Wszystkie warunki rozliczeń regulowane są przez nasze Umowę licencyjną dla API. Dwa modele rozliczeń Rozliczenia zależą od tego, w jaki sposób użytkownicy końcowi korzystają z treści: 1. Korzystanie z witryny (model Dni użycia) Dotyczy sytuacji, gdy treść jest wyświetlana na stronach internetowych, blogach lub w aplikacjach webowych Obliczane na podstawie każdego dnia kalendarzowego, w którym użytkownik końcowy uzyskuje dostęp do określonej treści Wzór: Łączna liczba Dni użycia × (uzgodniona miesięczna stawka ÷ 30) Rozliczanie proporcjonalne w ujęciu dziennym sprawia, że płacisz tylko za rzeczywiste wykorzystanie Śledzone osobno dla każdego użytkownika końcowego i dla każdego elementu treści 2. Korzystanie z e-maili (model „Per Email”) Dotyczy sytuacji, gdy treść jest włączana do wiadomości e-mail Opłata naliczana za wysłaną wiadomość e-mail (nie za odbiorcę) Jednorazowe rozliczenie za e-mail, który zawiera treść Stawka uzgadniana podczas konfiguracji dostępu do API Kiedy rozliczenia się zaczynają i kończą Treść ze znakiem wodnym jest bezpłatna Treść początkowo pojawia się ze znakiem wodnym Podgląd ze znakiem wodnym nie generuje opłat Idealne do umożliwienia użytkownikom końcowym przeglądania treści przed podjęciem decyzji Może być używana do testów i celów próbnych Rozliczenia zaczynają się, gdy usuniesz znak wodny Użytkownik końcowy decyduje się korzystać z treści bez znaku wodnego Twoja aplikacja wywołuje POST /confirm z: media_id: Identyfikator treści usage_type: „website” albo „email” client_identifier: Unikalny identyfikator Twojego użytkownika końcowego API zwraca stałe adresy URL dla treści bez znaku wodnego Rozliczenia rozpoczynają się natychmiast od tej chwili Musisz przechowywać te adresy URL oraz dane o wykorzystaniu do celów śledzenia rozliczeń Rozliczenia kończą się, gdy treść zostanie usunięta Użytkownik końcowy usuwa treść lub przestaje z niej korzystać Twoja aplikacja wywołuje POST /remove z: media_id: Identyfikator treści client_identifier: Identyfikator użytkownika końcowego Rozliczenia dla tego konkretnego wykorzystania zostają zatrzymane Musisz usunąć adresy URL dla treści bez znaku wodnego z bazy danych Przykład rozliczeń dla witryny Załóżmy, że uzgodniłeś miesięczną stawkę za nieograniczone korzystanie z treści: Scenariusz: Parafia A wyświetla Obraz #12345 na swojej stronie głównej Dzień 1: Wywołujesz /confirm → Rozliczenia się rozpoczynają Dni 1-15: Obraz pozostaje na stronie głównej (15 dni użycia) Dzień 16: Parafia usuwa obraz, wywołujesz /remove → Rozliczenia się kończą Obliczenie: 15 dni × ( ÷ 30 dni) = Naliczono: za to konkretne wykorzystanie Jeśli Parafia B również używa tego samego obrazu przez 10 dni, jest to śledzone osobno i powoduje naliczenie dodatkowych opłat. Przykład rozliczeń dla e-maila Załóżmy, że uzgodniłeś stawkę --.05 za e-mail: Scenariusz: Ministerstwo wysyła newsletter z Obrazem #67890 Działanie: Wywołujesz /confirm z usage_type: "email" Wynik: Jednorazowa opłata --.05 za ten e-mail Odbiorcy: Nie ma znaczenia, czy wiadomość została wysłana do 100 czy 10 000 osób Naliczono: --.05 łącznie (nie za odbiorcę) Miesięczne limity rozliczeń Twoja umowa może zawierać miesięczne limity rozliczeń: Chronią Cię przed niespodziewanie wysokimi rachunkami Po osiągnięciu limitu dodatkowe wykorzystanie może być bezpłatne lub naliczane w obniżonej stawce Konkretną kwotę limitu uzgadnia się podczas konfiguracji dostępu do API Dotyczy łącznych opłat miesięcznych naliczanych za wszystkich użytkowników końcowych Fakturowanie i płatności Harmonogram faktur Faktury są wystawiane co miesiąc w pierwszych 10 dniach każdego miesiąca Obejmuje wszystkie wykorzystania z poprzedniego miesiąca Szczegółowe zestawienie wykorzystania według użytkownika końcowego i elementu treści Wysyłane na adres e-mail powiązany z Twoim kontem API Obsługa płatności Płatności są przetwarzane wyłącznie przez Stripe Automatyczne obciążenie zarejestrowanej metody płatności Musisz przez cały czas utrzymywać poprawne informacje o płatnościach Potwierdzenia (paragony) są udostępniane automatycznie po udanej płatności Niepowodzenia płatności Jeśli płatność się nie powiedzie, system wykona 4 próby ponowienia Otrzymujesz powiadomienia e-mail o problemach z płatnością Jeśli wszystkie ponowienia się nie powiodą, dostęp do API zostaje zawieszony Dostęp zostaje przywrócony natychmiast po udanej płatności Niezapłacone faktury mogą naliczać odsetki Twoje obowiązki w zakresie śledzenia Musisz prowadzić dokładne rejestry: Dzienniki wykorzystania: Kiedy treść została potwierdzona i usunięta Identyfikatory użytkowników końcowych: Którzy użytkownicy uzyskali dostęp do jakiej treści Identyfikatory treści: Które elementy multimedialne zostały użyte Typy wykorzystania: Witryna vs e-mail dla każdego wykorzystania Daty: Data rozpoczęcia i zakończenia korzystania z treści na stronie Adresy URL: Przechowywane adresy URL bez znaku wodnego dla aktywnego wykorzystania Te rejestry są niezbędne do: Weryfikowania miesięcznych faktur Rozwiązywania sporów dotyczących rozliczeń Audytów zgodności przez Cathopic Twojego własnego raportowania wewnętrznego Uzyskiwanie raportów o wykorzystaniu Możesz śledzić wykorzystanie API w czasie rzeczywistym: Przejdź do Ustawienia → API Zobacz sekcję „On-demand usage” Sprawdź statystyki bieżącego okresu rozliczeniowego: Łączny koszt naliczony do tej pory Liczba użyć w witrynie Liczba użyć e-mail Kliknij „View detailed report”, aby zobaczyć zestawienie według: Użytkownika końcowego (client identifier) Elementu treści Typu wykorzystania Zakresu dat Poszczególnych kosztów Eksportuj raporty do pliku CSV na potrzeby swoich zapisów Uzgadnianie stawek Cennik API jest dostosowywany do każdego klienta: Stawki są uzgadniane podczas procesu składania wniosku o dostęp do API Na podstawie przewidywanej wielkości wykorzystania Na podstawie Twojego konkretnego przypadku użycia i typu integracji Może obejmować rabaty ilościowe dla aplikacji o wysokim wykorzystaniu Limity rozliczeń mogą zostać uzgodnione w celu zapewnienia przewidywalnych kosztów Aby omówić wycenę: Odwiedź naszą stronę pomocy Wybierz „API access request” Opisz swoją integrację i oczekiwane wykorzystanie Nasz zespół przygotuje dostosowaną wycenę Zrozumienie pełnej licencji Rozliczenia to tylko jeden aspekt umowy dotyczącej API. Przejrzyj kompletne warunki: Przeczytaj pełną Umowę licencyjną dla API Zrozum ograniczenia dotyczące korzystania (tylko treści cyfrowe, bez AI/ML, bez pobierania) Znajdź swoje obowiązki w zakresie śledzenia i raportowania Przejrzyj postanowienia dotyczące własności intelektualnej i zakończenia umowy W celu uzyskania szczegółów technicznych dotyczących wdrożenia: Zobacz punkty końcowe /confirm i /remove na api.cathopic.com/docs Zrozum, jak obliczać wykorzystanie dla Twojej konkretnej integracji Przejrzyj najlepsze praktyki dotyczące dokładnego śledzenia rozliczeń Pamiętaj: Dokładne śledzenie wykorzystania jest Twoim obowiązkiem. Prowadź szczegółowe rejestry, aby zapewnić prawidłowe rozliczenia i zgodność z umową licencyjną.

Question 5

Jak poprosić o dostęp deweloperski do API i OAuth

Accepted Answer

Cathopic sprawdza konto dewelopera tylko raz. Jedna akceptacja odblokowuje zarówno komercyjne API, jak i zarządzanie aplikacjami OAuth; nie składasz osobnych wniosków. Po akceptacji tworzysz i zarządzasz kluczami API oraz poświadczeniami OAuth w Ustawieniach Cathopic. Deweloperzy nigdy nie potrzebują dostępu do poleceń serwera Cathopic ani infrastruktury. 1. Przygotuj swoje konto Cathopic Utwórz konto Cathopic, zweryfikuj adres e-mail i upewnij się, że nazwa użytkownika oraz e-mail we wniosku dokładnie odpowiadają temu kontu. 2. Wyślij wniosek deweloperski Otwórz formularz kontaktowy Cathopic. Wybierz Wniosek o dostęp deweloperski. Potwierdź nazwę użytkownika Cathopic i opisz produkt, organizację oraz planowane wykorzystanie katalogu. Wyślij formularz. Wniosek pojawia się w wewnętrznym panelu przeglądu Cathopic. 3. Otrzymaj decyzję Cathopic sprawdza konto i przypadek użycia. Po akceptacji deweloper otrzymuje e-mail z kolejnymi krokami oraz linkiem do Ustawienia → Developer / API → OAuth applications. Jeśli potrzebne są dodatkowe informacje, Cathopic kontaktuje się z adresem e-mail podanym we wniosku. 4. Utwórz aplikację Wybierz poufną aplikację webową, gdy produkt ma bezpieczne zaplecze, albo publiczną aplikację PKCE dla klientów działających tylko w przeglądarce, na urządzeniach mobilnych lub w aplikacjach desktopowych. Wprowadź jej publiczną nazwę, opis, stronę internetową, politykę prywatności, kontakt ds. bezpieczeństwa, dokładne adresy URL callback oraz tylko te zakresy (scopes), których potrzebuje. 5. Zapisz poświadczenia Identyfikator klienta (client ID) identyfikuje integrację i jest udostępniany wszystkim użytkownikom tego produktu. Autoryzacja użytkownika i tokeny pozostają osobne dla każdego konta Cathopic. Poufna tajemnica klienta (client secret) jest pokazywana tylko raz i musi być zaszyfrowana na serwerze aplikacji. Nigdy nie umieszczaj jej w kodzie przeglądarki, wygenerowanych stronach internetowych, logach, wiadomościach wsparcia ani w publicznym repozytorium. Ta sama strona umożliwia zatwierdzonemu deweloperowi edycję callbacków i zakresów, rotację poufnej tajemnicy lub cofnięcie aplikacji.

Question 6

Jak działają klucze API?

Accepted Answer

Klucze API są Twoimi danymi uwierzytelniającymi do korzystania z API Cathopic. Zrozumienie, jak działają, jest niezbędne dla bezpiecznej i skutecznej integracji z API. Czym jest klucz API? Klucz API to unikalny tajny token, który identyfikuje Twoją aplikację i upoważnia ją do dostępu do API Cathopic: Długi ciąg znaków alfanumerycznych (np. sk_live_abc123xyz789...) Działa zarówno jako uwierzytelnianie, jak i autoryzacja Jest powiązany z Twoim kontem Cathopic i rozliczeniami Może być aktywny lub nieaktywny Cykl życia klucza Tworzenie: Wygeneruj klucze w Ustawienia → API Nadaj każdemu kluczowi opisową nazwę ("Production Website", "Staging", "Mobile App") Skopiuj pełny klucz od razu — jest wyświetlany tylko raz Przechowuj bezpiecznie (zmienne środowiskowe, menedżer sekretów, menedżer haseł) Użycie: Dołącz do nagłówka HTTP x-api-key w przypadku każdej prośby Klucze są weryfikowane po stronie serwera w każdej prośbie Wszystkie użycia API są rejestrowane i rozliczane na Twoim koncie Dezaktywacja: Klucze można tymczasowo wyłączyć bez usuwania Przydatne do diagnozowania problemów lub wstrzymania konkretnej integracji Można je ponownie aktywować w dowolnym momencie Usunięcie: Trwale usuwa klucz Nie można tego cofnąć ani odzyskać Wszystkie prośby z tym kluczem zakończą się natychmiast niepowodzeniem Zasady zarządzania kluczami Bezpieczeństwo: Nigdy nie zapisuj kluczy w systemie kontroli wersji: Użyj plików .env i dodaj je do .gitignore Nigdy nie ujawniaj w kodzie po stronie klienta: Klucze API powinny być używane wyłącznie po stronie serwera Używaj zmiennych środowiskowych: Przechowuj klucze w process.env.CATHOPIC_API_KEY lub odpowiedniku Regularnie rotuj: Zmieniaj klucze okresowo (co kwartał lub po zmianach w zespole) Używaj osobnych kluczy dla każdego środowiska: Różne klucze dla dev, staging i produkcji Organizacja: Opisowe nazwy: Nazywaj klucze według przeznaczenia: "Production Website", "iOS App", "Email System" Dokumentuj właściciela: Śledź, który członek zespołu utworzył każdy klucz Regularne audyty: Przeglądaj aktywne klucze co miesiąc i usuwaj te nieużywane Wiele kluczy API Możesz utworzyć wiele kluczy API do różnych celów: Na środowisko: Oddzielne klucze dla development, staging, produkcji Na aplikację: Różne klucze dla strony internetowej, aplikacji mobilnej, narzędzi wewnętrznych Na członka zespołu: Indywidualne klucze dla programistów (łatwiejsze do śledzenia i cofnięcia) Wszystkie klucze w ramach Twojego konta współdzielą to samo rozliczenie. Użycie ze wszystkich kluczy jest sumowane w Twojej miesięcznej fakturze. Monitorowanie użycia klucza Śledź aktywność dla każdego klucza: Przejdź do Ustawienia → API Zobacz listę wszystkich kluczy wraz z datami ostatniego użycia Kliknij klucz, aby zobaczyć szczegółowe statystyki użycia Monitoruj pod kątem nieoczekiwanej aktywności Co zrobić, jeśli klucz został naruszony Jeśli uważasz, że klucz API został ujawniony: Natychmiast usuń lub dezaktywuj klucz w Ustawienia → API Wygeneruj nowy klucz zastępczy Zaktualizuj swoją aplikację o nowy klucz Przejrzyj logi użycia pod kątem podejrzanej aktywności Skontaktuj się z pomocą, jeśli widzisz nieautoryzowane użycie Przykład: bezpieczne przechowywanie kluczy Node.js ze zmiennymi środowiskowymi: // plik .env (dodaj do .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Twój kod 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 ze zmiennymi środowiskowymi: 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

Jak uwierzytelnić żądania?

Accepted Answer

Wszystkie żądania do API Cathopic muszą być uwierzytelniane przy użyciu klucza API. Oto jak prawidłowo uwierzytelnić wywołania API. Metoda uwierzytelniania API Cathopic wykorzystuje uwierzytelnianie kluczem API za pomocą nagłówków HTTP: Nazwa nagłówka: x-api-key Wartość nagłówka: Twój pełny klucz API Wymagane dla: Wszystkich endpointów API Rozróżnianie wielkości liter: Nazwy i wartości nagłówków muszą być zgodne dokładnie Przykład podstawowego uwierzytelniania 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); ?> Błędy uwierzytelniania Jeśli uwierzytelnianie się nie powiedzie, otrzymasz odpowiedź z błędem: Brak klucza API: HTTP 401 Unauthorized { "message": "Unauthorized" } Nieprawidłowy klucz API: HTTP 401 Unauthorized { "message": "Unauthorized" } Nieaktywny klucz API: HTTP 401 Unauthorized { "error": "Unauthorized token" } Ważne przypomnienia Bezpieczeństwo: Nigdy nie osadzaj na sztywno kluczy API: Używaj zmiennych środowiskowych lub bezpiecznej konfiguracji Tylko po stronie serwera: Nigdy nie umieszczaj kluczy API w kodzie JavaScript po stronie klienta Używaj wyłącznie HTTPS: Klucze API przesyłane przez HTTP są narażone Regularnie rotuj: Zmieniaj klucze okresowo dla bezpieczeństwa Obsługa błędów: Sprawdzaj kody statusu: Zawsze weryfikuj status odpowiedzi HTTP Rejestruj niepowodzenia uwierzytelniania: Śledź nieudane próby w celu monitorowania bezpieczeństwa Wdroż logikę ponawiania: Z wykładniczym backoff dla błędów przejściowych Waliduj przed wysłaniem: Upewnij się, że klucz API został poprawnie załadowany Testowanie uwierzytelniania Szybki test, aby sprawdzić, czy Twój klucz API działa: 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}' Oczekiwana odpowiedź (sukces): { "total": 1234, "page": 1, "page_size": 1, "results": [ ... ] } Częste błędy Zła nazwa nagłówka: Musi być x-api-key, a nie api-key ani Authorization Nieprawidłowy format wartości: Użyj pełnego klucza dokładnie tak, jak jest, bez prefiksu „Bearer” Wiodące/końcowe białe znaki: Usuń zbędne spacje z wartości klucza API przed użyciem Klucz nie został załadowany: Sprawdź, czy zmienna środowiskowa jest ustawiona poprawnie W celu rozwiązywania problemów z uwierzytelnianiem zobacz „Common authentication errors” w tej sekcji.

Question 8

Jak obrócić (rotować) klucz API?

Accepted Answer

Regularna rotacja kluczy API to ważna praktyka bezpieczeństwa. Oto jak bezpiecznie rotować klucze, nie zakłócając działania usługi. Dlaczego rotować klucze API? Dobra praktyka bezpieczeństwa: Ogranicza narażenie, jeśli klucz kiedykolwiek zostanie naruszony Zmiany w zespole: Gdy deweloperzy odchodzą lub zmieniają role Podejrzenie naruszenia: Jeśli uważasz, że klucz mógł zostać ujawniony Zgodność: Niektóre polityki bezpieczeństwa wymagają okresowej rotacji kluczy Zmiany środowiska: Gdy przenosisz infrastrukturę lub dokonujesz refaktoryzacji Standardowy proces rotacji (bez przestojów) Krok 1: Utwórz nowy klucz Zaloguj się do Ustawienia → API Kliknij "Utwórz nowy klucz API" Nazwij go opisowo (np. "Production Web v2") Skopiuj nowy klucz od razu — jest wyświetlany tylko raz Zabezpiecz go Krok 2: Zaktualizuj swoją aplikację Wdróż nowy klucz do swojej aplikacji (zmienne środowiskowe, menedżer sekretów itp.) Uruchom ponownie aplikację, aby załadować nowy klucz Zweryfikuj, że nowy klucz działa poprawnie Monitoruj wszelkie błędy Krok 3: Monitoruj przejście Przez pewien czas utrzymuj aktywne oba klucze Sprawdź Ustawienia → API, aby zobaczyć daty „Ostatnio użyty” Poczekaj, aż stary klucz nie będzie wykazywał ostatniej aktywności Upewnij się, że wszystkie instancje/usługi przełączyły się na nowy klucz Krok 4: Usuń stary klucz Gdy potwierdzisz, że stary klucz nie jest już używany Usuń lub dezaktywuj stary klucz w Ustawienia → API Zapisz rotację w dokumentacji dla swoich rejestrów Szybki proces rotacji (jeśli klucz został naruszony) Jeśli klucz jest na pewno naruszony i musisz działać natychmiast: Najpierw usuń naruszony klucz w Ustawienia → API Utwórz nowy klucz zastępczy Szybko wdroż nowy klucz we wszystkich aplikacjach Akceptuj krótkie przestoje, aby zapobiec nieautoryzowanemu dostępowi Monitoruj logi użycia pod kątem podejrzanej aktywności W razie potrzeby skontaktuj się z wsparciem Strategia rotacji dla wielu środowisk Dla systemów produkcyjnych zastosuj podejście etapowe: Tydzień 1: Development Utwórz i wdroż nowy klucz do środowiska dev Dokładnie przetestuj Tydzień 2: Staging Wdróż nowy klucz do środowiska staging Uruchom testy integracyjne Monitoruj pod kątem problemów Tydzień 3: Produkcja Wdróż nowy klucz do produkcji w czasie małego ruchu Uważnie monitoruj Utrzymuj stary klucz aktywny przez 24–48 godzin jako plan awaryjny Tydzień 4: Czyszczenie Sprawdź, że stary klucz nie wykazuje aktywności Usuń stary klucz Zaktualizuj dokumentację Przykład automatyzacji Skrypt pomocniczy do sprawdzenia, czy rotacja klucza została zakończona: #!/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 Dobre praktyki Rotuj regularnie: Co 90 dni dla kluczy produkcyjnych Dokumentuj rotacje: Prowadź log, kiedy klucze były rotowane i dlaczego Testuj przed usunięciem: Zawsze upewnij się, że nowy klucz działa, zanim usuniesz stary Używaj wielu kluczy: Rozdzielenie kluczy per środowisko ułatwia rotację Automatyzuj, gdy to możliwe: Korzystaj z narzędzi do zarządzania sekretami, które obsługują automatyczną rotację Lista kontrolna po rotacji Potwierdź te elementy po rotacji: ✅ Wszystkie instancje produkcyjne używają nowego klucza ✅ Wszystkie środowiska staging/dev zostały zaktualizowane (jeśli używasz tego samego klucza) ✅ Zmienne środowiskowe zostały zaktualizowane ✅ Sekrety CI/CD zostały zaktualizowane ✅ Dokumentacja została zaktualizowana ✅ Członkowie zespołu zostali powiadomieni ✅ Stary klucz został usunięty ✅ Rotacja została zapisana do celów audytu

Question 9

Jak zabezpieczyć swoje dane uwierzytelniające?

Accepted Answer

Twoje klucze API są bramą do Twojego konta Cathopic. Dbając o ich bezpieczeństwo, zapobiegasz nieautoryzowanemu dostępowi i chronisz się przed nadużyciami rozliczeniowymi. Złota zasada: Trzymaj klucze w tajemnicy Traktuj swoje klucze API jak hasła. Typowe błędy, których należy unikać: Wpisywanie kluczy na sztywno bezpośrednio w kodzie źródłowym Przekazywanie kluczy do Git lub innego systemu kontroli wersji Używanie kluczy w kodzie JavaScript po stronie klienta lub w aplikacjach mobilnych Dzielnie się kluczami przez e-mail, Slack lub komunikatory Przechowywanie kluczy w publicznych lokalizacjach (publiczne repozytoria, wiki itp.) Używaj zmiennych środowiskowych Przechowuj klucze w zmiennych środowiskowych zamiast w kodzie: // plik .env (dodaj do .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Twój kod require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; To oddziela wrażliwe dane od Twojej bazy kodu i ułatwia rotację kluczy. Tylko po stronie serwera Wywołania API muszą być wykonywane z Twoich serwerów backendowych, a nie z przeglądarek ani aplikacji mobilnych. Jeśli użytkownicy potrzebują dostępu do zasobów Cathopic: Utwórz punkt końcowy (endpoint) po stronie backendu, który używa Twojego klucza API Twój frontend wywołuje TWOJĄ usługę (endpoint), a nie bezpośrednio Cathopic Twój serwer weryfikuje żądanie użytkownika przed wywołaniem Cathopic Ograniczaj według IP (jeśli to możliwe) Niektóre rozwiązania infrastrukturalne umożliwiają białe listy IP. Jeśli Twoje wywołania API pochodzą ze znanych adresów IP: Skonfiguruj reguły zapory sieciowej, aby ograniczyć dostęp wychodzący Używaj dedykowanych kont serwisowych z minimalnymi uprawnieniami Monitoruj logi dostępu pod kątem nietypowej aktywności Jeśli klucz został naruszony Jeśli podejrzewasz, że klucz został ujawniony: Natychmiast wygeneruj nowy klucz API Zaktualizuj swoją aplikację o nowy klucz Usuń naruszony klucz Przejrzyj logi użycia pod kątem podejrzanej aktywności Skontaktuj się z pomocą, jeśli zauważysz nieautoryzowane obciążenia Zarządzaj swoimi kluczami bezpiecznie w Ustawienia → API.

Question 10

Najczęstsze błędy uwierzytelniania

Accepted Answer

Jeśli masz problem z uwierzytelnianiem się za pomocą API Cathopic, poniżej znajdziesz najczęstsze błędy oraz sposoby ich naprawy. 401 Unauthorized Najczęstszy błąd uwierzytelniania: HTTP 401 Unauthorized { "message": "Unauthorized" } Najczęstsze przyczyny: Brak nagłówka x-api-key Nieprawidłowy lub wygasły klucz API Literówka w kluczu API Spacje przed/po kluczu Klucz nie został wczytany z zmiennej środowiskowej Jak to naprawić: Sprawdź, czy nazwa nagłówka jest dokładnie x-api-key (małe litery) Ponownie skopiuj swój klucz API z Ustawienia → API Sprawdź, czy zmienne środowiskowe są wczytane: console.log(process.env.CATHOPIC_API_KEY) Usuń białe znaki: apiKey.trim() Upewnij się, że klucz jest aktywny (nie usunięty ani nie zdezaktywowany) Błędna nazwa nagłówka API wymaga x-api-key, a nie innych popularnych nazw nagłówków: // ❌ ŹLE Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ POPRAWNIE x-api-key: sk_live_abc... Błąd nieautoryzowanego tokenu HTTP 401 Unauthorized { "error": "Unauthorized token" } Przyczyna: Twój klucz API został zdezaktywowany lub usunięty. Jak to naprawić: Sprawdź, czy klucz nadal jest aktywny w Ustawienia → API Aktywuj ponownie klucz, jeśli został zdezaktywowany Wygeneruj nowy klucz, jeśli stary został usunięty Nie wczytano zmiennej środowiskowej Twój kod nie znajduje klucza API: // Zwraca undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Jak to naprawić: Node.js: // Upewnij się, że .env jest wczytany 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') Błąd ujawnienia po stronie klienta Próba użycia klucza API w przeglądarce (JavaScript): // ❌ To się nie uda (klucze nie działają w przeglądarkach) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Jak to naprawić: Utwórz punkt końcowy po stronie serwera, który będzie pośredniczył w żądaniach do API Cathopic. Zobacz „Jak zabezpieczyć moje dane uwierzytelniające?” dla przykładów. Błędy CORS Jeśli w konsoli przeglądarki widzisz błędy CORS: Access to fetch has been blocked by CORS policy... Przyczyna: Próbujesz wywołać API bezpośrednio z kodu JavaScript po stronie klienta. Jak to naprawić: API Cathopic działa tylko po stronie serwera. Musisz przekazywać żądania przez własny backend. Testowanie uwierzytelniania Szybki test, aby zweryfikować konfigurację: 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}' # Sprawdź odpowiedź HTTP 200 # Jeśli 401, uważnie sprawdź klucz Lista kontrolna debugowania Jeśli uwierzytelnianie nadal nie działa: ☐ Nazwa nagłówka to x-api-key (rozróżniana jest wielkość liter) ☐ Klucz API to pełny klucz (zaczyna się od sk_live_ lub podobnego) ☐ Brak prefiksu Bearer lub cudzysłowów wokół klucza ☐ Zmienna środowiskowa jest ustawiona i wczytana ☐ Żądanie jest wysyłane z serwera, a nie z przeglądarki ☐ Klucz jest aktywny w Ustawienia → API ☐ Dodano metodę płatności i jest ona ważna Jeśli problemy będą się utrzymywać, skontaktuj się z wsparciem dla deweloperów podając: Komunikat o błędzie Ostatnie 4 cyfry twojego klucza API Język programowania i framework Przykładowy kod (bez ujawniania pełnego klucza)

Question 11

Dostępne parametry wyszukiwania

Accepted Answer

Punkt końcowy /resources obsługuje kilka parametrów, które pozwalają doprecyzować wyniki wyszukiwania. Podstawowe wyszukiwanie POST https://api.cathopic.com/resources { "query": "Saint Francis", "page": 1, "page_size": 20, "order": "popular" } Parametry query (string, opcjonalnie) Twoje hasło wyszukiwania. Zostaw puste, aby otrzymać wszystkie zasoby. Przykłady: "Virgin Mary", "Eucharist", "cross" Obsługuje dopasowanie przybliżone i tolerancję literówek Wyszukuje w tytułach, opisach i tagach page (integer, domyślnie: 1) Którą stronę wyników zwrócić. Zaczyna się od 1. page_size (integer, domyślnie: 20, max: 100) Liczba wyników na stronę. Maksimum to 100, aby utrzymać wydajność. order (string, domyślnie: "popular") Jak sortować wyniki: popular - Najpierw najczęściej pobierane zasoby recent - Najpierw najnowsze dodane materiały Struktura odpowiedzi { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Resource title", "description": "Resource description", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Przykłady praktyczne Pobierz pierwsze 10 najpopularniejszych zasobów dotyczących modlitwy: { "query": "prayer", "page": 1, "page_size": 10, "order": "popular" } Pobierz najnowsze dodania, bez konkretnego hasła wyszukiwania: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Przeglądaj stronę 3 obrazów o świętych: { "query": "saints", "page": 3, "page_size": 20, "order": "popular" } Aby zapoznać się z pełną dokumentacją API, odwiedź api.cathopic.com/docs.

Question 12

Jak pobrać obrazy przez API?

Accepted Answer

Ważne doprecyzowanie: API nie umożliwia „pobierania” w tradycyjnym znaczeniu. Zamiast tego udostępnia stałe adresy URL do treści zoptymalizowanych pod WWW, które Twoja aplikacja wyświetla użytkownikom końcowym. Reguluje to Umowa licencyjna API. Nie pobierasz plików Działanie Cathopic API różni się zasadniczo od tradycyjnych pobrań: Brak transferu plików: Nigdy nie otrzymujesz ani nie przechowujesz samych plików obrazu/wideo Dostęp przez adresy URL: API udostępnia adresy URL wskazujące treści hostowane przez Cathopic Tylko pod WWW: Treści są serwowane w rozdzielczości odpowiedniej do wyświetlania cyfrowego Brak oryginalnych plików: Wysokiej jakości oryginały nigdy nie są dostępne przez API Zawsze hostowane: Treści pozostają na serwerach Cathopic lub na autoryzowanym CDN Dostępne rozdzielczości API udostępnia trzy rozmiary zoptymalizowane pod WWW: Small: Odpowiednie do miniatur i małych osadzeń (zwykle ok. 400 px szerokości) Medium: Dobre do standardowych treści w sieci (zwykle ok. 800 px szerokości) Large: Najlepsza jakość do wyświetlania w sieci (zwykle ok. 1200 px szerokości) Krytyczne ograniczenia: Oryginalne pliki w wysokiej rozdzielczości są NIGDY udostępniane Rozdzielczości są zoptymalizowane do wyświetlania na ekranie, nie do druku Rozmiary plików są skompresowane dla szybkiej dostawy w sieci Nie możesz żądać niestandardowych rozdzielczości ani oryginalnej jakości Aby poznać pełne warunki, przeczytaj całą Umowę licencyjną API i zapoznaj się z dokumentacją techniczną na api.cathopic.com/docs. Pobieranie obrazów obejmuje dwa kroki: licencjonowanie zasobu przez /confirm, a następnie użycie zwróconych adresów URL. Krok 1: Zlicencjonuj zasób Wywołaj /confirm, aby zlicencjonować zasób dla konkretnego użytkownika końcowego: POST https://api.cathopic.com/confirm x-api-key: YOUR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parametry: media_id - Identyfikator zasobu z wyników Twojego wyszukiwania usage_type - Albo „website”, albo „email” client_identifier - Unikalny identyfikator Twojego użytkownika końcowego Krok 2: Użyj adresów URL do pobrania Odpowiedź zawiera stałe adresy URL w wielu formatach: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Ważne: przechowuj adresy URL Zwrócone adresy URL są stałe — przechowuj je w swojej bazie danych: // Po wywołaniu /confirm const response = await api.confirm(mediaId, userId); // Zapisz w swojej bazie danych await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Następnym razem pobierz z DB zamiast ponownie wywoływać /confirm Wybór właściwego formatu Format AVIF: Mniejsze rozmiary plików (lepsza wydajność) Lepsza kompresja Zalecany dla nowoczesnych przeglądarek Nieobsługiwany w starszych przeglądarkach Format JPEG: Powszechna kompatybilność Większe rozmiary plików Użyj jako zamiennika dla starszych przeglądarek Krytyczne przypomnienie ⚠️ Zawsze sprawdzaj swoją bazę danych przed wywołaniem /confirm. Wywołanie go wielokrotnie dla tego samego użytkownika i zasobu spowoduje utworzenie duplikatów opłat. Pełna dokumentacja na api.cathopic.com/docs.

Question 13

Obsługa stronicowania i sortowania

Accepted Answer

Interfejs API zwraca wyniki wyszukiwania w postaci stron. Oto jak sprawnie poruszać się po dużych zbiorach wyników. Podstawowe stronicowanie POST /resources { "query": "saints", "page": 1, "page_size": 20 } Odpowiedź: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 items ... ] } Odpowiedź informuje, że łącznie jest 1 523 wyniki, a Ty przeglądasz stronę 1 z 20 elementami. Obliczanie liczby stron const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 stron Wczytywanie następnej strony // Prosta kolejna strona currentPage++; // Albo zbuduj interfejs stronicowania for (let page = 1; page <= totalPages; page++) { // Utwórz przycisk strony } Optymalizacja rozmiaru strony Wybierz rozmiar strony w zależności od swojego przypadku użycia: Małe strony (10–20 elementów): Szybsze początkowe wczytywanie Dobre do wyszukiwania dostępnego dla użytkowników Potrzebnych jest więcej zapytań do API Duże strony (50–100 elementów): Mniej zapytań do API Dobre do przetwarzania wsadowego Wolniejsze pojedyncze zapytania Maksimum to 100 elementów Opcje sortowania Popularne (domyślne): { "order": "popular" } Zwraca najpierw najczęściej pobierane zasoby. Najlepsze do prezentowania treści wysokiej jakości, sprawdzonych. Najnowsze: { "order": "recent" } Zwraca najpierw najnowsze przesłane materiały. Dobre do odkrywania świeżych treści. Przykład nieskończonego przewijania 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(); // Dodaj wyniki do swojego interfejsu appendResults(data.results); // Sprawdź, czy są kolejne strony const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Wywołaj przy przewijaniu window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Wskazówki dotyczące wydajności Buforuj wyniki lokalnie, aby uniknąć zbędnych zapytań Stosuj odpowiednie rozmiary stron do swojego przypadku użycia Wdroż stany ładowania dla lepszego UX Rozważ wirtualizację dla bardzo długich list Nie pobieraj wszystkich stron naraz — wczytuj na żądanie Aby uzyskać więcej szczegółów, zobacz pełną dokumentację na stronie api.cathopic.com/docs.

Question 14

Jak wyszukiwać w katalogu i korzystać z podglądowych adresów URL Cathopic

Accepted Answer

Użyj GET /api/v2/catalog wraz z catalog.read. Wykorzystuje istniejącą w Cathopic warstwę wyszukiwania rozmytego tolerującą literówki i wypełnia te same kanoniczne modele multimediów używane w siatce na stronie internetowej. Parametry q lub query: tekst do 250 znaków. type: photo, video, graphic, artwork, ai lub all. orientation: landscape, portrait, square lub all. sort: most_recent, popular lub popular_alltime. page, per_page : do 50 oraz locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUżywaj podglądowych adresów URL bez zmian Każdy wynik zawiera preview.url oraz preview.transformation_url_template. Pochodzą one z dokładnie tego samego prezentera siatki, hosta CDN, ścieżki w pamięci masowej oraz reguł znakowania wodnego używanych na cathopic.com. Używaj ich bez zmian, aby integracje ponownie wykorzystywały istniejące klucze cache Cloudflare. Nie przesyłaj kolejnej kopii ani nie udostępniaj jej niepotrzebnie jako proxy. Nie dodawaj parametrów zapobiegających cache’owaniu (cache-busting). Zamień <OPTIONS> wyłącznie na stabilne opcje obrazów Cloudflare. Podglądy nigdy nie zużywają pobrania. already_licensed obejmuje uprawnienia dla pojedynczych użytkowników oraz dla zespołów współdzielonych.

Question 15

Jak bezpiecznie licencjonować i pobierać zasób

Accepted Answer

Utworzenie licencji i utworzenie oryginalnego adresu URL są oddzielne, więc ponawianie jest bezpieczne, a świeże adresy URL nie obciążają ponownie. 1. Utwórz licencję POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Użyj unikalnego klucza od 8 do 160 znaków ASCII możliwych do wydrukowania dla logicznej próby wyboru i zachowaj go podczas ponawiania. Nowa licencja zwraca 201; idempotentne ponowne wywołanie zwraca 200 z tym samym identyfikatorem licencji. Cathopic najpierw weryfikuje oryginał. W jednej transakcji blokuje subskrypcję indywidualną lub zespołową, sprawdza dostęp do multimediów i istniejące udziały współdzielone, zużywa co najwyżej jedno pobranie oraz rejestruje uprawnienie, historię i licencję. 2. Poproś o oryginalny adres URL POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENAdres URL wygasa po pięciu minutach. Poproś o nowy adres URL do ponownego pobrania; nie twórz kolejnej licencji. Cathopic wyprowadza ścieżkę przechowywania i nigdy nie akceptuje dowolnej ścieżki. Ważne błędy subscription_required: brak aktywnego płatnego dostępu. media_type_not_in_plan: typ nie jest uwzględniony. download_balance_exhausted: nie pozostały żadne pobrania w ramach planu z limitami. file_unavailable: oryginał nieobecny; bez opłaty. idempotency_key_conflict: klucz użyty dla innego identyfikatora media. Zachowaj X-Request-Id do wsparcia, ale nigdy nie loguj tokenów, sekretów ani podpisanych adresów URL. Po odpowiedziach 429 lub przejściowych 5xx zastosuj wycofanie z losowym opóźnieniem (jitter).

Question 16

Szybki start OAuth 2.0 dla połączonych aplikacji Cathopic

Accepted Answer

Połączone aplikacje Cathopic korzystają z OAuth 2.0 Authorization Code z obowiązkowym PKCE S256. To samo zatwierdzenie programisty odblokowuje również komercyjny API Cathopic, ale połączenia OAuth używają tokenów użytkownika i planu połączonego użytkownika zamiast kluczy API oraz rozliczeń naliczanych za użycie API. 1. Uzyskaj dostęp i zarejestruj aplikację Złóż pojedynczy wniosek o dostęp programisty przez formularz kontaktowy. Po tym, jak Cathopic zatwierdzi konto e-mailem, otwórz Ustawienia → Developer / API → OAuth applications, utwórz aplikację, zarejestruj jej dokładne callbacki oraz wymagane zakresy (scopes), a jeśli jest poufna, zapisz jej jednorazowy sekret. 2. Odkryj serwer autoryzacji GET https://cathopic.com/.well-known/oauth-authorization-server3. Przekieruj użytkownika 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=enZbuduj jeden adres URL; podziały linii służą tylko temu, aby przykład był czytelny. Za każdym razem wygeneruj nowy stan o wysokiej entropii oraz wartości PKCE. ui_locales jest opcjonalne i może prosić o obsługiwany język, taki jak en lub es. Jeśli wymagane jest logowanie, Cathopic wznawia ten sam wniosek o autoryzację, a następnie wyświetla ekran uprawnień. 4. Zweryfikuj callback i wymień kod Porównaj zwrócony stan przed wymianą kodu. Adres URI przekierowania musi być zgodny bajt w bajt. 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=VERIFIERAplikacje publiczne pomijają client_secret. Tokeny i poufne sekrety przechowuj wyłącznie na serwerze oraz szyfruj je w spoczynku. Tokeny dostępu wygasają po 30 minutach; tokeny odświeżania wygasają maksymalnie po 30 dniach i są rotowane po użyciu. Typowe sprawdzenia Odrzucony callback zwykle różni się od zarejestrowanego URI schematem, hostem, portem, ścieżką, wielkością liter lub ukośnikiem na końcu. invalid_request przed consent oznacza, że brakuje PKCE S256, challenge lub state albo są nieprawidłowe. invalid_grant zwykle oznacza, że kod lub zrotowany token odświeżania został ponownie użyty albo zmienił się callback lub verifier. Po 401 odśwież raz; jeśli odświeżanie się nie powiedzie, poproś użytkownika o ponowne połączenie. 403 oznacza, że token nie ma wymaganego zakresu. Zobacz kompletne kontrakt OpenAPI oraz szczegółowy przewodnik integracji Connected Apps.

Question 17

Jak połączyć Cathopic z inną aplikacją?

Accepted Answer

Zatwierdzona platforma może umożliwić korzystanie z katalogu Cathopic bez podawania hasła. Przekierowuje Twoją przeglądarkę na bezpieczną stronę w cathopic.com, gdzie logujesz się i przeglądasz dokładnie wymagane uprawnienia. Połącz konto W innej aplikacji wybierz jej łącznik Cathopic i kliknij Połącz lub Zaloguj się przez Cathopic. Potwierdź, że przeglądarka jest na cathopic.com. Zaloguj się do Cathopic, jeśli to konieczne. Cathopic wraca do tego samego żądania uprawnień, zamiast otwierać Twój profil. Przeczytaj każde uprawnienie. Mogą one obejmować tożsamość konta, dostęp do katalogu, saldo subskrypcji lub możliwość licencjonowania zasobów. Wybierz Zezwól na dostęp. Cathopic przekierowuje Cię z powrotem tylko do dokładnego callbacku zarejestrowanego dla tej aplikacji. Język i bezpieczeństwo konta Aplikacja może poprosić o obsługiwany język dla ekranów logowania i uprawnień. Cathopic zachowuje ten język przez cały czas trwania połączenia. Aplikacja otrzymuje krótkotrwałe tokeny, nigdy Twoje hasło, i może wykonywać wyłącznie działania wymienione na ekranie uprawnień. Jeśli nie ufasz żądaniu Wybierz Anuluj. Nie zatwierdzaj połączenia, jeśli aplikacja jest Ci nieznana, uprawnienia wydają się niepotrzebne albo przeglądarka nie wyświetla domeny Cathopic. Później możesz cofnąć dostęp z Ustawienia → Developer / API → Połączone aplikacje.

Question 18

Czy podłączone aplikacje korzystają z moich pobrań i jak je odłączyć?

Accepted Answer

Wyszukiwanie i wyświetlanie znakowanych wodą podglądów nigdy nie zużywa pobrania. Pobranie może zostać zużyte tylko wtedy, gdy podłączona aplikacja prosi Cathopic o udzielenie licencji na płatny zasób. Gdy zużywane jest jedno pobranie Zasób jest płatny, plan obejmuje jego typ i ani Ty, ani bieżąca subskrypcja zespołu nie udzielili wcześniej na niego licencji. Plan ma ograniczony limit. Plany bez limitu rejestrują licencję bez zmniejszania liczby. Dostępny jest plik źródłowy. Cathopic weryfikuje to przed zmianą salda. Gdy nie jest zużywane żadne dodatkowe pobranie Zasób jest bezpłatny. Ty lub inny członek korzystający z tej samej subskrypcji zespołu już wcześniej udzielili na niego licencji. Prośba o nowy link do pobrania dla istniejącej licencji. Aplikacja ponawia to samo żądanie z tym samym kluczem idempotencji. Członkowie zespołu zużywają wspólne saldo udostępnione przez właściciela zespołu. Cathopic zawsze jest źródłem prawdy. Odłącz aplikację Otwórz Ustawienia → Developer / API → Podłączone aplikacje. Przejrzyj aplikację i jej uprawnienia. Kliknij Odłącz i potwierdź. Każdy aktywny token dostępu i odświeżania dla tej aplikacji zostaje natychmiast unieważniony. Istniejące licencje i historia pobrań pozostają bez zmian.

Question 19

Najczęstsze kody błędów API

Accepted Answer

Zrozumienie odpowiedzi błędów pomaga szybko diagnozować problemy. Oto najczęstsze błędy, na które możesz natrafić. 400 Bad Request { "error": "media_id is required" } Przyczyny: Brak wymaganego parametru Nieprawidłowy format parametru Niepoprawny JSON Naprawa: Sprawdź, czy treść żądania jest zgodna ze specyfikacją API na api.cathopic.com/docs. 401 Unauthorized { "message": "Unauthorized" } or { "error": "Unauthorized token" } Przyczyny: Brak lub nieprawidłowy klucz API Wyłączony klucz API Zła nazwa nagłówka Naprawa: Upewnij się, że nagłówek x-api-key jest poprawny, a klucz jest aktywny w Ustawienia → API. 404 Not Found { "error": "No file found for media_id 1234" } or { "error": "Media item not found" } Przyczyny: Zasób nie istnieje Zasób został usunięty Złe media_id Naprawa: Zweryfikuj, czy media_id istnieje, najpierw wyszukując za pomocą /resources. 429 Too Many Requests { "error": "Limit exceed." } Przyczyny: Zbyt wiele żądań w krótkim czasie Przekroczono limit zapytań (rate limit) Naprawa: Zaimplementuj wykładnicze opóźnianie (exponential backoff). Poczekaj i ponów próbę, zwiększając opóźnienia (1s, 2s, 4s itd.). 500 Internal Server Error { "error": "Internal server error" } Przyczyny: Przejściowy problem po stronie serwera Niespodziewany stan Naprawa: Odczekaj chwilę i spróbuj ponownie. Jeśli problem będzie się powtarzać, skontaktuj się z supportem. Przykład obsługi błędów 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; } } W przypadku uporczywych błędów sprawdź pełną dokumentację API lub skontaktuj się z supportem.

Question 20

Błędy limitu zapytań

Accepted Answer

Jeśli widzisz 429 Too Many Requests, oznacza to, że wywołujesz API zbyt często. Oto jak obsłużyć to poprawnie. Błąd HTTP 429 Too Many Requests { "error": "Limit exceed." } Dlaczego tak się dzieje Limity zapytań chronią API przed nadmiernym użyciem: Zbyt wiele żądań w krótkim czasie Agresywne odpytywanie lub skrobanie (scraping) Brak opóźnienia między żądaniami Równoległe żądania bez ograniczania (throttling) Strategia wykładniczego backoffu Najlepszym sposobem obsługi limitów zapytań jest wykładniczy backoff — czekaj dłużej po każdej ponownej próbie: 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'); } Zapobieganie limitom zapytań Dodawaj opóźnienia między żądaniami: // Źle: Szybkie, wielokrotne żądania for (const id of mediaIds) { await api.getResource(id); // Brak opóźnienia } // Dobrze: Ograniczone (throttled) żądania for (const id of mediaIds) { await api.getResource(id); await sleep(500); // Opóźnienie 500 ms } Grupuj operacje: // Przetwarzanie w partiach po 10 z opóźnieniami 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); // 2 s między partiami } } Buforuj odpowiedzi (cache): 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; } Czego NIE robić ❌ Ponawiać natychmiast bez opóźnienia ❌ Wysyłać równoległych żądań bez limitu ❌ Ignorować błędy 429 ❌ Stosować stałe krótkie opóźnienia (zawsze używaj wykładniczego backoffu) Jeśli problem nadal występuje Skontaktuj się z wsparciem dla deweloperów, jeśli w sposób uzasadniony potrzebujesz wyższych limitów zapytań dla swojego scenariusza. Podaj szczegóły dotyczące: Twojej aplikacji i zastosowania Oczekiwanej liczby żądań Aktualnej implementacji (z backoffem)

Question 21

Przekroczenie limitu czasu i problemy z siecią

Accepted Answer

Problemy z siecią mogą powodować niepowodzenie żądań do API. Oto jak łagodnie obsługiwać przekroczenia limitu czasu i problemy z połączeniem. Ustawianie odpowiednich limitów czasu Zawsze ustawiaj limity czasu, aby uniknąć zawieszania się żądań: // JavaScript z 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('Żądanie przekroczyło limit czasu po 30s'); } else { console.error('Błąd sieci:', error); } throw error; } // Python z 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 sekund ) return response.json() except Timeout: print('Żądanie przekroczyło limit czasu po 30s') raise except RequestException as e: print(f'Błąd sieci: {e}') raise Częste błędy sieci Przekroczenie limitu czasu połączenia: Nie można nawiązać połączenia z serwerem Zwykle problem z siecią lub zaporą (firewall) Sprawdź połączenie internetowe Zweryfikuj, czy zapora pozwala na HTTPS do api.cathopic.com Przekroczenie limitu czasu odczytu: Połączenie zostało nawiązane, ale brak odpowiedzi Serwer może być wolny lub przeciążony Zwiększ limit czasu lub spróbuj ponownie później Błąd rozwiązywania DNS: Nie można rozwiązać api.cathopic.com Problem z serwerem DNS Spróbuj ponownie lub sprawdź ustawienia DNS Ponawiaj z 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(`Wszystkie ${maxRetries} próby nie powiodły się`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Próba ${attempt + 1} nie powiodła się. Ponawianie za ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Rekomendowane wartości limitów czasu Limit czasu połączenia: 10 sekund Limit czasu odczytu: 30 sekund Wyszukiwanie /resources: 30 sekund /confirm licensing: 30 sekund Debugowanie problemów z siecią Użyj curl do testowania łączności: # Test podstawowej łączności curl -v https://api.cathopic.com/resources # Test z limitem czasu 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"}' Sprawdź: ✓ DNS rozwiązuje api.cathopic.com ✓ Połączenie SSL/TLS przebiega pomyślnie ✓ Otrzymano odpowiedź HTTP ✓ Czas odpowiedzi jest rozsądny (<5s zazwyczaj) Jeśli problemy będą się utrzymywać, skontaktuj się z supportem, podając szczegóły diagnostyki sieci.

Question 22

Debugowanie nieudanych żądań

Accepted Answer

Gdy żądania się nie powiodą, systematyczne debugowanie pomaga szybko zidentyfikować problem. Włącz szczegółowe logowanie 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; } } Najpierw sprawdź te rzeczy 1. Klucz API jest poprawny: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. Nazwa nagłówka jest dokładna: // Musi być małymi literami 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Poprawnie 'X-API-Key': apiKey, // ✗ Źle 'api-key': apiKey, // ✗ Źle } 3. JSON jest poprawny: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. Żądanie dociera do serwera: // Użyj zakładki Network w narzędziach deweloperskich przeglądarki lub curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Częste błędy Zły Content-Type: // ✗ Źle headers: { 'Content-Type': 'text/plain' } // ✓ Poprawnie headers: { 'Content-Type': 'application/json' } Brak serializacji body do stringa: // ✗ Źle body: { query: 'test' } // ✓ Poprawnie body: JSON.stringify({ query: 'test' }) Użycie GET zamiast POST: // ✗ Wszystkie endpointy wymagają POST method: 'GET' // ✓ Poprawnie method: 'POST' Testuj z minimalnym żądaniem Odetnij wszystko do absolutnego minimum, aby odizolować problem: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Pusty obiekt }); console.log(response.status); console.log(await response.json()); Jeśli to działa, stopniowo dodawaj z powrotem parametry, aż do momentu, gdy znów się nie powiedzie. Porównaj z działającym przykładem Przetestuj za pomocą curl, aby zweryfikować swoją implementację: 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}' Jeśli curl działa, ale Twój kod nie, porównaj dokładnie nagłówki i treść (body). Dalej utknąłeś? Skontaktuj się z wsparciem deweloperskim z: Pełna wiadomość o błędzie Nagłówki żądania (ukryj swój pełny klucz API) Treść żądania (body) Status odpowiedzi i treść Język programowania i biblioteka HTTP Fragment kodu (bez ujawniania danych uwierzytelniających)

Question 23

Jak skontaktować się z pomocą techniczną dla deweloperów

Accepted Answer

Potrzebujesz pomocy przy integracji API? Nasz zespół wsparcia dla deweloperów jest tutaj, aby Ci pomóc. Kiedy kontaktować się z pomocą Zgłoś się, jeśli doświadczasz: Problemów z uwierzytelnianiem mimo postępowania zgodnie z poradnikami Niespodziewanych odpowiedzi z błędami Problemów z wydajnością lub wolnych odpowiedzi Pytań dotyczących rozliczeń lub wykorzystania Potrzeby zwiększenia limitów szybkości Wyjaśnienia warunków licencji Pomocy w konkretnych scenariuszach integracji Jak się z nami skontaktować Strona wsparcia: Wejdź na cathopic.com/support i wypełnij formularz kontaktowy. E-mail (jeśli podano): Wyślij szczegóły bezpośrednio na adres e-mail wsparcia dla deweloperów podany w panelu Twojego konta w API. Informacje, które warto podać Pomóż nam pomóc Ci szybciej, podając: 1. Jasny opis problemu Co próbujesz zrobić Co się dzieje, a czego oczekujesz Kiedy problem się rozpoczął 2. Szczegóły techniczne Język programowania i framework Biblioteka HTTP lub SDK, z których korzystasz Ostatnie 4 cyfry Twojego klucza API Komunikaty o błędach (pełny tekst) Kody statusu HTTP 3. Przykład kodu (zanonimizowany) // Usuń swój pełny klucz API! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Tylko ostatnie 4 cyfry 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Szczegóły żądania/odpowiedzi Nagłówki żądania Treść żądania Status odpowiedzi Treść odpowiedzi Znacznik czasu wystąpienia problemu Przed skontaktowaniem się z pomocą Najpierw wypróbuj te kroki, aby zaoszczędzić czas: Sprawdź dokumentację API Przejrzyj pytania w tej sekcji pomocy Przetestuj za pomocą curl, aby zawęzić problem Upewnij się, że Twój klucz API jest aktywny w Ustawienia → API Sprawdź, czy Twoja metoda płatności jest poprawna Czas odpowiedzi Dążymy do tego, aby odpowiadać na zapytania do wsparcia dla deweloperów w dni robocze w ciągu 24–48 godzin. Złożone problemy mogą wymagać dodatkowego czasu na analizę. Dla pilnych problemów Jeśli doświadczasz krytycznej awarii produkcyjnej: Oznacz swoje zgłoszenie jako „Pilne” Podaj e-mail powiązany z kontem, aby umożliwić priorytetową identyfikację Dołącz szczegóły wpływu (liczba dotkniętych użytkowników, wpływ na przychody itd.) Status API Przed zgłoszeniem awarii sprawdź, czy nie ma znanego problemu: Test podstawowej łączności: curl https://api.cathopic.com/resources Sprawdź naszą stronę statusu (jeśli dostępna) Sprawdź ogłoszenia w panelu Twojego konta Dodatkowe zasoby Pełna dokumentacja API: api.cathopic.com/docs Panel konta: cathopic.com/settings/api Ogólne wsparcie: cathopic.com/support Informacje o licencji: cathopic.com/legal/license Jesteśmy tutaj, aby pomóc Ci odnieść sukces w integracji!

Deweloper / API

Zaczynanie pracy

Klucze API, rozliczenia i bezpieczeństwo

Katalog, wyszukiwanie i licencjonowanie

Aplikacje OAuth

Połączone aplikacje

Rozwiązywanie problemów