Question 1

¿Qué es la API de Cathopic?

Accepted Answer

Nuestra API es un servicio RESTful que te permite integrar la biblioteca de medios católicos de Cathopic directamente en tus aplicaciones. Accede a miles de imágenes, vídeos y gráficos de forma programática. Qué puedes hacer Buscar y navegar por nuestro catálogo completo Licenciar recursos para tus usuarios finales automáticamente Descargar en múltiples formatos optimizados para diferentes casos de uso Acceder a metadatos ricos incluyendo etiquetas, descripciones e información litúrgica Arquitectura REST Construida sobre principios REST estándar: URL base: https://api.cathopic.com Formato de datos: Peticiones y respuestas JSON Autenticación: Clave API vía header x-api-key Método HTTP: POST para todos los endpoints Cuatro endpoints principales POST /resources - Buscar en el catálogo POST /resource - Obtener detalles sobre un elemento específico POST /confirm - Licenciar un recurso y obtener URLs de descarga POST /remove - Dejar de licenciar cuando ya no se necesite (solo website) Documentación completa Todo lo que necesitas está disponible en línea: Referencia interactiva de la API: api.cathopic.com/docs Ejemplos de código en múltiples lenguajes Especificaciones detalladas de parámetros Primeros pasos Contacta con nuestro equipo para solicitar acceso a la API Genera tu clave API en Ajustes → API Añade un método de pago para facturación de uso Empieza a construir Consulta las otras preguntas en esta sección para detalles sobre autenticación, facturación y mejores prácticas. Acuerdo de Licencia API Todo el uso de la API está sujeto a nuestro Acuerdo de Licencia API. Puntos clave a entender: Solo uso digital: El contenido solo puede mostrarse en entornos web y de email Sin descargas de archivos: Los usuarios finales no pueden descargar o exportar archivos originales Usos prohibidos: Entrenamiento de AI/ML, materiales impresos y uso offline están estrictamente prohibidos Facturación por uso: Paga solo por el uso real del contenido por tus usuarios finales Al usar la API, aceptas todos los términos del acuerdo de licencia Antes de integrar la API: Revisa el Acuerdo de Licencia API completo Entiende las restricciones y obligaciones Asegúrate de que tu caso de uso cumple con los requisitos de solo digital Planifica tu integración para rastrear el uso con precisión para facturación Para más detalles, ver: ¿Qué puedo construir con la API? (incluye restricciones detalladas) ¿Cómo funcionan las licencias vía API? (detalles completos de licenciamiento) ¿Cómo se factura el uso de la API? (explicación del modelo de facturación)

Question 2

¿Qué puedo construir con la API?

Accepted Answer

La API de Cathopic te permite integrar contenido visual católico directamente en tu aplicación, sitio web o plataforma. Sin embargo, el uso de la API está estrictamente regido por nuestro Acuerdo de Licencia API, que limita el uso a entornos digitales específicos. Qué puedes construir Sistemas de gestión parroquial Permitir que las parroquias añadan imágenes católicas a sus boletines y newsletters Habilitar promoción de eventos con contenido visual relevante Proporcionar imágenes litúrgicas que coincidan con el calendario de la iglesia Crear displays digitales para anuncios parroquiales Plataformas de contenido católico Construir plataformas de blogs para escritores católicos con imágenes integradas Crear sitios web de noticias católicas con visuales relevantes Desarrollar apps devocionales con imágenes diarias y oraciones Diseñar plataformas catequéticas con ayudas visuales educativas Herramientas de email marketing Permitir que ministerios creen newsletters con imágenes católicas Habilitar a organizaciones religiosas diseñar campañas de email Proporcionar plantillas con contenido Cathopic integrado Apoyar campañas de recaudación de fondos con visuales apropiados Constructores de sitios web y CMS Integrar imágenes católicas en plataformas de construcción de sitios web Proporcionar módulos de contenido para organizaciones católicas Habilitar selección de imágenes de Cathopic mediante arrastrar y soltar Crear plantillas específicamente para ministerios católicos Gestión de eventos y redes sociales Ayudar a ministerios a crear gráficos para redes sociales (sin descargar archivos) Diseñar sistemas de invitaciones de eventos con imágenes católicas Construir calendarios de contenido con visuales de temporadas litúrgicas Permitir a organizaciones programar publicaciones con imágenes apropiadas Restricciones críticas que debes seguir La Licencia API prohíbe estrictamente ciertos usos. Violar estas restricciones puede resultar en terminación inmediata: ❌ Entrenamiento de AI/ML (PERMANENTEMENTE PROHIBIDO) No puede usarse para entrenar, ajustar o alimentar ningún modelo de AI/ML No puede crear embeddings, datasets o extractos derivados para AI Esta restricción sobrevive indefinidamente, incluso después de la terminación del acuerdo Aplica a todas las formas de aprendizaje automático e inteligencia artificial ❌ Descargas y exportaciones de archivos Los usuarios finales no pueden descargar o guardar contenido como archivos No puede proporcionar funcionalidad de "descargar" o "exportar" El contenido debe permanecer alojado por Cathopic o en caché autorizado Solo pueden usarse URLs optimizadas para web, no archivos originales ❌ Uso impreso y offline No puede usarse en materiales impresos, folletos o pósters Sin publicidad offline o productos físicos Estrictamente limitado a entornos digitales web y email No puede incorporarse en PDFs destinados a impresión ❌ Reventa y redistribución No puede crear productos que revendan o redistribuyan contenido de Cathopic No puede construir mercados de fotos de stock usando nuestra API No puede ofrecer contenido como producto independiente Debe integrarse como parte de un servicio mayor ❌ Modificación y derivados No puede alterar, transformar o crear obras derivadas No puede aplicar filtros o modificaciones significativas Debe mostrar el contenido como lo proporciona la API El recorte básico y redimensionamiento están permitidos para propósitos de diseño Solo entornos web y email El contenido accedido a través de la API solo puede usarse en: Sitios web: Páginas web públicas o privadas Aplicaciones web: Herramientas y plataformas basadas en navegador Email: Newsletters, campañas y emails transaccionales Blogs: Sistemas de gestión de contenido online Embebidos web: Contenido servido por iframe o API controlado Importante: El contenido debe mostrarse solo en resolución optimizada para web. Los archivos originales de alta resolución nunca son accesibles a través de la API. Requisitos técnicos Tu aplicación debe: Usar HTTPS: Todas las llamadas API y entrega de contenido deben ser seguras Implementar manejo de marca de agua: Comenzar con contenido con marca de agua, solicitar sin marca solo cuando sea necesario Rastrear uso con precisión: Registrar todo uso de contenido para propósitos de facturación Llamar endpoint /confirm: Cuando el usuario final se compromete a usar contenido Llamar endpoint /remove: Cuando el contenido ya no está en uso (detiene la facturación) Prevenir acceso no autorizado: Proteger tus credenciales API Respetar límites de tasa: Seguir los límites establecidos para tu cuenta Tus obligaciones legales Cuando integras la API, debes: Actualizar tus Términos de Uso para informar a los usuarios finales: El contenido no puede descargarse o usarse fuera de tu aplicación El contenido no puede usarse para propósitos de AI/ML El contenido es propiedad de Cathopic y sus creadores El uso se rastrea para facturación y cumplimiento Implementar controles técnicos para prevenir: Descargas con clic derecho (donde sea factible) Acceso directo a URL de archivos originales Extensiones de navegador que permitan descargas Mantener registros de uso para: Verificación de facturación Auditorías de cumplimiento Resolución de disputas Ejemplos de integraciones compatibles ✅ Constructor de boletines parroquiales Las parroquias crean boletines digitales con imágenes católicas El contenido se muestra en el sitio web y en newsletters por email No se proporciona funcionalidad de descarga La facturación rastrea el uso por parroquia y por imagen ✅ Plataforma de email para ministerios Organizaciones religiosas diseñan campañas de email Las imágenes se sirven directamente en emails vía URLs de API Se factura por email enviado con contenido Sin almacenamiento de archivos en dispositivos de usuarios finales ✅ Plataforma CMS católica Constructor de sitios web con biblioteca Cathopic integrada Los usuarios navegan y seleccionan imágenes para sus páginas El contenido se incrusta vía URLs servidas por API Se factura por día de uso por usuario Ejemplos de integraciones prohibidas ❌ Generador de imágenes con IA Usar contenido de Cathopic para entrenar modelos de IA Crear datasets para aprendizaje automático Generar imágenes similares basadas en nuestro contenido ❌ Herramienta de diseño para impresión Permitir a usuarios crear pósters imprimibles Proporcionar descarga para impresión de alta resolución Crear PDFs con contenido Cathopic para imprimir ❌ Mercado de fotos de stock Revender contenido de Cathopic como productos independientes Crear colecciones derivadas de fotos de stock Redistribuir contenido a múltiples clientes Antes de empezar a construir Lectura esencial: Revisa el Acuerdo de Licencia API completo Estudia la documentación técnica en api.cathopic.com/docs Entiende el modelo de facturación en detalle (ver ¿Cómo se factura el uso de la API?) Planifica tu integración para cumplir con todas las restricciones Contáctanos vía soporte si tienes preguntas Recuerda: Al acceder o usar la API, aceptas todos los términos del Acuerdo de Licencia API. El incumplimiento puede resultar en terminación inmediata y consecuencias legales.

