Question 1

O que é a API da Cathopic?

Accepted Answer

A nossa API é um serviço RESTful que permite integrar diretamente a biblioteca de mídia católica da Cathopic nas suas aplicações. Acesse milhares de imagens, vídeos e gráficos de forma programática. O que você pode fazer Pesquisar e navegar pelo nosso catálogo completo Licenciar recursos automaticamente para os seus utilizadores finais Baixar em vários formatos otimizados para diferentes casos de uso Acessar metadados ricos incluindo tags, descrições e informações litúrgicas Arquitetura REST Construída com base em princípios REST padrão: URL base: https://api.cathopic.com Formato de dados: solicitações e respostas em JSON Autenticação: chave de API via cabeçalho x-api-key Método HTTP: POST para todos os endpoints Quatro endpoints principais POST /resources - Pesquisar no catálogo POST /resource - Obter detalhes sobre um item específico POST /confirm - Licenciar um recurso e obter URLs de download POST /remove - Parar a licenciamento quando não for mais necessário (apenas site) Documentação completa Tudo o que você precisa está disponível online: Referência interativa da API: api.cathopic.com/docs Exemplos de código em várias linguagens Especificações detalhadas de parâmetros Começando Fale com a nossa equipe para solicitar acesso à API Gere a sua chave de API em Settings → API Adicione um método de pagamento para faturamento de uso Comece a construir Veja as outras perguntas desta seção para obter detalhes sobre autenticação, faturamento e melhores práticas. Contrato de Licença da API Todo o uso da API está sujeito ao nosso Contrato de Licença da API. Pontos-chave para entender: Uso apenas digital: o conteúdo só pode ser exibido em ambientes web e de e-mail Sem downloads de arquivos: os utilizadores finais não podem baixar ou exportar os arquivos originais Usos proibidos: treinamento de IA/ML, materiais impressos e uso offline são estritamente proibidos Faturamento por uso: pague apenas pelo uso real do conteúdo pelos seus utilizadores finais Ao usar a API, você aceita todos os termos do contrato de licença Antes de integrar a API: Revise o Contrato de Licença da API completo Entenda as restrições e obrigações Garanta que o seu caso de uso esteja em conformidade com os requisitos de uso apenas digital Planeje a sua integração para rastrear o uso com precisão para faturamento Para mais detalhes, veja: O que posso construir com a API? (inclui restrições detalhadas) Como as licenças funcionam via API? (detalhes completos de licenciamento) Como o uso da API é faturado? (explicação do modelo de faturamento)

Question 2

O que posso criar com a API?

Accepted Answer

A API da Cathopic permite integrar conteúdo visual católico diretamente na sua aplicação, site ou plataforma. No entanto, o uso da API é estritamente regido pelo nosso Contrato de Licença da API, que limita o uso a ambientes digitais específicos. O que você pode criar Sistemas de gestão de Igreja e paróquia Permitir que as paróquias adicionem imagens católicas aos seus boletins e newsletters Viabilizar a divulgação de eventos com conteúdo visual relevante Fornecer imagens litúrgicas que correspondam ao calendário da Igreja Criar displays digitais para avisos paroquiais Plataformas de conteúdo católico Construir plataformas de blog para escritores católicos com imagens integradas Criar sites de notícias católicas com visuais relevantes Desenvolver aplicativos devocionais com imagens e orações diárias Projetar plataformas de catequese com recursos visuais de ensino Ferramentas de marketing por e-mail Permitir que ministérios criem newsletters com imagens católicas Possibilitar que organizações religiosas criem campanhas de e-mail Fornecer modelos com conteúdo da Cathopic integrado Apoiar campanhas de arrecadação com visuais apropriados Construtores de sites e CMS Integrar imagens católicas em plataformas de criação de sites Fornecer módulos de conteúdo para organizações católicas Ativar a seleção de imagens por arrastar e soltar a partir da Cathopic Criar modelos especificamente para ministérios católicos Gestão de eventos e redes sociais Ajudar ministérios a criar artes para redes sociais (sem baixar arquivos) Desenhar sistemas de convites para eventos com imagens católicas Construir calendários de conteúdo com visuais do tempo litúrgico Permitir que organizações programem publicações com imagens apropriadas Restrições críticas que você deve seguir A Licença da API proíbe estritamente certos usos. A violação dessas restrições pode resultar em encerramento imediato: ❌ Treinamento de IA/ML (PROIBIDO PERMANENTEMENTE) Não pode ser usada para treinar, fazer fine-tuning ou alimentar quaisquer modelos de IA/ML Não pode criar embeddings, conjuntos de dados ou extrações derivadas para IA Essa restrição permanece indefinidamente, mesmo após o término do acordo Aplica-se a todas as formas de aprendizado de máquina e inteligência artificial ❌ Downloads e exportações de arquivos Os usuários finais não podem baixar ou salvar conteúdo como arquivos Não pode fornecer funcionalidade de "download" ou "exportação" O conteúdo deve permanecer hospedado pela Cathopic ou em cache autorizado Somente URLs otimizadas para a web podem ser usadas, não arquivos originais ❌ Uso para impressão e offline Não pode ser usada em materiais impressos, panfletos ou pôsteres Sem publicidade offline ou produtos físicos Limitado estritamente a ambientes digitais de web e e-mail Não pode ser incorporada em PDFs destinados à impressão ❌ Revenda e redistribuição Não pode criar produtos que revendam ou redistribuam conteúdo da Cathopic Não pode criar marketplaces de fotos de banco usando nossa API Não pode oferecer conteúdo como produto independente Deve ser integrado como parte de um serviço maior ❌ Modificação e obras derivadas Não pode alterar, transformar ou criar obras derivadas Não pode aplicar filtros ou modificações significativas Deve exibir o conteúdo conforme fornecido pela API Corte e redimensionamento básicos são permitidos para fins de layout Apenas ambientes de web e e-mail O conteúdo acessado por meio da API pode apenas ser usado em: Sites: páginas web públicas ou privadas Aplicações web: ferramentas e plataformas baseadas no navegador E-mail: newsletters, campanhas e e-mails transacionais Blogs: sistemas de gerenciamento de conteúdo online Embeds web: conteúdo controlado em iframe ou servido pela API Importante: O conteúdo deve ser exibido apenas em resolução otimizada para a web. Arquivos originais em alta resolução nunca ficam acessíveis por meio da API. Requisitos técnicos Seu aplicativo deve: Usar HTTPS: todas as chamadas de API e a entrega de conteúdo devem ser seguras Implementar o tratamento de marca d’água: comece com conteúdo com marca d’água e solicite sem marca d’água apenas quando necessário Rastrear o uso com precisão: registre todo o uso do conteúdo para fins de cobrança Chamar o endpoint /confirm: quando o usuário final confirmar o uso do conteúdo Chamar o endpoint /remove: quando o conteúdo não estiver mais em uso (para de ser cobrado) Evitar acesso não autorizado: proteja suas credenciais de API Respeitar os limites de taxa: siga os limites definidos para sua conta Suas obrigações legais Ao integrar a API, você deve: Atualizar seus Termos de Uso para informar os usuários finais: O conteúdo não pode ser baixado nem usado fora da sua aplicação O conteúdo não pode ser usado para fins de IA/ML O conteúdo é de propriedade da Cathopic e de seus criadores O uso é rastreado para cobrança e conformidade Implementar controles técnicos para impedir: Downloads com botão direito (quando viável) Acesso direto por URL a arquivos originais Extensões do navegador que habilitem downloads Manter registros de uso para: Verificação de cobrança Auditorias de conformidade Resolução de disputas Exemplos de integrações em conformidade ✅ Construtor de boletins paroquiais As paróquias criam boletins digitais com imagens católicas O conteúdo é exibido no site e em newsletters por e-mail Sem funcionalidade de download A cobrança rastreia o uso por paróquia e por imagem ✅ Plataforma de e-mail de ministério Organizações religiosas criam campanhas de e-mail Imagens servidas diretamente nos e-mails por URLs da API Cobrado por e-mail enviado com conteúdo Sem armazenamento de arquivos nos dispositivos dos usuários finais ✅ Plataforma de CMS católico Construtor de site com biblioteca Cathopic integrada Os usuários navegam e selecionam imagens para suas páginas Embeds de conteúdo via URLs servidas pela API Cobrado por dia de uso por usuário Exemplos de integrações proibidas ❌ Gerador de imagens com IA Usar conteúdo da Cathopic para treinar modelos de IA Criar conjuntos de dados para aprendizado de máquina Gerar imagens semelhantes com base no nosso conteúdo ❌ Ferramenta de design para impressão Permitir que os usuários criem pôsteres imprimíveis Fornecer download para impressão em alta resolução Criar PDFs com conteúdo da Cathopic para impressão ❌ Marketplace de fotos de banco Revender conteúdo da Cathopic como produtos independentes Criar coleções derivadas de fotos de banco Redistribuir conteúdo para múltiplos clientes Antes de começar a construir Leitura essencial: Revise o Contrato de Licença da API completo Estude a documentação técnica em api.cathopic.com/docs Entenda o modelo de cobrança em detalhes (veja Como o uso da API é cobrado?) Planeje sua integração para cumprir todas as restrições Entre em contato conosco via support se tiver dúvidas Lembre-se: Ao acessar ou usar a API, você aceita todos os termos do Contrato de Licença da API. A não conformidade pode resultar em encerramento imediato e consequências legais.

