Saltar al contenido principal

Obtención de claves de API

Instrucciones paso a paso para obtener credenciales reales de cada proveedor externo con el que se integra Closegram. Consulta Configuración del entorno para saber en qué variable de .env va cada valor.

Los proveedores están ordenados aproximadamente según la probabilidad de que los necesites para el desarrollo local.

Base de datos y Redis​

No se necesita cuenta — consulta Infraestructura local mediante Docker. Configura un proveedor administrado de Postgres/Redis (por ejemplo, Railway, RDS, ElastiCache) solo al desplegar.

LiveKit​

Desarrollo local: no se necesita cuenta — el stack de Docker Compose ejecuta un servidor LiveKit real con una clave de desarrollo fija (devkey / dev1234567890abcdef1234567890abcdef). Apunta LIVEKIT_URL a ws://localhost:7880 y usa esas credenciales.

Producción: puedes autoalojarlo (despliega la misma imagen livekit/livekit-server en algún lugar accesible y genera tu propio par de claves con livekit-server generate-keys) o usar LiveKit Cloud:

  1. Regístrate en cloud.livekit.io y crea un proyecto.
  2. Ve a Settings → Keys y crea un nuevo par de API key/secret.
  3. Copia la WebSocket URL, la API Key y el API Secret en LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET.

Firebase​

Se usa para: verificación de tokens de Google Sign-In (backend), notificaciones push (backend + iOS + web) y Firebase Auth en los clientes frontend/iOS.

  1. Ve a la consola de Firebase y crea un proyecto (o usa uno existente).
  2. Cuenta de servicio del backend (completa las variables FIREBASE_* del backend): Project settings (icono de engranaje) → Service accounts → Generate new private key. Esto descarga un archivo JSON — mapea sus campos directamente a FIREBASE_PROJECT_ID, FIREBASE_PRIVATE_KEY_ID, FIREBASE_PRIVATE_KEY, FIREBASE_CLIENT_EMAIL, FIREBASE_CLIENT_ID, FIREBASE_AUTH_URI, FIREBASE_TOKEN_URI, FIREBASE_AUTH_PROVIDER_CERT_URL, FIREBASE_CLIENT_CERT_URL. Al pegar FIREBASE_PRIVATE_KEY en un archivo .env, mantenlo en una sola línea con secuencias literales \n (siguiendo el formato que ya existe en .env.example).
  3. Configuración de la app web (completa las variables NEXT_PUBLIC_FIREBASE_* del frontend): Project settings → General → desplázate hasta Your apps → agrega una app Web (icono </>) si no existe → copia apiKey, authDomain, projectId, storageBucket, messagingSenderId, appId del objeto firebaseConfig.
  4. Configuración de la app iOS (completa GoogleService-Info.plist): Project settings → General → Your apps → agrega una app iOS con el bundle ID de app.xcodeproj → descarga GoogleService-Info.plist y reemplaza apps/ios/app/app/GoogleService-Info.plist.
  5. Habilita los métodos de inicio de sesión que necesites en Authentication → Sign-in method (Google, y Phone si quieres autenticación telefónica basada en Firebase además de la vía Twilio/SMS).
  6. Si usas notificaciones push, habilita también Cloud Messaging en Project settings — no se necesita ninguna clave adicional más allá de la cuenta de servicio anterior.

Google Sign-In (cliente OAuth)​