Question 3

¿Cuáles son los límites de tasa?

Accepted Answer

Actualmente, no imponemos límites estrictos de peticiones por segundo. Sin embargo, se espera un uso justo para mantener la calidad del servicio para todos. Enfoque actual En lugar de límites duros, fomentamos el uso responsable: Espacía tus peticiones razonablemente Implementa retroceso exponencial cuando ocurran errores Cachea respuestas para evitar llamadas redundantes Contáctanos si anticipas volúmenes de tráfico altos Mejores prácticas Cachea agresivamente: Almacena resultados de búsqueda para consultas comunes Guarda metadatos de medios localmente después de recuperarlos No llames a /confirm múltiples veces para el mismo usuario/recurso Agrupa tus operaciones: Agrupa peticiones relacionadas Añade pequeños retrasos entre lotes Limita conexiones concurrentes (10-20 es razonable) Maneja errores con elegancia: Implementa lógica de reintento con retroceso exponencial No reintentes inmediatamente al fallar Registra errores para monitoreo Tiempos de respuesta esperados Búsqueda /resources: 200-500ms típicamente Detalles /resource: Menos de 100ms Licenciamiento /confirm: 300-800ms Configura el timeout de tu cliente a al menos 30 segundos para manejar respuestas ocasionalmente más lentas. Si alcanzas límites Recibirás un error 429 Too Many Requests. Cuando esto suceda: // Implementa retroceso exponencial 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; } } } Monitorea tu uso Rastrea la actividad de la API en Ajustes → API: Ver total de peticiones realizadas Comprobar licencias activas Revisar tendencias de uso Monitorear patrones inusuales ¿Necesitas límites más altos? Si tu caso de uso legítimo requiere altos volúmenes de peticiones (>1M peticiones/mes), contacta con nuestro equipo para discutir: Tu aplicación y patrones de tráfico Volumen de peticiones esperado Límites de tasa garantizados si se necesitan

Question 4

¿Cómo se factura el uso de la API?

Accepted Answer

La API de Cathopic usa un modelo de facturación de pago por uso basado en el uso real del contenido por tus usuarios finales. Todos los términos de facturación están regidos por nuestro Acuerdo de Licencia API. Dos modelos de facturación La facturación depende de cómo tus usuarios finales consumen el contenido: 1. Uso en sitio web (modelo de Días de Uso) Aplica cuando el contenido se muestra en sitios web, blogs o aplicaciones web Calculado por día calendario que un usuario final accede a contenido específico Fórmula: Total Días de Uso × (Tarifa mensual negociada ÷ 30) La facturación prorrateada diaria asegura que solo pagues por uso real Rastreado separadamente por usuario final y por elemento de contenido 2. Uso en email (modelo Por Email) Aplica cuando el contenido se incorpora en mensajes de email Cobrado por mensaje de email enviado (no por destinatario) Facturación única por email que incluye el contenido Tarifa negociada durante la configuración de acceso a la API Cómo inicia y termina la facturación El contenido con marca de agua es gratis El contenido aparece inicialmente con marca de agua La vista previa con marca de agua no genera cargos Ideal para dejar que los usuarios finales naveguen antes de comprometerse Puede usarse para pruebas y propósitos de prueba La facturación inicia cuando se elimina la marca de agua El usuario final decide usar contenido sin marca de agua Tu aplicación llama a POST /confirm con: media_id: El identificador del contenido usage_type: Ya sea "website" o "email" client_identifier: ID único de tu usuario final La API devuelve URLs permanentes para contenido sin marca de agua La facturación comienza inmediatamente desde este momento Debes almacenar estas URLs y datos de uso para rastreo de facturación La facturación se detiene cuando se elimina el contenido El usuario final elimina o deja de usar el contenido Tu aplicación llama a POST /remove con: media_id: El identificador del contenido client_identifier: El ID del usuario final La facturación para ese uso específico se detiene Debes eliminar las URLs sin marca de agua de tu base de datos Ejemplo de facturación de sitio web Digamos que negociaste una tarifa mensual de para uso ilimitado de contenido: Escenario: La Parroquia A muestra la Imagen #12345 en su página principal Día 1: Llamas a /confirm → La facturación inicia Días 1-15: La imagen permanece en la página principal (15 días de uso) Día 16: La parroquia elimina la imagen, llamas a /remove → La facturación se detiene Cálculo: 15 días × ( ÷ 30 días) = Cobrado: por este uso específico Si la Parroquia B también usa la misma imagen durante 10 días, eso se rastrea por separado y añade más. Ejemplo de facturación de email Digamos que negociaste una tarifa de --.05 por email: Escenario: Un ministerio envía un newsletter con la Imagen #67890 Acción: Llamas a /confirm con usage_type: "email" Resultado: Cargo único de --.05 por ese email Destinatarios: No importa si se envía a 100 o 10,000 personas Cobrado: --.05 total (no por destinatario) Topes de facturación mensual Tu acuerdo puede incluir topes de facturación mensual: Te protege de facturas inesperadamente altas Una vez alcanzado el tope, el uso adicional puede ser gratis o a tarifa reducida El monto específico del tope se negocia durante la configuración de acceso a la API Aplica a los cargos mensuales totales en todos los usuarios finales Facturación y pago Calendario de facturas Facturas emitidas mensualmente dentro de los primeros 10 días de cada mes Cubre todo el uso del mes anterior Desglose detallado de uso por usuario final y elemento de contenido Enviado a la dirección de email asociada con tu cuenta API Procesamiento de pagos Pagos procesados exclusivamente a través de Stripe Cargo automático a tu método de pago registrado Debes mantener información de pago válida en todo momento Recibos proporcionados automáticamente después del pago exitoso Fallos de pago Si el pago falla, el sistema hace 4 intentos de reintento Recibes notificaciones por email sobre problemas de pago Si todos los reintentos fallan, el acceso a la API se suspende El acceso se restaura inmediatamente tras el pago exitoso Las facturas no pagadas pueden acumular cargos por intereses Tus responsabilidades de rastreo Debes mantener registros precisos de: Registros de uso: Cuándo se confirmó y eliminó el contenido IDs de usuarios finales: Qué usuarios accedieron a qué contenido IDs de contenido: Qué elementos de media se usaron Tipos de uso: Sitio web vs email para cada uso Fechas: Fechas de inicio y fin para uso de sitio web URLs: URLs sin marca de agua almacenadas para uso activo Estos registros son esenciales para: Verificar facturas mensuales Resolver disputas de facturación Auditorías de cumplimiento por Cathopic Tus propios informes internos Accediendo a informes de uso Puedes rastrear tu uso de API en tiempo real: Ve a Configuración → API Ver la sección "Uso bajo demanda" Ver estadísticas del período de facturación actual: Costo total acumulado hasta ahora Recuento de usos de sitio web Recuento de usos de email Haz clic en "Ver informe detallado" para desglose por: Usuario final (identificador de cliente) Elemento de contenido Tipo de uso Rango de fechas Costos individuales Exporta informes como CSV para tus registros Negociando tarifas Los precios de API se personalizan para cada cliente: Las tarifas se negocian durante el proceso de solicitud de acceso a la API Basado en tu volumen de uso esperado Basado en tu caso de uso específico y tipo de integración Puede incluir descuentos por volumen para aplicaciones de alto uso Los topes de facturación pueden negociarse para proporcionar costos predecibles Para discutir precios: Visita nuestra página de soporte Selecciona "Solicitud de acceso a API" Describe tu integración y uso esperado Nuestro equipo proporcionará un presupuesto personalizado Entendiendo la licencia completa La facturación es solo un aspecto del acuerdo API. Revisa los términos completos: Lee el Acuerdo de Licencia API completo Entiende las restricciones de uso (solo digital, sin AI/ML, sin descargas) Conoce tus obligaciones para rastreo y reporte Revisa las cláusulas de propiedad intelectual y terminación Para detalles técnicos sobre implementación: Ver los endpoints /confirm y /remove en api.cathopic.com/docs Entiende cómo calcular el uso para tu integración específica Revisa las mejores prácticas para rastreo preciso de facturación Recuerda: El rastreo preciso del uso es tu responsabilidad. Mantén registros detallados para asegurar facturación correcta y cumplimiento con el acuerdo de licencia.