Question 3

Quais são os limites de taxa?

Accepted Answer

Atualmente, não aplicamos limites estritos de requisições por segundo. No entanto, espera-se um uso responsável para manter a qualidade do serviço para todos. Abordagem atual Em vez de limites rígidos, incentivamos o uso responsável: Espaçe suas requisições de forma razoável Implemente backoff exponencial quando ocorrerem erros Armazene em cache as respostas para evitar chamadas redundantes Entre em contato conosco se você antecipar volumes altos de tráfego Boas práticas Faça cache de forma agressiva: Armazene os resultados de busca para consultas comuns Mantenha os metadados de mídia localmente após a recuperação Não chame /confirm várias vezes para o mesmo usuário/recurso Faça o agrupamento das operações: Junte requisições relacionadas Adicione pequenos atrasos entre os lotes Limite conexões simultâneas (10-20 é razoável) Trate os erros com elegância: Implemente lógica de nova tentativa com backoff exponencial Não tente novamente imediatamente em caso de falha Registre erros para monitoramento Tempos de resposta esperados busca em /resources: tipicamente 200-500ms detalhes de /resource: abaixo de 100ms licenciamento em /confirm: 300-800ms Defina o timeout do seu cliente para pelo menos 30 segundos para lidar com respostas ocasionalmente mais lentas. Se você atingir os limites Você receberá um erro 429 Too Many Requests. Quando isso acontecer: // Implementar backoff 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; } } } Monitore seu uso Acompanhe a atividade da API em Configurações → API: Veja o total de requisições feitas Verifique licenças ativas Analise tendências de uso Monitore padrões incomuns Precisa de limites mais altos? Se o seu caso de uso legítimo exigir volumes altos de requisições (>1M requisições/mês), entre em contato com nossa equipe para discutir: Seu aplicativo e padrões de tráfego Volume esperado de requisições Limites de taxa garantidos, se necessário

Question 4

Como é cobrado o uso da API?

Accepted Answer