Independiente del proyecto de Firebase anterior — este es un cliente OAuth de Google Cloud puro, usado por dos rutas de código distintas en el backend (GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET para una estrategia, CLIENT_ID/CLIENT_ID_SECRET/REDIRECT_URIs para otra).

  1. Ve a Google Cloud Console → selecciona el mismo proyecto que tu proyecto de Firebase (los proyectos de Firebase son proyectos de GCP por debajo) o crea uno nuevo.
  2. APIs & Services → OAuth consent screen — configúrala (External, agrega el nombre de tu app/correo de soporte) si aún no está hecho.
  3. APIs & Services → Credentials → Create Credentials → OAuth client ID.
  4. Tipo de aplicación Web application. Agrega tu(s) URI(s) de redirección (por ejemplo, http://localhost:8000/auth/google/callback para desarrollo local) — este valor también va en REDIRECT_URIs.
  5. Copia el Client ID y el Client Secret generados — usa el mismo par tanto para GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET como para CLIENT_ID/CLIENT_ID_SECRET, a menos que quieras que sean apps distintas específicamente.

Apple Sign-In​

Requiere una cuenta de Apple Developer paga ($99/año).

  1. Apple Developer → Certificates, Identifiers & Profiles → Identifiers → tu App ID (o crea uno) → habilita la capacidad Sign In with Apple.
  2. Identifiers → + → Services IDs → crea uno (por ejemplo, com.yourapp.signin) → habilita Sign In with Apple → configúralo con tu dominio y URL de redirección. Este valor de Services ID es tu APPLE_CLIENT_ID.
  3. Keys → + → marca Sign In with Apple, configúralo contra tu App ID → Continue → Register → Download. La descarga es un archivo .p8 que solo se puede obtener una vez — su contenido va en APPLE_PRIVATE_KEY (conserva el envoltorio -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY-----, con \n escapado como las demás claves multilínea). El Key ID mostrado en esa página es APPLE_KEY_ID.
  4. Tu Team ID se muestra en la esquina superior derecha de la página de la cuenta de Apple Developer (o en Membership) — eso es APPLE_TEAM_ID.
  5. APPLE_REDIRECT_URI es la URL de callback que configuraste en el Services ID en el paso 2 (solo se usa para el flujo OAuth web/backend — el Sign in with Apple nativo en iOS no lo necesita).

La propia app de iOS necesita la capacidad Sign In with Apple agregada en Xcode (Signing & Capabilities) — ya presente en apps/ios/app/app/app.entitlements.

Apple Push Notifications (APNs)​

Clave separada de Sign in with Apple — se usa para push de VoIP (alertas de llamadas entrantes) y push estándar de iOS.

  1. Apple Developer → Keys → + → marca Apple Push Notifications service (APNs) → Continue → Register → Download. De nuevo, este .p8 solo se puede descargar una vez.
  2. El contenido de la clave va en APNS_PRIVATE_KEY; el Key ID mostrado en la página es APNS_KEY_ID.
  3. APNS_TEAM_ID es el mismo Team ID mencionado antes.
  4. APNS_BUNDLE_ID es el identificador de bundle de tu app iOS (de app.xcodeproj).
  5. Deja APNS_PRODUCTION=false para un build Debug/TestFlight que use el entorno sandbox de APNs; ponlo en true para builds de App Store.

Stripe​

  1. Regístrate en dashboard.stripe.com.
  2. Developers → API keys — copia la Secret key (sk_test_... en modo de prueba) en STRIPE_API_KEY_PROD_SECRET, y la Publishable key (pk_test_...) en NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY del frontend y STRIPE_PUBLISHABLE_KEY de iOS.
  3. Developers → Webhooks → Add endpoint — apúntalo a <API_URL>/webhooks/stripe (o dondequiera que el backend lo exponga), selecciona los eventos que la app necesita (payment intents, eventos de suscripción), luego copia el Signing secret en STRIPE_WEBHOOK_SECRET. Para pruebas locales, el Stripe CLI (stripe listen --forward-to localhost:8000/webhooks/stripe) imprime un webhook secret que puedes usar en su lugar.
  4. Cambia a claves live (sk_live_... / pk_live_...) solo en producción, después de completar la activación de cuenta de Stripe.

AWS (S3, SES, SNS)​

  1. Crea una cuenta de AWS si no tienes una, e inicia sesión en la consola de IAM.
  2. Crea un usuario de IAM (o rol) con acceso programático. Adjunta políticas acotadas a lo que necesites: AmazonS3FullAccess (o una política personalizada acotada a un bucket), AmazonSESFullAccess, AmazonSNSFullAccess — redúcelas para producción.
  3. IAM → Users → tu usuario → Security credentials → Create access key — copia el Access key ID y el Secret access key en AWS_ACCESS_KEY/AWS_ACCESS_KEY_ID y AWS_SECRET_KEY/AWS_SECRET_ACCESS_KEY (ambas variantes de nombre son leídas por distintas partes del código — usa los mismos valores para ambas).
  4. Bucket de S3: consola de S3 → Create bucket, dale un nombre y anota la región. Completa AWS_BUCKET_NAME y AWS_REGION; AWS_S3_URL es https://<bucket>.s3.amazonaws.com.
  5. SES (correo): consola de SES → Verified identities → Create identity — verifica un dominio o una dirección de remitente individual. Mientras estés en el sandbox de SES solo puedes enviar a direcciones verificadas; solicita acceso de producción para enviar a cualquier dirección. Configura AWS_EMAIL con tu remitente verificado.
  6. SNS (SMS, solo si usas SMS_PROVIDER=aws-sns): no requiere un registro aparte — las mismas credenciales de IAM funcionan; SNS se cobra por uso, por SMS.
  7. Para desarrollo local sin nada de esto, configura DISABLE_S3=true y DISABLE_EMAIL=true.

Twilio (SMS / OTP telefónico)​

SMS_PROVIDER por defecto.

  1. Regístrate en twilio.com.
  2. El panel de la consola muestra directamente tu Account SID y Auth Token → TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN.
  3. Phone Numbers → Buy a number (las cuentas de prueba obtienen uno gratis) → cópialo en TWILIO_PHONE_NUMBER.
  4. Verify → Services → Create new Service — esto habilita específicamente los códigos OTP. Copia el Service SID en TWILIO_VERIFY_SERVICE_SID.
  5. Para desarrollo local sin SMS, configura DISABLE_SMS=true.

MessageBird (proveedor de SMS alternativo)​

Solo se necesita si configuras SMS_PROVIDER=messagebird.

  1. Regístrate en messagebird.com.
  2. Developers → API access → copia tu Live API key (o Test key para el sandbox) en MESSAGEBIRD_API_KEY.
  3. MESSAGEBIRD_ORIGINATOR es el nombre/número de remitente que se muestra a los destinatarios.

PayPal​

  1. Regístrate para una cuenta de PayPal Developer.
  2. Apps & Credentials → Create App (en Sandbox para pruebas, Live para producción).
  3. Copia el Client ID y el Secret en PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET.
  4. PAYPAL_API_BASE por defecto es la URL de sandbox (https://api-m.sandbox.paypal.com) — cambia a https://api-m.paypal.com para producción.

Compras dentro de la app (Apple & Google IAP)​

Para vender monedas dentro de las apps nativas. Ver Monedas → Compras dentro de la app para cómo funciona, y las variables de entorno.

Apple (App Store Server API)​

  1. Primero crea los productos: App Store Connect → tu app → Monetization → In-App Purchases → Create un Consumable por cada paquete de monedas. Configura ahí sus tiers de precio localizados (Apple localiza automáticamente) y copia cada Product ID al paquete correspondiente en la pantalla admin /coins (appleProductId).
  2. Crea una API key: App Store Connect → Users and Access → Integrations (Keys) → App Store Connect API → genera una key con el rol In-App Purchase (o Admin). Descarga el .p8 (solo una vez).
  3. Mapea al env: la página muestra el Issuer ID → APPLE_IAP_ISSUER_ID; el Key ID de la key → APPLE_IAP_KEY_ID; el contenido del .p8 → APPLE_IAP_PRIVATE_KEY; tu bundle id → APPLE_IAP_BUNDLE_ID.
  4. Notificaciones (reembolsos): App Store Connect → tu app → General → App Store Server Notifications → Version 2, pon la URL de Producción/Sandbox a https://<tu-api>/api/webhooks/apple/iap. Para fijar la firma, descarga Apple Root CA — G3 de Apple PKI y pon su PEM en APPLE_IAP_ROOT_CERT (requerido — el webhook de reembolso de Apple falla en cerrado y rechaza notificaciones sin un root anclado).

Google (Play Developer API + RTDN)​

  1. Primero crea los productos: Play Console → tu app → Monetize → Products → In-app products → Create un producto gestionado por paquete de monedas. Copia cada Product ID al paquete en admin (googleProductId). GOOGLE_IAP_PACKAGE_NAME es el applicationId de tu app.
  2. Service account: en Google Cloud Console crea una service account + JSON key; luego en Play Console → Users and permissions → invita esa service account y otórgale View financial data / Manage orders and subscriptions. Pon el JSON (como string) en GOOGLE_IAP_SERVICE_ACCOUNT_KEY.
  3. Reembolsos (Voided Purchases + RTDN): habilita Play Console → Monetization setup → Real-time developer notifications, apunta el topic a un topic de Google Cloud Pub/Sub, y agrega una push subscription a ese topic que entregue a https://<tu-api>/api/webhooks/google/rtdn. Para verificar el push, configura GOOGLE_RTDN_AUDIENCE (la URL de tu webhook) y GOOGLE_RTDN_SA_EMAIL (la service account del push) — opcional pero recomendado.

Google Cloud Vision (moderación de imágenes)​

Se usa para la detección de contenido NSFW/etiquetas de contenido (IMAGE_ANALYSIS_PROVIDER=google-vision). Usa el mismo tipo de credenciales de cuenta de servicio que BigQuery más abajo — puedes reutilizar una misma cuenta de servicio para ambas si tiene ambas APIs habilitadas.

  1. En Google Cloud Console, habilita la Cloud Vision API para tu proyecto (APIs & Services → Library → Cloud Vision API → Enable).
  2. IAM & Admin → Service Accounts → Create Service Account, otórgale un rol como Cloud Vision AI Service Agent (o uno más amplio si la reutilizas para BigQuery).
  3. Keys → Add key → Create new key → JSON — descárgala. El servicio de análisis de imágenes del backend obtiene las credenciales de la forma estándar de Google Cloud; revisa services/image-analysis/image-analysis.service.js para saber exactamente en qué variable(s) de entorno espera la ruta/JSON de credenciales antes de conectar esto, ya que no es una de las variables nombradas explícitamente en .env.example.

BigQuery (analítica, opcional)​

Solo se necesita si configuras ANALYTICS_DB_TYPE=bigquery — el valor por defecto (postgres) no requiere ninguna cuenta externa.

  1. En Google Cloud Console, habilita la BigQuery API.
  2. IAM & Admin → Service Accounts → Create Service Account, otórgale BigQuery Data Editor y BigQuery Job User.
  3. Keys → Add key → Create new key → JSON — mapea los campos del archivo descargado a BIGQUERY_PRIVATE_KEY_ID, BIGQUERY_PRIVATE_KEY, BIGQUERY_CLIENT_EMAIL, BIGQUERY_CLIENT_ID.
  4. Consola de BigQuery → Create dataset — anota el ID del dataset y la ubicación para BIGQUERY_DATASET_ID / BIGQUERY_LOCATION.
  5. GOOGLE_CLOUD_PROJECT_ID / GCP_PROJECT_ID es el ID de tu proyecto de GCP, visible en el panel de Cloud Console.

Giphy (selector de GIF de iOS)​

  1. Regístrate en developers.giphy.com.
  2. Create an App → elige el tipo de clave API (no SDK).
  3. Copia la clave en GIPHY_API_KEY de iOS (variable de entorno del scheme de Xcode — consulta Configuración del entorno).

Observabilidad (todo opcional)​

Esto solo importa cuando te preocupas por el monitoreo en producción — puedes omitirlo por completo para el desarrollo local.

  • Sentry — crea un proyecto, copia el DSN de Project Settings → Client Keys en SENTRY_DSN.
  • Datadog — Organization Settings → API Keys → crea/copia uno en DATADOG_API_KEY.
  • New Relic — Account settings → API keys → copia una clave Ingest - License en NEW_RELIC_LICENSE_KEY.
  • LogRocket — Project Settings → copia el App ID (formato org/project) en LOGROCKET_APP_ID.
  • Logger personalizado (CUSTOM_LOGGER_URL / CUSTOM_LOGGER_API_KEY) — solo es relevante si apuntas los logs a tu propio endpoint de ingesta; no está ligado a ningún producto de terceros en particular.