Question 5

Cómo solicitar acceso de desarrollador para la API y OAuth

Accepted Answer

Cathopic revisa una sola vez la cuenta de desarrollador. Esa única aprobación habilita tanto la API comercial como la gestión de aplicaciones OAuth; no tienes que enviar dos solicitudes. Después de aprobarse, tú mismo crearás y gestionarás las API keys y credenciales OAuth desde los Ajustes de Cathopic. Un desarrollador nunca necesita ejecutar comandos ni acceder a la infraestructura de Cathopic. 1. Prepara tu cuenta de Cathopic Crea una cuenta de Cathopic, verifica su email y comprueba que el username y el email de la solicitud coinciden exactamente con esa cuenta. 2. Envía la solicitud de desarrollador Abre el formulario de contacto de Cathopic. Elige Solicitar acceso de desarrollador. Confirma el username de Cathopic y explica el producto, la organización y el uso previsto del catálogo. Envía el formulario. La solicitud aparecerá en el dashboard interno de revisión de Cathopic. 3. Recibe la decisión Cathopic revisará la cuenta y el caso de uso. Cuando se apruebe, el desarrollador recibirá un email con los siguientes pasos y un enlace a Ajustes → Developer / API → Aplicaciones OAuth. Si hace falta más información, Cathopic escribirá al email de la solicitud. 4. Crea la aplicación Elige una aplicación web confidencial si el producto tiene un backend seguro, o una aplicación pública con PKCE para clientes web sin backend, móviles o de escritorio. Introduce su nombre público, descripción, website, política de privacidad, contacto de seguridad, callbacks exactos y solo los scopes necesarios. 5. Guarda las credenciales El client ID identifica la integración y lo comparten todos los usuarios de ese producto. La autorización y los tokens son independientes para cada cuenta de Cathopic. El client secret de una aplicación confidencial solo se muestra una vez y debe guardarse cifrado en el servidor de la aplicación. Nunca lo incluyas en código del navegador, websites generados, logs, mensajes de soporte ni repositorios públicos. Desde la misma página podrás editar callbacks y scopes, rotar el secreto o revocar la aplicación.

Question 6

¿Cómo funcionan las claves API?

Accepted Answer

Las claves API son tus credenciales de autenticación para acceder a la API de Cathopic. Entender cómo funcionan es esencial para una integración API segura y efectiva. ¿Qué es una clave API? Una clave API es un token secreto único que identifica tu aplicación y la autoriza a acceder a la API de Cathopic: Una cadena alfanumérica larga (ej., sk_live_abc123xyz789...) Actúa como autenticación y autorización Vinculada a tu cuenta de Cathopic y facturación Puede estar activa o inactiva Ciclo de vida de la clave Creación: Genera claves en Ajustes → API Dale a cada clave un nombre descriptivo ("Website Producción", "Staging", "App Móvil") Copia la clave completa inmediatamente - solo se muestra una vez Almacena de forma segura (variables de entorno, gestor de secretos, gestor de contraseñas) Uso: Incluye en el header HTTP x-api-key con cada petición Las claves se validan del lado del servidor en cada petición Todo el uso de la API se rastrea y factura a tu cuenta Desactivación: Las claves pueden desactivarse temporalmente sin eliminarlas Útil para solucionar problemas o pausar una integración específica Pueden reactivarse en cualquier momento Eliminación: Elimina permanentemente la clave No se puede deshacer o recuperar Todas las peticiones con esa clave fallarán inmediatamente Pautas de gestión de claves Seguridad: Nunca las commits a control de versiones: Usa archivos .env y añádelos a .gitignore Nunca las expongas en código del lado del cliente: Las claves API solo deben usarse del lado del servidor Usa variables de entorno: Almacena las claves en process.env.CATHOPIC_API_KEY o equivalente Rota regularmente: Cambia las claves periódicamente (trimestral o después de cambios de equipo) Usa claves separadas por entorno: Diferentes claves para dev, staging y producción Organización: Nombres descriptivos: Nombra las claves por propósito: "Website Producción", "App iOS", "Sistema Email" Documenta la propiedad: Rastrea qué miembro del equipo creó cada clave Auditorías regulares: Revisa las claves activas mensualmente y elimina las no usadas Múltiples claves API Puedes crear múltiples claves API para diferentes propósitos: Por entorno: Claves separadas para desarrollo, staging, producción Por aplicación: Diferentes claves para sitio web, app móvil, herramientas internas Por miembro del equipo: Claves individuales para desarrolladores (más fácil de rastrear y revocar) Todas las claves bajo tu cuenta comparten la misma facturación. El uso de todas las claves se combina en tu factura mensual. Monitorear el uso de claves Rastrea la actividad de cada clave: Ve a Ajustes → API Ver lista de todas las claves con fechas de último uso Haz clic en una clave para ver estadísticas de uso detalladas Monitorea por actividad inesperada Qué hacer si una clave está comprometida Si crees que una clave API ha sido expuesta: Elimina o desactiva inmediatamente la clave en Ajustes → API Genera una nueva clave de reemplazo Actualiza tu aplicación con la nueva clave Revisa los logs de uso para cualquier actividad sospechosa Contacta con soporte si ves uso no autorizado Ejemplo: Almacenar claves de forma segura Node.js con variables de entorno: // archivo .env (¡añadir a .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Tu código 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: 'Jesús' }) }); Python con variables de entorno: 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': 'Jesús'} )