A API da Cathopic utiliza um modelo de cobrança “pay-as-you-go” (pague conforme o uso), baseado no uso real do conteúdo pelos seus utilizadores finais. Todos os termos de faturação são regidos pelo nosso Contrato de Licença da API. Dois modelos de cobrança A cobrança depende de como os seus utilizadores finais consomem o conteúdo: 1. Uso no website (modelo de Dias de Uso) Aplica-se quando o conteúdo é exibido em websites, blogs ou aplicações web É calculado por dia de calendário em que um utilizador final acede a um conteúdo específico Fórmula: Total de Dias de Uso × (taxa mensal negociada ÷ 30) A cobrança diária proporcional garante que você paga apenas pelo uso real É registado separadamente por utilizador final e por item de conteúdo 2. Uso por email (modelo por Email) Aplica-se quando o conteúdo é incorporado em mensagens de email É cobrado por mensagem de email enviada (não por destinatário) Cobrança única por email que inclui o conteúdo Taxa negociada durante a configuração do acesso à API Como a cobrança começa e termina Conteúdo com marca d’água é gratuito O conteúdo aparece inicialmente com uma marca d’água A pré-visualização com marca d’água não gera cobranças Ideal para permitir que os utilizadores finais naveguem antes de se comprometerem Pode ser usado para testes e fins de avaliação A cobrança começa quando a marca d’água é removida O utilizador final decide usar o conteúdo sem marca d’água A sua aplicação chama POST /confirm com: media_id: O identificador do conteúdo usage_type: “website” ou “email” client_identifier: O ID único do seu utilizador final A API devolve URLs permanentes para o conteúdo sem marca d’água A cobrança começa imediatamente a partir deste momento Você deve armazenar essas URLs e os dados de uso para o acompanhamento da faturação A cobrança termina quando o conteúdo é removido O utilizador final remove ou deixa de usar o conteúdo A sua aplicação chama POST /remove com: media_id: O identificador do conteúdo client_identifier: O ID do utilizador final A cobrança para esse uso específico é interrompida Você deve apagar as URLs do conteúdo sem marca d’água da sua base de dados Exemplo de cobrança no website Suponha que você tenha negociado uma taxa mensal de para uso ilimitado do conteúdo: Cenário: A Paróquia A exibe a Imagem n.º 12345 na sua página inicial Dia 1: Você chama /confirm → A cobrança começa Dias 1-15: A imagem permanece na página inicial (15 dias de uso) Dia 16: A Paróquia remove a imagem, você chama /remove → A cobrança termina Cálculo: 15 dias × ( ÷ 30 dias) = Cobrado: para este uso específico Se a Paróquia B também usar a mesma imagem por 10 dias, isso é registado separadamente e adiciona mais cobrança. Exemplo de cobrança por email Suponha que você tenha negociado uma taxa de --.05 por email: Cenário: Um Ministério envia uma newsletter com a Imagem n.º 67890 Ação: Você chama /confirm com usage_type: "email" Resultado: Cobrança única de --.05 por aquele email Destinatários: Não importa se foi enviado para 100 ou 10.000 pessoas Cobrado: --.05 total (não por destinatário) Limites mensais de cobrança O seu acordo pode incluir limites mensais de cobrança: Protege-o contra faturas inesperadamente altas Quando o limite é atingido, o uso adicional pode ser gratuito ou com taxa reduzida O valor específico do limite é negociado durante a configuração do acesso à API Aplica-se ao total das cobranças mensais em todos os utilizadores finais Faturação e pagamento Calendário de faturas Faturas emitidas mensalmente nos primeiros 10 dias de cada mês Cobre todo o uso do mês anterior Detalhamento do uso por utilizador final e por item de conteúdo Enviadas para o endereço de email associado à sua conta de API Processamento de pagamentos Pagamentos processados exclusivamente através da Stripe Cobrança automática para o seu método de pagamento registado É necessário manter, em todos os momentos, informações de pagamento válidas Recibos fornecidos automaticamente após um pagamento bem-sucedido Falhas de pagamento Se o pagamento falhar, o sistema faz 4 tentativas de reprocessamento Você recebe notificações por email sobre problemas de pagamento Se todas as tentativas falharem, o acesso à API é suspenso O acesso é restaurado imediatamente após um pagamento bem-sucedido Faturas não pagas podem acumular encargos de juros Suas responsabilidades de acompanhamento Você deve manter registos precisos de: Registos de uso: quando o conteúdo foi confirmado e removido IDs dos utilizadores finais: quais utilizadores acederam a qual conteúdo IDs do conteúdo: quais itens de mídia foram usados Tipos de uso: website vs email para cada uso Datas: datas de início e fim para o uso no website URLs: URLs sem marca d’água armazenadas para uso ativo Esses registos são essenciais para: Verificar as faturas mensais Resolver disputas de faturação Auditorias de conformidade pela Cathopic O seu próprio reporte interno Aceder a relatórios de uso Você pode acompanhar o uso da sua API em tempo real: Vá a Definições → API Veja a secção “Uso sob demanda” Consulte as estatísticas do período de faturação atual: Custo total acumulado até agora Número de usos no website Número de usos por email Clique em “Ver relatório detalhado” para ver a decomposição por: Utilizador final (client identifier) Item de conteúdo Tipo de uso Intervalo de datas Custos individuais Exporte os relatórios em CSV para os seus registos Negociar taxas O preço da API é personalizado para cada cliente: As taxas são negociadas durante o processo de solicitação de acesso à API Com base no volume de uso esperado Com base no seu caso de uso específico e no tipo de integração Pode incluir descontos por volume para aplicações com alto uso Os limites de cobrança podem ser negociados para proporcionar custos previsíveis Para discutir preços: Visite a nossa página de suporte Selecione “API access request” Descreva a sua integração e o uso esperado A nossa equipa fornecerá uma proposta personalizada Compreender a licença completa A cobrança é apenas um aspeto do contrato da API. Reveja os termos completos: Leia o Contrato de Licença da API na íntegra Entenda as restrições de uso (apenas digital, sem IA/ML, sem downloads) Conheça as suas obrigações de acompanhamento e reporte Reveja as cláusulas de propriedade intelectual e de rescisão Para detalhes técnicos sobre a implementação: Veja os endpoints /confirm e /remove em api.cathopic.com/docs Entenda como calcular o uso para a sua integração específica Reveja as melhores práticas para um acompanhamento de faturação preciso Lembre-se: o acompanhamento preciso do uso é da sua responsabilidade. Mantenha registos detalhados para garantir a cobrança correta e a conformidade com o contrato de licença.

Question 5

Como solicitar acesso de desenvolvedor para a API e o OAuth

Accepted Answer

A Cathopic analisa uma conta de desenvolvedor uma vez. Essa única aprovação desbloqueia tanto a API comercial quanto o gerenciamento das aplicações de OAuth; você não envia solicitações separadas. Após a aprovação, você cria e gerencia suas chaves de API e credenciais de OAuth nas Configurações da Cathopic. Os desenvolvedores nunca precisam de um comando do servidor da Cathopic nem de acesso à infraestrutura. 1. Prepare sua conta Cathopic Crie uma conta na Cathopic, verifique o endereço de e-mail e certifique-se de que o nome de usuário e o e-mail na solicitação correspondam exatamente a essa conta. 2. Envie a solicitação de desenvolvedor Abra o formulário de contato da Cathopic. Escolha Solicitar acesso de desenvolvedor. Confirme o nome de usuário da Cathopic e descreva o produto, a organização e o uso pretendido do catálogo. Envie o formulário. A solicitação aparece no painel interno de análise da Cathopic. 3. Receba a decisão A Cathopic analisa a conta e o caso de uso. Quando for aprovado, o desenvolvedor recebe um e-mail com os próximos passos e um link para Configurações → Desenvolvedor / API → aplicações OAuth. Se for necessária mais informação, a Cathopic entra em contato pelo e-mail da solicitação. 4. Crie a aplicação Escolha uma aplicação web confidencial quando o produto tiver um backend seguro, ou uma aplicação pública PKCE para clientes apenas de navegador, mobile ou desktop. Informe o nome público, a descrição, o site, a política de privacidade, o contato de segurança, as URLs exatas de callback e apenas os escopos de que ela precisa. 5. Armazene as credenciais O ID do cliente identifica a integração e é compartilhado por todos os usuários daquele produto. A autorização do usuário e os tokens permanecem separados para cada conta da Cathopic. Um segredo confidencial do cliente é exibido apenas uma vez e deve ser criptografado no servidor da aplicação. Nunca o inclua em código de navegador, sites gerados, logs, mensagens de suporte ou em um repositório público. A mesma página permite que o desenvolvedor aprovado edite callbacks e escopos, faça a rotação de um segredo confidencial ou revogue a aplicação.

Question 6

Como funcionam as chaves de API?

Accepted Answer

As chaves de API são suas credenciais de autenticação para acessar a API da Cathopic. Entender como elas funcionam é essencial para uma integração de API segura e eficaz. O que é uma chave de API? Uma chave de API é um token secreto exclusivo que identifica seu aplicativo e autoriza o acesso à API da Cathopic: Uma longa sequência alfanumérica (por exemplo, sk_live_abc123xyz789...) Atua como autenticação e autorização Vinculada à sua conta e ao faturamento da Cathopic Pode estar ativa ou inativa Ciclo de vida da chave Criação: Gere chaves em Configurações → API Dê a cada chave um nome descritivo ("Website de Produção", "Staging", "Aplicativo Mobile") Copie a chave completa imediatamente — ela é exibida apenas uma vez Armazene com segurança (variáveis de ambiente, gerenciador de segredos, gerenciador de senhas) Uso: Inclua no cabeçalho HTTP x-api-key em cada solicitação As chaves são validadas no servidor em cada solicitação Todo o uso da API é rastreado e faturado para sua conta Desativação: As chaves podem ser desativadas temporariamente sem exclusão Útil para solucionar problemas ou pausar uma integração específica Pode ser reativada a qualquer momento Exclusão: Remove a chave permanentemente Não pode ser desfeita nem recuperada Todas as solicitações com essa chave falharão imediatamente Diretrizes para gerenciamento de chaves Segurança: Nunca envie chaves para controle de versão: Use arquivos .env e adicione-os ao .gitignore Nunca exponha em código do lado do cliente: As chaves de API devem ser usadas apenas no servidor Use variáveis de ambiente: Armazene as chaves em process.env.CATHOPIC_API_KEY ou equivalente Gire regularmente: Troque as chaves periodicamente (trimestralmente ou após mudanças na equipe) Use chaves separadas por ambiente: Chaves diferentes para desenvolvimento, staging e produção Organização: Nomes descritivos: Nomeie as chaves por finalidade: "Website de Produção", "App iOS", "Sistema de E-mail" Documente a propriedade: Registre qual membro da equipe criou cada chave Auditorias regulares: Revise as chaves ativas mensalmente e remova as que não são usadas Múltiplas chaves de API Você pode criar várias chaves de API para finalidades diferentes: Por ambiente: Chaves separadas para desenvolvimento, staging e produção Por aplicativo: Chaves diferentes para website, aplicativo mobile, ferramentas internas Por membro da equipe: Chaves individuais para desenvolvedores (mais fácil de rastrear e revogar) Todas as chaves sob sua conta compartilham o mesmo faturamento. O uso de todas as chaves é combinado na sua fatura mensal. Monitorar o uso da chave Rastreie a atividade de cada chave: Vá para Configurações → API Veja a lista de todas as chaves com as datas da última utilização Clique em uma chave para ver estatísticas detalhadas de uso Monitore por atividades inesperadas O que fazer se uma chave for comprometida Se você acredita que uma chave de API foi exposta: Exclua ou desative imediatamente a chave em Configurações → API Gere uma nova chave de substituição Atualize seu aplicativo com a nova chave Revise os logs de uso para qualquer atividade suspeita Entre em contato com o suporte se você vir uso não autorizado Exemplo: armazenar chaves com segurança Node.js com variáveis de ambiente: // arquivo .env (adicione ao .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Seu 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: 'Jesus' }) }); Python com variáveis de ambiente: import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'} )

Question 7

Como autenticar as requisições?

Accepted Answer

Todas as requisições para a API Cathopic devem ser autenticadas usando sua chave de API. Veja como autenticar corretamente suas chamadas de API. Método de autenticação A API Cathopic usa autenticação por chave de API via cabeçalhos HTTP: Nome do cabeçalho: x-api-key Valor do cabeçalho: Sua chave de API completa Obrigatório para: Todos os endpoints da API Diferencia maiúsculas de minúsculas: Os nomes e valores dos cabeçalhos devem corresponder exatamente Exemplo de autenticação básica 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); ?> Erros de autenticação Se a autenticação falhar, você receberá uma resposta de erro: Chave de API ausente: HTTP 401 Unauthorized { "message": "Unauthorized" } Chave de API inválida: HTTP 401 Unauthorized { "message": "Unauthorized" } Chave de API inativa: HTTP 401 Unauthorized { "error": "Unauthorized token" } Lembretes importantes Segurança: Nunca codifique chaves de API no código: Use variáveis de ambiente ou configuração segura Apenas no lado do servidor: Nunca inclua chaves de API em JavaScript do lado do cliente Use apenas HTTPS: Chaves de API transmitidas via HTTP são vulneráveis Gire regularmente: Altere as chaves periodicamente para segurança Tratamento de erros: Verifique os códigos de status: Sempre confirme o status da resposta HTTP Registre falhas de autenticação: Acompanhe tentativas malsucedidas para monitoramento de segurança Implemente lógica de nova tentativa: Com backoff exponencial para erros transitórios Valide antes de enviar: Garanta que a chave de API foi carregada corretamente Testando a autenticação Teste rápido para verificar se sua chave de API funciona: 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}' Resposta esperada (sucesso): { "total": 1234, "page": 1, "page_size": 1, "results": [ ... ] } Erros comuns Nome do cabeçalho incorreto: Deve ser x-api-key, não api-key ou Authorization Formato de valor incorreto: Use a chave completa como está, sem prefixo "Bearer" Espaço em branco no final: Remova espaços em branco dos valores da chave de API antes de usar Chave não carregada: Verifique se a variável de ambiente está definida corretamente Para solucionar problemas de autenticação, veja "Common authentication errors" nesta seção.

Question 8

Como faço para rotacionar uma chave de API?

Accepted Answer

Rotacionar chaves de API regularmente é uma prática importante de segurança. Veja como rotacionar suas chaves com segurança sem interromper seu serviço. Por que rotacionar chaves de API? Boa prática de segurança: Limita a exposição caso uma chave seja comprometida Mudanças na equipe: Quando desenvolvedores saem ou mudam de função Suspeita de comprometimento: Se você acredita que uma chave pode ter sido exposta Conformidade: Algumas políticas de segurança exigem rotação periódica de chaves Mudanças de ambiente: Ao migrar infraestrutura ou refatorar Processo padrão de rotação (zero downtime) Etapa 1: Crie uma nova chave Faça login em Configurações → API Clique em "Criar nova chave de API" Nomeie de forma descritiva (por exemplo, "Web de Produção v2") Copie a nova chave imediatamente — ela é exibida apenas uma vez Armazene com segurança Etapa 2: Atualize sua aplicação Implante a nova chave na sua aplicação (variáveis de ambiente, gerenciador de segredos, etc.) Reinicie sua aplicação para carregar a nova chave Verifique se a nova chave está funcionando corretamente Monitore para identificar quaisquer erros Etapa 3: Monitore a transição Mantenha as duas chaves ativas temporariamente Verifique em Configurações → API as datas de "Último uso" Aguarde até que a chave antiga não mostre atividade recente Garanta que todas as instâncias/serviços tenham mudado para a nova chave Etapa 4: Exclua a chave antiga Depois de confirmar que a chave antiga não está mais em uso Exclua ou desative a chave antiga em Configurações → API Registre a rotação para seus registros Processo rápido de rotação (se comprometida) Se uma chave estiver definitivamente comprometida e você precisar agir imediatamente: Exclua primeiro a chave comprometida em Configurações → API Crie uma nova chave de substituição Implante rapidamente a nova chave em todas as aplicações Aceite uma breve indisponibilidade para evitar acesso não autorizado Monitore os logs de uso para qualquer atividade suspeita Entre em contato com o suporte se necessário Estratégia de rotação com múltiplos ambientes Para sistemas de produção, use uma abordagem em etapas: Semana 1: Desenvolvimento Crie e implante a nova chave no ambiente de desenvolvimento Teste minuciosamente Semana 2: Homologação Implante a nova chave na homologação Execute testes de integração Monitore para identificar problemas Semana 3: Produção Implante a nova chave na produção durante um período de baixo tráfego Monitore de perto Mantenha a chave antiga ativa por 24-48 horas como alternativa Semana 4: Limpeza Verifique se a chave antiga não mostra atividade Exclua a chave antiga Atualize a documentação Exemplo de automação Script para ajudar a verificar se a rotação da chave foi concluída: #!/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 Boas práticas Rotacione regularmente: A cada 90 dias para chaves de produção Documente as rotações: Mantenha um registro de quando as chaves foram rotacionadas e por quê Teste antes de excluir: Verifique sempre se a nova chave funciona antes de remover a antiga Use várias chaves: Separe chaves por ambiente para facilitar a rotação Automatize quando possível: Use ferramentas de gerenciamento de segredos que suportem rotação automática Checklist após a rotação Confirme estes itens após rotacionar: ✅ Todas as instâncias de produção usando a nova chave ✅ Todos os ambientes de homologação/desenvolvimento atualizados (se estiver usando a mesma chave) ✅ Variáveis de ambiente atualizadas ✅ Segredos do CI/CD atualizados ✅ Documentação atualizada ✅ Membros da equipe notificados ✅ Chave antiga excluída ✅ Rotação registrada para fins de auditoria