Question 7

¿Cómo autent ico las peticiones?

Accepted Answer

Todas las peticiones a la API de Cathopic deben estar autenticadas usando tu clave API. Aquí está cómo autenticar correctamente tus llamadas a la API. Método de autenticación La API de Cathopic usa autenticación por clave API vía headers HTTP: Nombre del header: x-api-key Valor del header: Tu clave API completa Requerido para: Todos los endpoints de la API Sensible a mayúsculas: Los nombres y valores de headers deben coincidir exactamente Ejemplo básico de autenticación cURL: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: TU_CLAVE_API" \ -H "Content-Type: application/json" \ -d '{ "query": "Virgen María", "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: 'Virgen María', 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: 'Virgen María', 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': 'Virgen María', 'page': 1, 'page_size': 20, 'order': 'popular' } ) data = response.json() print(data) PHP (cURL):

Question 8

¿Cómo roto una clave API?

Accepted Answer

Rotar las claves API regularmente es una práctica de seguridad importante. Aquí está cómo rotar de forma segura tus claves sin interrumpir tu servicio. ¿Por qué rotar claves API? Mejor práctica de seguridad: Limita la exposición si una clave alguna vez se ve comprometida Cambios de miembros del equipo: Cuando desarrolladores se van o cambian de rol Sospecha de compromiso: Si crees que una clave puede haber sido expuesta Cumplimiento: Algunas políticas de seguridad requieren rotación periódica de claves Cambios de entorno: Al migrar infraestructura o refactorizar Proceso de rotación estándar (sin tiempo de inactividad) Paso 1: Crear una nueva clave Inicia sesión en Ajustes → API Haz clic en "Crear nueva clave API" Nómbrala descriptivamente (ej., "Web Producción v2") Copia la nueva clave inmediatamente - solo se muestra una vez Almacénala de forma segura Paso 2: Actualizar tu aplicación Despliega la nueva clave a tu aplicación (variables de entorno, gestor de secretos, etc.) Reinicia tu aplicación para cargar la nueva clave Verifica que la nueva clave funciona correctamente Monitorea por cualquier error Paso 3: Monitorear la transición Mantén ambas claves activas temporalmente Verifica Ajustes → API para ver fechas de "Último uso" Espera hasta que la clave antigua no muestre actividad reciente Asegura que todas las instancias/servicios han cambiado a la nueva clave Paso 4: Eliminar la clave antigua Una vez confirmado que la clave antigua ya no está en uso Elimina o desactiva la clave antigua en Ajustes → API Documenta la rotación para tus registros Proceso de rotación rápida (si está comprometida) Si una clave está definitivamente comprometida y necesitas actuar inmediatamente: Elimina primero la clave comprometida en Ajustes → API Crea una nueva clave de reemplazo Despliega rápidamente la nueva clave a todas las aplicaciones Acepta un breve tiempo de inactividad para prevenir acceso no autorizado Monitorea logs de uso para cualquier actividad sospechosa Contacta con soporte si es necesario Estrategia de rotación multi-entorno Para sistemas de producción, usa un enfoque por fases: Semana 1: Desarrollo Crear y desplegar nueva clave al entorno dev Probar exhaustivamente Semana 2: Staging Desplegar nueva clave a staging Ejecutar pruebas de integración Monitorear por problemas Semana 3: Producción Desplegar nueva clave a producción durante período de bajo tráfico Monitorear de cerca Mantener clave antigua activa por 24-48 horas como respaldo Semana 4: Limpieza Verificar que clave antigua no muestra actividad Eliminar clave antigua Actualizar documentación Ejemplo de automatización Script para ayudar a verificar que la rotación de clave está completa: #!/bin/bash # check-api-key.sh OLD_KEY="sk_live_OLD123..." NEW_KEY="sk_live_NEW789..." echo "Probando clave antigua..." 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 "Probando clave nueva..." 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 "Estado clave antigua: ${OLD_RESPONSE: -3}" echo "Estado clave nueva: ${NEW_RESPONSE: -3}" if [ "${NEW_RESPONSE: -3}" == "200" ]; then echo "✅ ¡La nueva clave funciona!" else echo "❌ ¡La nueva clave falló!" fi Mejores prácticas Rota regularmente: Cada 90 días para claves de producción Documenta rotaciones: Mantén un log de cuándo se rotaron las claves y por qué Prueba antes de eliminar: Siempre verifica que la nueva clave funciona antes de eliminar la antigua Usa múltiples claves: Claves separadas por entorno facilitan la rotación Automatiza donde sea posible: Usa herramientas de gestión de secretos que soporten rotación automática Lista de verificación post-rotación Confirma estos elementos después de rotar: ✅ Todas las instancias de producción usando nueva clave ✅ Todos los entornos staging/dev actualizados (si usan la misma clave) ✅ Variables de entorno actualizadas ✅ Secretos de CI/CD actualizados ✅ Documentación actualizada ✅ Miembros del equipo notificados ✅ Clave antigua eliminada ✅ Rotación registrada para propósitos de auditoría

Question 9

¿Cómo aseguro mis credenciales?

Accepted Answer

Tus claves API son la puerta de entrada a tu cuenta de Cathopic. Mantenerlas seguras previene el acceso no autorizado y protege contra fraude de facturación. La regla de oro: Mantén las claves secretas Trata tus claves API como contraseñas. Errores comunes a evitar: Escribir claves directamente en el código fuente Commitear claves a Git u otro control de versiones Usar claves en JavaScript del lado del cliente o apps móviles Compartir claves por email, Slack o apps de mensajería Almacenar claves en ubicaciones públicas (repos públicos, wikis, etc.) Usa variables de entorno Almacena claves en variables de entorno en lugar de código: // archivo .env (¡añadir a .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Tu código require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Esto separa datos sensibles de tu código base y hace que la rotación de claves sea más fácil. Solo del lado del servidor Las llamadas API deben ocurrir desde tus servidores backend, no navegadores o apps móviles. Si los usuarios necesitan acceso a recursos de Cathopic: Crea un endpoint backend que use tu clave API Tu frontend llama a TU endpoint, no a Cathopic directamente Tu servidor valida la petición del usuario antes de llamar a Cathopic Restringe por IP (si es posible) Algunas infraestructuras permiten whitelist de IPs. Si tus llamadas API vienen de IPs conocidas: Configura reglas de firewall para limitar acceso saliente Usa cuentas de servicio dedicadas con permisos mínimos Monitorea logs de acceso en busca de actividad inusual Si una clave está comprometida Si sospechas que una clave ha sido expuesta: Genera una nueva clave API inmediatamente Actualiza tu aplicación con la nueva clave Elimina la clave comprometida Revisa logs de uso en busca de actividad sospechosa Contacta con soporte si ves cargos no autorizados Gestiona tus claves de forma segura en Ajustes → API.