Question 9

Como protejo as minhas credenciais?

Accepted Answer

As suas chaves de API são a porta de entrada para a sua conta Cathopic. Mantê-las seguras evita acessos não autorizados e protege contra fraude de faturação. A regra de ouro: mantenha as chaves em segredo Trate as suas chaves de API como palavras-passe. Erros comuns a evitar: Codificar as chaves diretamente no código-fonte Fazer commit das chaves no Git ou noutro sistema de controlo de versões Usar chaves em JavaScript do lado do cliente ou em aplicações móveis Partilhar chaves por e-mail, Slack ou aplicações de mensagens Guardar chaves em locais públicos (repositórios públicos, wikis, etc.) Use variáveis de ambiente Guarde as chaves em variáveis de ambiente em vez de as colocar no código: // ficheiro .env (adicione ao .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // O seu código require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Isto separa os dados sensíveis da sua base de código e facilita a rotação das chaves. Apenas do lado do servidor As chamadas à API devem ser feitas a partir dos seus servidores de backend, não de navegadores nem de aplicações móveis. Se os utilizadores precisarem de acesso aos recursos da Cathopic: Crie um endpoint de backend que use a sua chave de API O seu frontend chama O SEU endpoint, não a Cathopic diretamente O seu servidor valida o pedido do utilizador antes de chamar a Cathopic Restringir por IP (se possível) Algumas infraestruturas permitem whitelisting de IPs. Se as suas chamadas à API vierem de IPs conhecidos: Configure regras de firewall para limitar o acesso de saída Use contas de serviço dedicadas com permissões mínimas Monitorize os registos de acesso para detetar atividade invulgar Se uma chave for comprometida Se suspeitar que uma chave foi exposta: Gere imediatamente uma nova chave de API Atualize a sua aplicação com a nova chave Elimine a chave comprometida Revise os registos de utilização em busca de atividade suspeita Contacte o suporte se vir cobranças não autorizadas Gira as suas chaves em segurança em Definições → API.

Question 10

Erros comuns de autenticação

Accepted Answer

Se você está com dificuldades para autenticar com a API do Cathopic, estes são os erros mais comuns e como corrigi-los. 401 Não autorizado O erro de autenticação mais comum: HTTP 401 Unauthorized { "message": "Unauthorized" } Causas comuns: Header x-api-key ausente Chave de API inválida ou expirada Erro de digitação na chave de API Espaços em branco antes/depois da chave Chave não carregada a partir da variável de ambiente Como corrigir: Verifique se o nome do header é exatamente x-api-key (minúsculo) Copie novamente sua chave de API em Settings → API Verifique se as variáveis de ambiente estão carregadas: console.log(process.env.CATHOPIC_API_KEY) Remova espaços em branco: apiKey.trim() Verifique se a chave está ativa (não foi excluída ou desativada) Nome de header incorreto A API exige x-api-key, e não outros nomes comuns de header: // ❌ INCORRETO Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRETO x-api-key: sk_live_abc... Erro de token não autorizado HTTP 401 Unauthorized { "error": "Unauthorized token" } Causa: Sua chave de API foi desativada ou excluída. Como corrigir: Verifique se a chave ainda está ativa em Settings → API Reative a chave, caso tenha sido desativada Gere uma nova chave se a antiga foi excluída Variável de ambiente não carregada Seu código não consegue encontrar a chave de API: // Retorna undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Como corrigir: Node.js: // Certifique-se de que o .env está carregado 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') Erro de exposição no lado do cliente Tentando usar a chave de API no JavaScript do navegador: // ❌ Isso falhará (chaves não funcionam em navegadores) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Como corrigir: Crie um endpoint no lado do servidor que faça proxy das requisições para a API do Cathopic. Veja "Como faço para proteger minhas credenciais?" para exemplos. Erros de CORS Se você vir erros de CORS no console do navegador: Access to fetch has been blocked by CORS policy... Causa: Você está tentando chamar a API diretamente a partir do JavaScript do lado do cliente. Como corrigir: A API do Cathopic é apenas do lado do servidor. Você precisa fazer proxy das requisições pelo seu próprio backend. Testando a autenticação Teste rápido para verificar sua configuração: 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}' # Procure uma resposta HTTP 200 # Se 401, verifique a chave com cuidado Checklist de depuração Se a autenticação ainda falhar: ☐ O nome do header é x-api-key (sensível a maiúsculas e minúsculas) ☐ A chave de API é a chave completa (começa com sk_live_ ou semelhante) ☐ Sem prefixo Bearer ou aspas ao redor da chave ☐ A variável de ambiente está definida e carregada ☐ A requisição é enviada a partir do servidor, não do navegador ☐ A chave está ativa em Settings → API ☐ O método de pagamento foi adicionado e é válido Se os problemas persistirem, entre em contato com suporte ao desenvolvedor com: A mensagem de erro Os últimos 4 dígitos da sua chave de API Linguagem de programação e framework Código de exemplo (sem expor sua chave completa)

Question 11

Parâmetros de pesquisa disponíveis

Accepted Answer

O endpoint /resources aceita vários parâmetros para refinar os resultados da sua pesquisa. Pesquisa básica POST https://api.cathopic.com/resources { "query": "São Francisco", "page": 1, "page_size": 20, "order": "popular" } Parâmetros query (string, opcional) Seu termo de pesquisa. Deixe em branco para obter todos os recursos. Exemplos: "Virgem Maria", "Eucaristia", "cruz" Suporta correspondência aproximada e tolerância a erros de digitação Pesquisa em títulos, descrições e tags page (inteiro, padrão: 1) Qual página de resultados retornar. Começa em 1. page_size (inteiro, padrão: 20, máximo: 100) Número de resultados por página. O máximo é 100 para manter o desempenho. order (string, padrão: "popular") Como ordenar os resultados: popular - Recursos mais baixados primeiro recent - Envios mais recentes primeiro Estrutura da resposta { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Título do recurso", "description": "Descrição do recurso", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Exemplos práticos Obtenha os 10 primeiros recursos mais populares sobre oração: { "query": "oração", "page": 1, "page_size": 10, "order": "popular" } Obtenha envios recentes, sem termo de pesquisa específico: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Navegue pela página 3 de imagens de santos: { "query": "santos", "page": 3, "page_size": 20, "order": "popular" } Para a referência completa da API, visite api.cathopic.com/docs.

Question 12

Como faço para baixar imagens via API?

Accepted Answer

Esclarecimento importante: A API não permite "baixar" no sentido tradicional. Em vez disso, ela fornece URLs permanentes para conteúdo otimizado para a web que sua aplicação entrega aos usuários finais. Isso é regido pelo nosso Contrato de Licença da API. Você NÃO baixa arquivos A API da Cathopic funciona de forma fundamentalmente diferente dos downloads tradicionais: Sem transferência de arquivos: você nunca recebe nem armazena os arquivos reais de imagem/vídeo Acesso baseado em URL: a API fornece URLs que apontam para conteúdo hospedado pela Cathopic Apenas otimizado para a web: o conteúdo é entregue em resolução adequada para exibição digital Sem arquivos originais: os originais em alta resolução nunca ficam acessíveis via API Sempre hospedado: o conteúdo permanece nos servidores da Cathopic ou em CDN autorizada Resoluções disponíveis A API fornece três tamanhos otimizados para a web: Pequeno: adequado para miniaturas e pequenos embeds (normalmente ~400px de largura) Médio: bom para conteúdo web padrão (normalmente ~800px de largura) Grande: melhor qualidade para exibição na web (normalmente ~1200px de largura) Restrições críticas: Arquivos originais em alta resolução NUNCA são fornecidos As resoluções são otimizadas para exibição em tela, não para impressão Os tamanhos dos arquivos são compactados para entrega rápida na web Você não pode solicitar resoluções personalizadas nem qualidade original Para os termos completos, leia o Contrato de Licença da API completo e consulte a documentação técnica em api.cathopic.com/docs. Baixar imagens envolve duas etapas: licenciar o recurso com /confirm e depois usar as URLs retornadas. Etapa 1: Licencie o recurso Chame /confirm para licenciar um recurso para um usuário final específico: POST https://api.cathopic.com/confirm x-api-key: YOUR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parâmetros: media_id - O ID do recurso nos seus resultados de busca usage_type - "website" ou "email" client_identifier - ID único do seu usuário final Etapa 2: Use as URLs de download A resposta contém URLs permanentes em vários 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: armazene as URLs As URLs retornadas são permanentes - armazene-as no seu banco de dados: // Depois de chamar /confirm const response = await api.confirm(mediaId, userId); // Armazene no seu banco de dados await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Na próxima vez, recupere do banco de dados em vez de chamar /confirm novamente Escolhendo o formato certo Formato AVIF: Tamanhos de arquivo menores (melhor desempenho) Melhor compressão Recomendado para navegadores modernos Não é compatível com navegadores mais antigos Formato JPEG: Compatibilidade universal Tamanhos de arquivo maiores Use como alternativa para navegadores mais antigos Lembrete crítico ⚠️ Verifique sempre seu banco de dados antes de chamar /confirm. Chamá-lo várias vezes para o mesmo usuário e recurso criará cobranças duplicadas. Documentação completa em api.cathopic.com/docs.

Question 13

Gerenciando paginação e ordenação

Accepted Answer

A API retorna resultados de pesquisa em páginas. Veja como navegar de forma eficiente por grandes conjuntos de resultados. Paginação básica POST /resources { "query": "saints", "page": 1, "page_size": 20 } Resposta: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 itens ... ] } A resposta informa que há 1.523 resultados no total e que você está visualizando a página 1 com 20 itens. Calculando o total de páginas const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 páginas Carregando a próxima página // Próxima página simples currentPage++; // Ou crie a interface de paginação for (let page = 1; page <= totalPages; page++) { // Crie o botão da página } Otimizando o tamanho da página Escolha o tamanho da página com base no seu caso de uso: Páginas pequenas (10-20 itens): Carregamento inicial mais rápido Bom para pesquisa voltada ao usuário Mais solicitações à API Páginas grandes (50-100 itens): Menos solicitações à API Bom para processamento em lote Solicitações individuais mais lentas O máximo é 100 itens Opções de ordenação Popular (padrão): { "order": "popular" } Retorna primeiro os recursos mais baixados. Melhor para exibir conteúdo de alta qualidade e comprovado. Recente: { "order": "recent" } Retorna primeiro os uploads mais novos. Bom para descobrir conteúdo recente. Exemplo de rolagem infinita 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(); // Adicione os resultados à sua interface appendResults(data.results); // Verifique se há mais páginas const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Acione ao rolar window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Dicas de desempenho Armazene em cache os resultados localmente para evitar solicitações redundantes Use tamanhos de página adequados ao seu caso de uso Implemente estados de carregamento para uma melhor experiência do usuário Considere virtualização para listas muito grandes Não busque todas as páginas de uma vez — carregue sob demanda Para mais detalhes, consulte a documentação completa em api.cathopic.com/docs.

Question 14

Como pesquisar no catálogo e usar URLs de pré-visualização do Cathopic

Accepted Answer

Use GET /api/v2/catalog com catalog.read. Ele usa a camada de busca fuzzy tolerante a erros de digitação já existente do Cathopic e carrega os mesmos modelos canônicos de mídia usados pela grade do site. Parâmetros q ou query: texto com até 250 caracteres. type: photo, video, graphic, artwork, ai, ou all. orientation: landscape, portrait, square, ou all. sort: most_recent, popular, ou popular_alltime. page, per_page : até 50, e locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUse URLs de pré-visualização sem alterações Cada resultado inclui preview.url e preview.transformation_url_template. Eles vêm do mesmo apresentador de grade, host do CDN, caminho de armazenamento e regras de marca d’água usados em cathopic.com. Use-os sem alterações para que integrações reutilizem as chaves de cache existentes do Cloudflare. Não envie outra cópia nem faça proxy desnecessariamente. Não adicione parâmetros de consulta para quebrar cache. Substitua <OPTIONS> apenas por opções de imagem estáveis do Cloudflare. As pré-visualizações nunca consomem um download. already_licensed inclui permissões individuais e da equipe compartilhada.

Question 15

Como licenciar e baixar um recurso com segurança

Accepted Answer

A criação da licença e a criação da URL original são separadas, para que as tentativas sejam seguras e URLs novas nunca sejam cobradas novamente. 1. Crie a licença POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Use uma chave única de 8 a 160 caracteres ASCII imprimíveis para a tentativa lógica de seleção e mantenha-a ao tentar novamente. Uma nova licença retorna 201; uma repetição idempotente retorna 200 com o mesmo ID da licença. A Cathopic primeiro verifica a original. Em uma única transação, ela bloqueia a assinatura individual ou da equipe, verifica o acesso à mídia e as concessões compartilhadas existentes, consome no máximo um download e registra a concessão, o histórico e a licença. 2. Solicite a URL original POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENA URL expira após cinco minutos. Solicite uma nova URL para um novo download; não crie outra licença. A Cathopic deriva o caminho de armazenamento e nunca aceita um caminho arbitrário. Erros importantes subscription_required: sem acesso pago ativo. media_type_not_in_plan: tipo não incluído. download_balance_exhausted: não restam downloads no plano limitado. file_unavailable: original ausente; sem cobrança. idempotency_key_conflict: a chave foi usada para outro ID de mídia. Mantenha o X-Request-Id para o suporte, mas nunca registre tokens, segredos ou URLs assinadas. Faça backoff com jitter após respostas 429 ou 5xx transitórias.

Question 16

Guia rápido OAuth 2.0 para apps conectadas Cathopic

Accepted Answer