Question 10

Errores comunes de autenticación

Accepted Answer

Si tienes problemas autenticando con la API de Cathopic, estos son los errores más comunes y cómo solucionarlos. 401 Unauthorized El error de autenticación más común: HTTP 401 Unauthorized { "message": "Unauthorized" } Causas comunes: Falta el header x-api-key Clave API inválida o expirada Error tipográfico en la clave API Espacios en blanco antes/después de la clave Clave no cargada desde variable de entorno Cómo solucionar: Verifica que el nombre del header sea exactamente x-api-key (minúsculas) Copia tu clave API de nuevo desde Ajustes → API Comprueba que las variables de entorno están cargadas: console.log(process.env.CATHOPIC_API_KEY) Recorta espacios en blanco: apiKey.trim() Verifica que la clave está activa (no eliminada o desactivada) Nombre de header incorrecto La API requiere x-api-key, no otros nombres de header comunes: // ❌ INCORRECTO Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRECTO x-api-key: sk_live_abc... Error de token no autorizado HTTP 401 Unauthorized { "error": "Unauthorized token" } Causa: Tu clave API ha sido desactivada o eliminada. Cómo solucionar: Comprueba si la clave sigue activa en Ajustes → API Reactiva la clave si fue desactivada Genera una nueva clave si la antigua fue eliminada Variable de entorno no cargada Tu código no puede encontrar la clave API: // Devuelve undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Cómo solucionar: Node.js: // Asegúrate de que .env está cargado require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; if (!apiKey) { throw new Error('CATHOPIC_API_KEY no está configurada'); } 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 no está configurada') Error de exposición del lado del cliente Intentando usar clave API en JavaScript del navegador: // ❌ Esto fallará (las claves no funcionan en navegadores) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Cómo solucionar: Crea un endpoint del lado del servidor que haga proxy de peticiones a la API de Cathopic. Consulta "¿Cómo aseguro mis credenciales?" para ejemplos. Errores CORS Si ves errores CORS en la consola del navegador: Access to fetch has been blocked by CORS policy... Causa: Estás intentando llamar a la API directamente desde JavaScript del lado del cliente. Cómo solucionar: La API de Cathopic es solo del lado del servidor. Debes crear un proxy de peticiones a través de tu propio backend. Probar autenticación Prueba rápida para verificar tu configuración: curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: TU_CLAVE" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Busca respuesta HTTP 200 # Si es 401, verifica la clave cuidadosamente Lista de verificación de depuración Si la autenticación aún falla: ☐ El nombre del header es x-api-key (sensible a mayúsculas) ☐ La clave API es la clave completa (comienza con sk_live_ o similar) ☐ Sin prefijo Bearer o comillas alrededor de la clave ☐ La variable de entorno está configurada y cargada ☐ La petición se envía desde el lado del servidor, no del navegador ☐ La clave está activa en Ajustes → API ☐ El método de pago está añadido y es válido Si los problemas persisten, contacta con soporte para desarrolladores con: El mensaje de error Últimos 4 dígitos de tu clave API Lenguaje de programación y framework Código de ejemplo (sin exponer tu clave completa)

Question 11

Parámetros de búsqueda disponibles

Accepted Answer

El endpoint /resources acepta varios parámetros para refinar tus resultados de búsqueda. Búsqueda básica POST https://api.cathopic.com/resources { "query": "San Francisco", "page": 1, "page_size": 20, "order": "popular" } Parámetros query (string, opcional) Tu término de búsqueda. Déjalo vacío para obtener todos los recursos. Ejemplos: "Virgen María", "Eucaristía", "cruz" Soporta coincidencia difusa y tolerancia a errores tipográficos Busca en títulos, descripciones y etiquetas page (integer, por defecto: 1) Qué página de resultados devolver. Comienza en 1. page_size (integer, por defecto: 20, máx: 100) Número de resultados por página. El máximo es 100 para mantener el rendimiento. order (string, por defecto: "popular") Cómo ordenar los resultados: popular - Recursos más descargados primero recent - Subidas más recientes primero Estructura de respuesta { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Título del recurso", "description": "Descripción del recurso", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["etiqueta1", "etiqueta2"] } ] } Ejemplos prácticos Obtener los 10 recursos más populares sobre oración: { "query": "oración", "page": 1, "page_size": 10, "order": "popular" } Obtener subidas recientes, sin término de búsqueda específico: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Navegar página 3 de imágenes de santos: { "query": "santos", "page": 3, "page_size": 20, "order": "popular" } Para la referencia completa de la API, visita api.cathopic.com/docs.

Question 12

¿Cómo descargo imágenes vía API?

Accepted Answer

Aclaración importante: La API no permite "descargar" en el sentido tradicional. En su lugar, proporciona URLs permanentes a contenido optimizado para web que tu aplicación sirve a los usuarios finales. Esto está regido por nuestro Acuerdo de Licencia API. NO descargas archivos La API de Cathopic funciona fundamentalmente diferente de las descargas tradicionales: Sin transferencias de archivos: Nunca recibes o almacenas los archivos de imagen/video reales Acceso basado en URL: La API proporciona URLs que apuntan a contenido alojado por Cathopic Solo optimizado para web: El contenido se sirve en resolución adecuada para visualización digital Sin archivos originales: Los originales de alta resolución nunca son accesibles vía API Siempre alojado: El contenido permanece en servidores de Cathopic o CDN autorizado Resoluciones disponibles La API proporciona tres tamaños optimizados para web: Pequeña: Adecuada para miniaturas y embebidos pequeños (típicamente ~400px de ancho) Mediana: Buena para contenido web estándar (típicamente ~800px de ancho) Grande: Mejor calidad para visualización web (típicamente ~1200px de ancho) Restricciones críticas: Los archivos originales de alta resolución NUNCA se proporcionan Las resoluciones están optimizadas para visualización en pantalla, no impresión Los tamaños de archivo están comprimidos para entrega web rápida No puedes solicitar resoluciones personalizadas o calidad original Para términos completos, lee el Acuerdo de Licencia API completo y revisa la documentación técnica en api.cathopic.com/docs. Descargar imágenes involucra dos pasos: licenciar el recurso con /confirm, luego usar las URLs devueltas. Paso 1: Licenciar el recurso Llama a /confirm para licenciar un recurso para un usuario final específico: POST https://api.cathopic.com/confirm x-api-key: TU_CLAVE_API { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parámetros: media_id - El ID del recurso de tus resultados de búsqueda usage_type - "website" o "email" client_identifier - ID único para tu usuario final Paso 2: Usar las URLs de descarga La respuesta contiene URLs permanentes en múltiples formatos: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Importante: Almacena las URLs Las URLs devueltas son permanentes - almacénalas en tu base de datos: // Después de llamar a /confirm const response = await api.confirm(mediaId, userId); // Guardar en tu base de datos await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // La próxima vez, recuperar de la BD en lugar de llamar a /confirm de nuevo Elegir el formato correcto Formato AVIF: Archivos más pequeños (mejor rendimiento) Mejor compresión Recomendado para navegadores modernos No soportado en navegadores antiguos Formato JPEG: Compatibilidad universal Archivos más grandes Usar como fallback para navegadores antiguos Recordatorio crítico ⚠️ Siempre verifica tu base de datos antes de llamar a /confirm. Llamarlo múltiples veces para el mismo usuario y recurso creará cargos duplicados. Documentación completa en api.cathopic.com/docs.

Question 13

Manejo de paginación y ordenamiento

Accepted Answer

La API devuelve resultados de búsqueda en páginas. Aquí está cómo navegar eficientemente a través de grandes conjuntos de resultados. Paginación básica POST /resources { "query": "santos", "page": 1, "page_size": 20 } Respuesta: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 elementos ... ] } La respuesta te dice que hay 1,523 resultados totales, y estás viendo la página 1 con 20 elementos. Calcular total de páginas const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 páginas Cargar siguiente página // Siguiente página simple currentPage++; // O construir UI de paginación for (let page = 1; page <= totalPages; page++) { // Crear botón de página } Optimizar tamaño de página Elige el tamaño de página según tu caso de uso: Páginas pequeñas (10-20 elementos): Carga inicial más rápida Bueno para búsqueda de cara al usuario Se necesitan más peticiones API Páginas grandes (50-100 elementos): Menos peticiones API Bueno para procesamiento por lotes Peticiones individuales más lentas El máximo es 100 elementos Opciones de ordenamiento Popular (por defecto): { "order": "popular" } Devuelve recursos más descargados primero. Mejor para mostrar contenido de alta calidad y probado. Reciente: { "order": "recent" } Devuelve subidas más recientes primero. Bueno para descubrir contenido fresco. Ejemplo de scroll infinito let currentPage = 1; const pageSize = 20; let isLoading = false; let hasMore = true; async function loadMore() { if (isLoading || !hasMore) return; isLoading = true; const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'oración', page: currentPage, page_size: pageSize, order: 'popular' }) }); const data = await response.json(); // Añadir resultados a tu UI appendResults(data.results); // Verificar si hay más páginas const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Activar en scroll window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Consejos de rendimiento Cachea resultados localmente para evitar peticiones redundantes Usa tamaños de página apropiados para tu caso de uso Implementa estados de carga para mejor UX Considera virtualización para listas muy grandes No obtengas todas las páginas a la vez - carga bajo demanda Para más detalles, consulta la documentación completa en api.cathopic.com/docs.

Question 14

Cómo buscar en el catálogo y usar las URLs de preview de Cathopic

Accepted Answer

Usa GET /api/v2/catalog con catalog.read. Utiliza la capa existente de búsqueda fuzzy tolerante a errores y los mismos modelos canónicos del grid de la web. Parámetros q o query: texto de hasta 250 caracteres. type: photo, video, graphic, artwork, ai o all. orientation: landscape, portrait, square o all. sort: most_recent, popular o popular_alltime. page, per_page hasta 50 y locale. GET /api/v2/catalog?q=adoracion&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUsar las URLs sin modificar Cada resultado incluye preview.url y preview.transformation_url_template. Proceden exactamente del mismo presenter, host CDN, ruta y reglas de marca de agua del grid de cathopic.com. Úsalas sin cambios para reutilizar las claves de caché existentes de Cloudflare. No subas otra copia ni la pases por un proxy innecesario. No añadas parámetros para invalidar la caché. Sustituye <OPTIONS> solo por opciones estables de Cloudflare. Las previews nunca consumen descargas. already_licensed incluye derechos individuales y de equipo.

Question 15

Cómo licenciar y descargar un recurso de forma segura

Accepted Answer

La creación de licencia y la URL original son operaciones separadas para que los reintentos sean seguros y las URLs nuevas no vuelvan a cobrar. 1. Crear la licencia POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Usa una clave única de 8 a 160 caracteres ASCII imprimibles para el intento lógico y consérvala al reintentar. Una licencia nueva devuelve 201; una repetición devuelve 200 con el mismo ID. Cathopic primero verifica el original. En una transacción bloquea la suscripción individual o de equipo, comprueba el acceso y los derechos compartidos, consume como máximo una descarga y registra derecho, historial y licencia. 2. Solicitar la URL original POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENLa URL caduca a los cinco minutos. Solicita otra URL para volver a descargar; no crees otra licencia. Cathopic deriva la ruta y nunca acepta una ruta arbitraria. Errores importantes subscription_required: no hay acceso de pago activo. media_type_not_in_plan: tipo no incluido. download_balance_exhausted: no quedan descargas. file_unavailable: falta el original; no se cobra. idempotency_key_conflict: clave usada para otro media ID. Conserva X-Request-Id para soporte, pero nunca registres tokens, secretos ni URLs firmadas. Aplica espera con jitter tras 429 o errores 5xx transitorios.

Question 16

Inicio rápido de OAuth 2.0 para aplicaciones conectadas a Cathopic

Accepted Answer

Las aplicaciones conectadas de Cathopic usan OAuth 2.0 Authorization Code con PKCE S256 obligatorio. La misma aprobación de desarrollador también habilita la API comercial de Cathopic, pero las conexiones OAuth usan tokens de usuario y el plan del usuario conectado en lugar de API keys y facturación por uso de la API. 1. Obtén acceso y registra la aplicación Envía la única solicitud de acceso de desarrollador desde el formulario de contacto. Cuando Cathopic apruebe la cuenta por email, abre Ajustes → Developer / API → Aplicaciones OAuth, crea la aplicación, registra sus callbacks exactos y scopes necesarios, y guarda el secreto de un solo uso si es confidencial. 2. Descubre el servidor de autorización GET https://cathopic.com/.well-known/oauth-authorization-server3. Redirige al usuario GET https://cathopic.com/oauth/authorize ?client_id=CLIENT_ID &redirect_uri=CALLBACK_EXACTO &response_type=code &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read &state=ESTADO_IMPREDECIBLE &code_challenge=BASE64URL_SHA256_VERIFIER &code_challenge_method=S256 &ui_locales=esConstruye una sola URL; los saltos de línea solo facilitan la lectura. Genera valores nuevos y de alta entropía para state y PKCE en cada intento. ui_locales es opcional y permite pedir un idioma compatible, como es o en. Si hace falta iniciar sesión, Cathopic recupera la misma solicitud de autorización y muestra después la pantalla de permisos. 4. Valida el callback e intercambia el código Compara el state recibido antes de intercambiar el código. El callback debe coincidir byte a byte. POST https://cathopic.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=CALLBACK_EXACTO&code=CODIGO&code_verifier=VERIFICADORLas aplicaciones públicas omiten client_secret. Guarda los tokens y secretos confidenciales solo en el servidor y cifrados. Los access tokens duran 30 minutos; los refresh tokens duran hasta 30 días y rotan al usarse. Comprobaciones habituales Un callback rechazado suele diferir del registrado en esquema, host, puerto, path, mayúsculas o barra final. invalid_request antes del consentimiento indica que falta PKCE S256, el challenge o state, o que su formato no es válido. invalid_grant suele indicar que se reutilizó un código o refresh token rotado, o que cambiaron el callback o el verifier. Tras un 401, refresca una vez; si falla, pide al usuario que vuelva a conectar. Un 403 indica que falta el scope necesario. Consulta el contrato OpenAPI completo y la guía detallada de integración de aplicaciones conectadas.