As Apps Conectadas Cathopic usam OAuth 2.0 Authorization Code com PKCE S256 obrigatório. A mesma aprovação do desenvolvedor também desbloqueia a API comercial da Cathopic, mas as conexões OAuth usam tokens do usuário e o plano do usuário conectado, em vez de chaves de API e cobrança de API por uso. 1. Obter acesso e registrar a aplicação Envie a solicitação única de acesso do desenvolvedor por meio do formulário de contato. Depois que a Cathopic aprovar a conta por e-mail, abra Configurações → Desenvolvedor / API → aplicações OAuth, crie a aplicação, registre seus callbacks exatos e os escopos necessários e armazene seu segredo de uso único, se for confidencial. 2. Descobrir o servidor de autorização GET https://cathopic.com/.well-known/oauth-authorization-server3. Redirecionar o usuário 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=enConstrua uma única URL; as quebras de linha apenas tornam o exemplo legível. Gere novos valores de estado e PKCE com alta entropia para cada tentativa. ui_locales é opcional e pode solicitar um idioma compatível como en ou es. Se for necessário fazer login, a Cathopic retoma a mesma solicitação de autorização e então mostra a tela de permissões. 4. Validar o callback e trocar o código Compare o estado retornado antes de trocar o código. A URI de redirecionamento deve corresponder 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=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIERAplicações públicas omitem client_secret. Armazene tokens e segredos confidenciais apenas no servidor e criptografe-os em repouso. Tokens de acesso duram 30 minutos; tokens de atualização duram até 30 dias e são rotacionados quando usados. Verificações comuns Um callback rejeitado geralmente difere da URI registrada em esquema, host, porta, caminho, capitalização ou barra final. invalid_request antes do consentimento significa que PKCE S256, o challenge ou o state está ausente ou inválido. invalid_grant geralmente significa que um código ou um token de atualização rotacionado foi reutilizado, ou que o callback ou o verifier foi alterado. Após um 401, atualize uma vez; se a atualização falhar, peça ao usuário para reconectar. Um 403 significa que o token não tem o escopo necessário. Veja o contrato OpenAPI completo e o guia detalhado de integração de Apps Conectadas.

Question 17

Como conecto o Cathopic a outra aplicação?

Accepted Answer

Uma plataforma aprovada pode permitir que você use o catálogo do Cathopic sem receber sua senha. Ela envia o seu navegador para uma página segura em cathopic.com, onde você faz login e revisa as permissões exatas solicitadas. Conectar sua conta Na outra aplicação, escolha o conector do Cathopic e clique em Conectar ou Entrar com o Cathopic. Confirme que o navegador está em cathopic.com. Faça login no Cathopic, se necessário. O Cathopic retorna à mesma solicitação de permissão, em vez de abrir seu perfil. Leia todas as permissões. Elas podem incluir identidade da conta, acesso ao catálogo, saldo da assinatura ou a capacidade de licenciar recursos. Escolha Permitir acesso. O Cathopic só o envia de volta para o callback exato registrado para aquela aplicação. Idioma e segurança da conta A aplicação pode solicitar um idioma compatível para as telas de login e permissões. O Cathopic mantém esse idioma durante toda a conexão. A aplicação recebe tokens de curta duração, nunca sua senha, e só pode executar as ações listadas na tela de permissões. Se você não confia na solicitação Escolha Cancelar. Não aprove a conexão se a aplicação for desconhecida, se as permissões parecerem desnecessárias ou se o navegador não estiver mostrando o domínio do Cathopic. Você pode revogar o acesso mais tarde em Configurações → Desenvolvedor / API → Aplicativos conectados.

Question 18

Os aplicativos conectados usam meus downloads e como posso desconectá-los?

Accepted Answer

Pesquisar e exibir prévias com marca d’água nunca consome um download. Um download só pode ser consumido quando um aplicativo conectado pede ao Cathopic para licenciar um recurso pago. Quando um download é consumido O recurso é pago, o plano inclui o tipo dele e nem você nem a assinatura atual da equipe o licenciaram antes. O plano tem um saldo limitado. Planos ilimitados registram a licença sem reduzir um número. O arquivo original está disponível. O Cathopic verifica isso antes de alterar o saldo. Quando nenhum download adicional é consumido O recurso é gratuito. Você ou outro membro usando a mesma assinatura da equipe já o licenciaram. Você solicita um novo link de download para uma licença existente. A aplicação tenta novamente a mesma solicitação com a mesma chave de idempotência. Os membros da equipe consomem o saldo compartilhado do proprietário da equipe. O Cathopic é sempre a fonte da verdade. Desconectar um aplicativo Abrir Configurações → Desenvolvedor / API → Aplicativos conectados. Revise o aplicativo e suas permissões. Clique Desconectar e confirme. Todos os tokens de acesso e de atualização ativos para esse aplicativo são revogados imediatamente. As licenças existentes e o histórico de downloads permanecem.

Question 19

Códigos comuns de erro da API

Accepted Answer

Entender as respostas de erro ajuda você a depurar problemas rapidamente. Aqui estão os erros mais comuns que você encontrará. 400 Solicitação inválida { "error": "media_id is required" } Causas: Parâmetro obrigatório ausente Formato de parâmetro inválido JSON malformado Correção: Verifique se o corpo da sua solicitação corresponde à especificação da API em api.cathopic.com/docs. 401 Não autorizado { "message": "Unauthorized" } ou { "error": "Unauthorized token" } Causas: Chave de API ausente ou inválida Chave de API desativada Nome de cabeçalho incorreto Correção: Verifique se o seu cabeçalho x-api-key está correto e se a chave está ativa em Configurações → API. 404 Não encontrado { "error": "No file found for media_id 1234" } ou { "error": "Media item not found" } Causas: O recurso não existe O recurso foi excluído media_id incorreto Correção: Verifique se o media_id existe pesquisando primeiro com /resources. 429 Muitas solicitações { "error": "Limit exceed." } Causas: Muitas solicitações em pouco tempo Limite de taxa excedido Correção: Implemente backoff exponencial. Aguarde e tente novamente com atrasos crescentes (1s, 2s, 4s, etc.). 500 Erro interno do servidor { "error": "Internal server error" } Causas: Problema temporário no servidor Condição inesperada Correção: Aguarde um momento e tente novamente. Se persistir, entre em contato com suporte. Exemplo de tratamento de erro 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; } } Para erros persistentes, verifique a documentação completa da API ou entre em contato com o suporte.

Question 20

Erros de limite de taxa

Accepted Answer

Se você vir 429 Too Many Requests, você está acessando a API com muita frequência. Veja como lidar com isso corretamente. O erro HTTP 429 Too Many Requests { "error": "Limit exceed." } Por que isso acontece Os limites de taxa protegem a API contra uso excessivo: Muitas requisições em pouco tempo Consulta frequente (polling) agressiva ou scraping Sem intervalo entre as requisições Requisições simultâneas sem controle de taxa (throttling) Estratégia de backoff exponencial A melhor forma de lidar com limites de taxa é usar backoff exponencial — espere mais tempo após cada nova tentativa: 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'); } Prevenindo limites de taxa Adicione atrasos entre as requisições: // Ruim: requisições em sequência rápida for (const id of mediaIds) { await api.getResource(id); // Sem atraso } // Bom: requisições com controle de taxa for (const id of mediaIds) { await api.getResource(id); await sleep(500); // atraso de 500ms } Faça operações em lote: // Processar em lotes de 10 com atrasos 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 } } Armazene respostas em 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; } O que NÃO fazer ❌ Tentar novamente imediatamente sem atraso ❌ Fazer requisições paralelas sem limite ❌ Ignorar erros 429 ❌ Usar atrasos fixos e curtos (use sempre backoff exponencial) Se os problemas persistirem Entre em contato com o suporte ao desenvolvedor se você realmente precisar de limites de taxa mais altos para o seu caso de uso. Forneça detalhes sobre: Sua aplicação e seu caso de uso Volume esperado de requisições Implementação atual (com backoff)

Question 21

Tempo limite e problemas de rede

Accepted Answer

Problemas de rede podem fazer com que as requisições à API falhem. Veja como lidar com timeouts e problemas de conexão de forma adequada. Definindo timeouts apropriados Defina sempre timeouts para evitar requisições “travadas”: // JavaScript com 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('Requisição excedeu o tempo limite após 30s'); } else { console.error('Erro de rede:', error); } throw error; } // Python com 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 segundos ) return response.json() except Timeout: print('Requisição excedeu o tempo limite após 30s') raise except RequestException as e: print(f'Erro de rede: {e}') raise Erros comuns de rede Timeout de conexão: Não é possível estabelecer conexão com o servidor Geralmente é um problema de rede ou de firewall Verifique a conexão com a internet Confirme se o firewall permite HTTPS para api.cathopic.com Timeout de leitura: A conexão foi estabelecida, mas não há resposta O servidor pode estar lento ou sobrecarregado Aumente o timeout ou tente novamente mais tarde Falha na resolução de DNS: Não é possível resolver api.cathopic.com Problema no servidor DNS Tente novamente ou verifique as configurações de DNS Tentar novamente com 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(`Todas as ${maxRetries} tentativas falharam`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`A tentativa ${attempt + 1} falhou. Tentando novamente em ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Valores recomendados de timeout Timeout de conexão: 10 segundos Timeout de leitura: 30 segundos Busca em /resources: 30 segundos /confirm licensing: 30 segundos Depurando problemas de rede Use curl para testar a conectividade: # Testar conectividade básica curl -v https://api.cathopic.com/resources # Testar com timeout curl --max-time 30 -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Verifique: ✓ O DNS resolve api.cathopic.com ✓ A conexão SSL/TLS é bem-sucedida ✓ A resposta HTTP foi recebida ✓ O tempo de resposta é razoável (<5s normalmente) Se os problemas persistirem, entre em contato com suporte com detalhes de diagnóstico de rede.

Question 22

Depurar solicitações com falha

Accepted Answer

Quando as solicitações falham, uma depuração sistemática ajuda a identificar o problema rapidamente. Ative o registro detalhado 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; } } Verifique primeiro 1. A chave de API está correta: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. O nome do cabeçalho é exato: // Deve ser minúsculo 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Correto 'X-API-Key': apiKey, // ✗ Errado 'api-key': apiKey, // ✗ Errado } 3. O JSON é válido: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. A solicitação chega ao servidor: // Use a aba Network das DevTools do navegador ou curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Erros comuns Content-Type incorreto: // ✗ Errado headers: { 'Content-Type': 'text/plain' } // ✓ Correto headers: { 'Content-Type': 'application/json' } Não converter o corpo em string: // ✗ Errado body: { query: 'test' } // ✓ Correto body: JSON.stringify({ query: 'test' }) Usar GET em vez de POST: // ✗ Todos os endpoints exigem POST method: 'GET' // ✓ Correto method: 'POST' Teste com uma solicitação mínima Reduza ao mínimo para isolar o problema: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Objeto vazio }); console.log(response.status); console.log(await response.json()); Se isso funcionar, adicione gradualmente os parâmetros de volta até que falhe. Compare com um exemplo que funciona Teste com curl para verificar sua implementação: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Jesus", "page": 1, "page_size": 5}' Se o curl funcionar, mas seu código não, compare os cabeçalhos e o corpo exatos. Ainda com dificuldades? Entre em contato com o suporte ao desenvolvedor com: Mensagem de erro completa Cabeçalhos da solicitação (oculte sua chave de API completa) Corpo da solicitação Status e corpo da resposta Linguagem de programação e biblioteca HTTP Trecho de código (sem expor credenciais)

Question 23

Como entrar em contato com o suporte ao desenvolvedor

Accepted Answer

Precisa de ajuda com a sua integração de API? Nossa equipe de suporte ao desenvolvedor está aqui para ajudar. Quando entrar em contato com o suporte Entre em contato se você estiver enfrentando: Problemas de autenticação, mesmo seguindo os guias Respostas de erro inesperadas Problemas de desempenho ou respostas lentas Perguntas sobre cobrança ou uso Necessidade de limites de taxa mais altos Esclarecimentos sobre os termos de licenciamento Ajuda com cenários específicos de integração Como entrar em contato conosco Página de suporte: Visite cathopic.com/support e preencha o formulário de contato. E-mail (se fornecido): Envie os detalhes diretamente para o e-mail de suporte ao desenvolvedor listado no seu painel de API. Informações para incluir Ajude-nos a ajudá-lo mais rápido fornecendo: 1. Uma descrição clara do problema O que você está tentando fazer O que está acontecendo vs. o que você esperava Quando o problema começou 2. Detalhes técnicos Linguagem de programação e framework Biblioteca HTTP ou SDK que você está usando Últimos 4 dígitos da sua chave de API Mensagens de erro (texto completo) Códigos de status HTTP 3. Exemplo de código (sanitizado) // Remova sua chave de API completa! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Apenas os ú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. Detalhes da solicitação/resposta Headers da solicitação Corpo da solicitação Status da resposta Corpo da resposta Horário (timestamp) do problema Antes de entrar em contato com o suporte Tente primeiro estas opções para economizar tempo: Verifique a documentação da API Revise as perguntas nesta seção de ajuda Teste com curl para isolar o problema Verifique se a sua chave de API está ativa em Configurações → API Verifique se o seu método de pagamento é válido Tempo de resposta Nosso objetivo é responder às solicitações de suporte ao desenvolvedor em até 24-48 horas nos dias úteis. Problemas complexos podem exigir mais tempo de investigação. Para problemas urgentes Se você estiver enfrentando uma interrupção crítica em produção: Marque sua solicitação de suporte como "Urgente" Forneça o e-mail da sua conta para identificação prioritária Inclua detalhes do impacto (número de usuários afetados, impacto na receita, etc.) Status da API Antes de reportar uma interrupção, verifique se há um problema conhecido: Teste conectividade básica: curl https://api.cathopic.com/resources Verifique nossa página de status (se disponível) Procure anúncios no painel da sua conta Recursos adicionais Documentação completa da API: api.cathopic.com/docs Painel da conta: cathopic.com/settings/api Suporte geral: cathopic.com/support Informações de licenciamento: cathopic.com/legal/license Estamos aqui para ajudar você a ter uma integração bem-sucedida!

Developer / API

Primeiros passos

Chaves de API, faturamento e segurança

Catálogo, pesquisa e licenciamento

Aplicativos OAuth

Aplicativos conectados

Solução de problemas