Question 17

¿Cómo conecto Cathopic con otra aplicación?

Accepted Answer

Una plataforma aprobada puede permitirte usar el catálogo de Cathopic sin recibir tu contraseña. Te envía a una página segura en cathopic.com, donde inicias sesión y revisas los permisos exactos solicitados. Conectar tu cuenta En la otra aplicación, elige el conector de Cathopic y pulsa Conectar o Iniciar sesión con Cathopic. Confirma que el navegador está en cathopic.com. Inicia sesión en Cathopic si es necesario. Cathopic volverá a la misma solicitud de permisos en lugar de abrir tu perfil. Lee todos los permisos. Pueden incluir tu identidad, acceso al catálogo, saldo de suscripción o capacidad para licenciar recursos. Elige Permitir acceso. Cathopic solo te devuelve al callback exacto registrado para esa aplicación. Idioma y seguridad de la cuenta La aplicación puede solicitar un idioma compatible para las pantallas de login y permisos. Cathopic mantiene ese idioma durante toda la conexión. La aplicación recibe tokens de corta duración, nunca tu contraseña, y solo puede realizar las acciones indicadas en la pantalla de permisos. Si no confías en la solicitud Elige Cancelar. No apruebes la conexión si no reconoces la aplicación, los permisos parecen innecesarios o el navegador no muestra el dominio de Cathopic. Más adelante puedes revocar el acceso desde Ajustes → Developer / API → Aplicaciones conectadas.

Question 18

¿Las aplicaciones conectadas consumen mis descargas y cómo las desconecto?

Accepted Answer

Buscar y mostrar previews con marca de agua nunca consume una descarga. Solo puede consumirse una cuando una aplicación conectada pide licenciar un recurso de pago. Cuándo se consume una descarga El recurso es de pago, el plan incluye ese tipo y ni tú ni la suscripción de equipo actual lo habéis licenciado antes. El plan tiene saldo limitado. Los planes ilimitados registran la licencia sin reducir un número. El original está disponible. Cathopic lo comprueba antes de cambiar el saldo. Cuándo no se consume otra descarga El recurso es gratuito. Tú u otro miembro con la misma suscripción de equipo ya lo habéis licenciado. Solicitas otro enlace para una licencia existente. La aplicación repite la solicitud con la misma clave de idempotencia. Los miembros consumen el saldo compartido del propietario. Cathopic es siempre la fuente de verdad. Desconectar una aplicación Abre Ajustes → Developer / API → Aplicaciones conectadas. Revisa la aplicación y sus permisos. Pulsa Desconectar y confirma. Todos sus tokens activos se revocan inmediatamente. Las licencias y el historial permanecen.

Question 19

Códigos de error comunes de la API

Accepted Answer

Entender las respuestas de error te ayuda a depurar problemas rápidamente. Estos son los errores más comunes que encontrarás. 400 Bad Request { "error": "media_id is required" } Causas: Falta parámetro requerido Formato de parámetro inválido JSON mal formado Solución: Verifica que tu cuerpo de petición coincida con la especificación de la API en api.cathopic.com/docs. 401 Unauthorized { "message": "Unauthorized" } o { "error": "Unauthorized token" } Causas: Clave API faltante o inválida Clave API desactivada Nombre de header incorrecto Solución: Verifica que tu header x-api-key sea correcto y la clave esté activa en Ajustes → API. 404 Not Found { "error": "No file found for media_id 1234" } o { "error": "Media item not found" } Causas: El recurso no existe El recurso ha sido eliminado media_id incorrecto Solución: Verifica que el media_id existe buscando primero con /resources. 429 Too Many Requests { "error": "Limit exceed." } Causas: Demasiadas peticiones en poco tiempo Límite de tasa excedido Solución: Implementa retroceso exponencial. Espera y reintenta con retrasos crecientes (1s, 2s, 4s, etc.). 500 Internal Server Error { "error": "Internal server error" } Causas: Problema temporal del servidor Condición inesperada Solución: Espera un momento y reintenta. Si persiste, contacta con soporte. Ejemplo de manejo de errores 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('Petición incorrecta:', error); break; case 401: console.error('No autorizado. Verifica tu clave API.'); break; case 404: console.error('Recurso no encontrado:', error); break; case 429: console.error('Límite de tasa. Implementando retroceso...'); await sleep(5000); return searchWithErrorHandling(query); // Reintentar case 500: console.error('Error de servidor. Reintentando en 10s...'); await sleep(10000); return searchWithErrorHandling(query); default: console.error('Error desconocido:', error); } throw new Error(`Error de API: ${response.status}`); } return await response.json(); } catch (error) { console.error('Petición fallida:', error); throw error; } } Para errores persistentes, consulta la documentación completa de la API o contacta con soporte.

Question 20

Errores de límite de tasa

Accepted Answer

Si ves 429 Too Many Requests, estás accediendo a la API con demasiada frecuencia. Aquí está cómo manejarlo correctamente. El error HTTP 429 Too Many Requests { "error": "Limit exceed." } Por qué sucede esto Los límites de tasa protegen la API del uso excesivo: Demasiadas peticiones en poco tiempo Polling o scraping agresivo Sin retraso entre peticiones Peticiones concurrentes sin limitación Estrategia de retroceso exponencial La mejor manera de manejar límites de tasa es el retroceso exponencial - espera más tiempo después de cada reintento: 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(`Límite de tasa. Esperando ${waitTime}ms antes del reintento ${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('Reintentos máximos excedidos'); } Prevenir límites de tasa Añade retrasos entre peticiones: // Mal: Peticiones rápidas consecutivas for (const id of mediaIds) { await api.getResource(id); // Sin retraso } // Bien: Peticiones con limitación for (const id of mediaIds) { await api.getResource(id); await sleep(500); // 500ms de retraso } Agrupa tus operaciones: // Procesar en lotes de 10 con retrasos const batchSize = 10; for (let i = 0; i < mediaIds.length; i += batchSize) { const batch = mediaIds.slice(i, i + batchSize); await Promise.all(batch.map(id => api.getResource(id))); if (i + batchSize < mediaIds.length) { await sleep(2000); // 2s entre lotes } } Cachea respuestas: 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; } Qué NO hacer ❌ Reintentar inmediatamente sin retraso ❌ Hacer peticiones paralelas sin límite ❌ Ignorar errores 429 ❌ Usar retrasos fijos cortos (siempre usa retroceso exponencial) Si los problemas persisten Contacta con soporte para desarrolladores si legítimamente necesitas límites de tasa más altos para tu caso de uso. Proporciona detalles sobre: Tu aplicación y caso de uso Volumen de peticiones esperado Implementación actual (con retroceso)

Question 21

Problemas de timeout y red

Accepted Answer

Los problemas de red pueden causar que las peticiones de API fallen. Aquí está cómo manejar timeouts y problemas de conexión de forma elegante. Configurar timeouts apropiados Siempre configura timeouts para evitar peticiones colgadas: // JavaScript con fetch const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); // 30s try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesús' }), signal: controller.signal }); clearTimeout(timeout); return await response.json(); } catch (error) { clearTimeout(timeout); if (error.name === 'AbortError') { console.error('Petición agotó timeout después de 30s'); } else { console.error('Error de red:', error); } throw error; } // Python con requests import requests from requests.exceptions import Timeout, RequestException try: response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesús'}, timeout=30 # 30 segundos ) return response.json() except Timeout: print('Petición agotó timeout después de 30s') raise except RequestException as e: print(f'Error de red: {e}') raise Errores de red comunes Timeout de conexión: No se puede establecer conexión al servidor Usualmente problema de red o firewall Verifica conexión a internet Verifica que firewall permita HTTPS a api.cathopic.com Timeout de lectura: Conexión establecida pero sin respuesta El servidor puede estar lento o sobrecargado Aumenta timeout o reintenta más tarde Fallo de resolución DNS: No puede resolver api.cathopic.com Problema con servidor DNS Inténtalo de nuevo o verifica configuración DNS Reintentar con retroceso 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(`Todos los ${maxRetries} intentos fallaron`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Intento ${attempt + 1} falló. Reintentando en ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Valores de timeout recomendados Timeout de conexión: 10 segundos Timeout de lectura: 30 segundos Búsqueda /resources: 30 segundos Licenciamiento /confirm: 30 segundos Depurar problemas de red Usa curl para probar conectividad: # Probar conectividad básica curl -v https://api.cathopic.com/resources # Probar con timeout curl --max-time 30 -X POST https://api.cathopic.com/resources \ -H "x-api-key: TU_CLAVE" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Verifica: ✓ DNS resuelve api.cathopic.com ✓ Conexión SSL/TLS tiene éxito ✓ Se recibe respuesta HTTP ✓ Tiempo de respuesta razonable (<5s típicamente) Si los problemas persisten, contacta con soporte con detalles de diagnóstico de red.

Question 22

Depurar peticiones fallidas

Accepted Answer

Cuando las peticiones fallan, la depuración sistemática ayuda a identificar el problema rápidamente. Habilitar registro detallado async function debugRequest(url, options) { console.log('=== Petición API ==="); console.log('URL:', url); console.log('Método:', 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('=== Respuesta API ==="); console.log('Estado:', response.status, response.statusText); console.log('Duración:', 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('=== Petición Fallida ==="); console.error('Error:', error.message); console.error('Duración:', Date.now() - startTime + 'ms'); throw error; } } Verifica esto primero 1. La clave API es correcta: console.log('Clave API comienza con:', apiKey.substring(0, 10)); console.log('Longitud clave API:', apiKey.length); 2. Nombre de header es exacto: // Debe ser minúsculas 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Correcto 'X-API-Key': apiKey, // ✗ Incorrecto 'api-key': apiKey, // ✗ Incorrecto } 3. JSON es válido: try { const body = JSON.stringify({ query: 'test' }); console.log('JSON válido:', body); } catch (e) { console.error('JSON inválido:', e); } 4. La petición llega al servidor: // Usa pestaña Network de DevTools del navegador o curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: TU_CLAVE" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Errores comunes Content-Type incorrecto: // ✗ Incorrecto headers: { 'Content-Type': 'text/plain' } // ✓ Correcto headers: { 'Content-Type': 'application/json' } No convertir body a string: // ✗ Incorrecto body: { query: 'test' } // ✓ Correcto body: JSON.stringify({ query: 'test' }) Usar GET en lugar de POST: // ✗ Todos los endpoints requieren POST method: 'GET' // ✓ Correcto method: 'POST' Probar con petición mínima Reduce al mínimo para aislar el problema: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'TU_CLAVE_REAL_AQUI', 'Content-Type': 'application/json' }, body: '{}' // Objeto vacío }); console.log(response.status); console.log(await response.json()); Si esto funciona, añade gradualmente parámetros hasta que falle. Comparar con ejemplo que funciona Prueba con curl para verificar tu implementación: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: TU_CLAVE" \ -H "Content-Type: application/json" \ -d '{"query": "Jesús", "page": 1, "page_size": 5}' Si curl funciona pero tu código no, compara los headers y body exactos. ¿Aún atascado? Contacta con soporte para desarrolladores con: Mensaje de error completo Headers de petición (oculta tu clave API completa) Body de petición Estado y body de respuesta Lenguaje de programación y biblioteca HTTP Fragmento de código (sin exponer credenciales)

Question 23

Cómo contactar con soporte para desarrolladores

Accepted Answer

¿Necesitas ayuda con tu integración API? Nuestro equipo de soporte para desarrolladores está aquí para asistirte. Cuándo contactar con soporte Contáctanos si experimentas: Problemas de autenticación a pesar de seguir las guías Respuestas de error inesperadas Problemas de rendimiento o respuestas lentas Preguntas sobre facturación o uso Necesitas límites de tasa más altos Aclaración sobre términos de licencia Ayuda con escenarios de integración específicos Cómo contactarnos Página de soporte: Visita cathopic.com/support y completa el formulario de contacto. Email (si se proporciona): Envía detalles directamente al email de soporte para desarrolladores listado en tu panel de API. Información a incluir Ayúdanos a ayudarte más rápido proporcionando: 1. Descripción clara del problema Qué estás intentando hacer Qué está pasando vs. qué esperas Cuándo comenzó el problema 2. Detalles técnicos Lenguaje de programación y framework Biblioteca HTTP o SDK que usas Últimos 4 dígitos de tu clave API Mensajes de error (texto completo) Códigos de estado HTTP 3. Ejemplo de código (sanitizado) // ¡Elimina tu clave API completa! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Solo últimos 4 dígitos 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Detalles de petición/respuesta Headers de petición Body de petición Estado de respuesta Body de respuesta Marca de tiempo del problema Antes de contactar con soporte Prueba esto primero para ahorrar tiempo: Consulta la documentación de la API Revisa preguntas en esta sección de ayuda Prueba con curl para aislar el problema Verifica que tu clave API esté activa en Ajustes → API Comprueba que tu método de pago sea válido Tiempo de respuesta Nuestro objetivo es responder a consultas de soporte para desarrolladores en 24-48 horas en días hábiles. Problemas complejos pueden requerir tiempo adicional de investigación. Para problemas urgentes Si experimentas una interrupción crítica de producción: Marca tu solicitud de soporte como "Urgente" Proporciona el email de tu cuenta para identificación prioritaria Incluye detalles de impacto (número de usuarios afectados, impacto en ingresos, etc.) Estado de la API Antes de reportar una interrupción, verifica si hay un problema conocido: Prueba conectividad básica: curl https://api.cathopic.com/resources Consulta nuestra página de estado (si está disponible) Busca anuncios en el panel de tu cuenta Recursos adicionales Documentación completa de la API: api.cathopic.com/docs Panel de cuenta: cathopic.com/settings/api Soporte general: cathopic.com/support Información de licencia: cathopic.com/legal/license ¡Estamos aquí para ayudar a que tu integración sea exitosa!

Developer / API

Primeros pasos

API keys, facturación y seguridad

Catálogo, búsqueda y licencias

Aplicaciones OAuth

Aplicaciones conectadas

Resolución de problemas