Probablemente estés usando un pipeline de despliegue manual que se vuelve frágil en cuanto el equipo necesita lanzamientos repetibles. Un desarrollador crea un bundle, lo sube desde su laptop, revisa un dashboard, mueve un channel y espera los datos de adopción. Ese proceso puede funcionar en proyectos pequeños, pero genera riesgos evitables cuando varias apps, entornos y tareas de despliegue comparten la misma infraestructura.
Una buena lista pública de API debe responder algo más que “¿qué endpoints existen?”. Debe mostrar cómo encajan la autenticación, los identificadores de recursos, el estado de la release, las cuotas, los headers, los retries y los workflows por lotes. Esta guía aborda la Capgo API desde esa perspectiva operativa, con patrones aplicables a equipos de Capacitor que buscan automatizar su CI/CD en lugar de hacer peticiones de prueba aisladas.
Table of Contents
- Entendiendo la autenticación de API en Capgo
- Generación de tus credenciales de API
- Endpoints principales para gestionar apps
- Creación y gestión de releases
- Estrategia de canales y patrones de rollout
- Endpoints de monitoreo y diagnóstico
- Rate Limiting y headers de seguridad
- Solución de errores comunes de API
Entendiendo la autenticación de Capgo API
El error de integración más común es enviar una solicitud válida con el formato de credencial incorrecto. Una clave copiada de un dashboard no es automáticamente un bearer token, y un bearer token no sirve si la solicitud omite el Authorization header o lo envía bajo el esquema incorrecto. El servidor devolverá un fallo de autenticación antes de evaluar el endpoint, el payload o el identificador de la app.
Empieza identificando cómo la documentación de Capgo API llama a la credencial, y luego reproduce su ejemplo de solicitud exactamente. En una solicitud típica con bearer token, el header de autorización sigue este patrón:
Authorization: Bearer YOUR_TOKEN
Mantén la credencial en una variable de entorno mientras testeas localmente. En CI/CD, inyéctala mediante el secret store de la plataforma en lugar de subirla a un repositorio, incluirla en un mobile bundle o añadirla a un query string. Una app móvil no debe contener una credencial de gestión, ya que cualquier cosa enviada a un dispositivo puede ser inspeccionada.
Separa la identidad de la autorización
La autenticación determina quién hace la petición. La autorización determina qué puede cambiar esa identidad. Trátalas como procesos separados al diseñar un servicio de despliegue.
Una clave personal es útil para explorar, pero vincula la automatización de producción a la cuenta de una sola persona. Una clave gestionada por el equipo es mejor para un pipeline compartido, siempre que la organización pueda revocarla y reemplazarla sin interrumpir otros procesos. Usa credenciales distintas para los flujos de desarrollo, staging y producción cuando el dashboard y el modelo de permisos lo permitan.
Antes de llamar a un endpoint de release, prueba una operación de lectura de bajo riesgo. Confirma que:
- El host es correcto: Usa la URL base de API documentada para el entorno activo.
- El header esté completo: Incluye el esquema de autorización requerido y un
Acceptheader para respuestas JSON. - El body esté codificado correctamente: Envía
Content-Type: application/jsonsolo cuando la petición contenga JSON. - El scope sea suficiente: Una credencial con permiso de lectura de metadatos podría no tener autorización para crear o distribuir un release.
- La respuesta se registra de forma segura: Registra códigos de estado e identificadores de solicitud, pero anonimiza claves, tokens, contenido de bundles y datos sensibles del dispositivo.
Los catálogos públicos de API han pasado de ser simples directorios a ser herramientas de descubrimiento operativas. La cuenta histórica de ProgrammableWeb describe un directorio que superó las 19,000 APIs en enero de 2018, tras añadir 2,294 nuevas APIs en 2017 y un promedio de más de 2,000 adiciones por año desde enero de 2014. Esa historia explica por qué una lista pública de API moderna debe ayudar a los ingenieros a evaluar el comportamiento de la integración, no solo a encontrar una URL.
For related client-side access-control considerations, see patrones de autorización de la app CapgoLa misma disciplina aplica aquí: mantén las credenciales de gestión en servidores de confianza, define los permisos con intención y facilita el diagnóstico de errores de autorización.
Generación de tus credenciales API
La creación de credenciales debe tratarse como un cambio en la gestión de accesos, no como un paso de configuración trivial. Las etiquetas del dashboard pueden variar, así que usa la interfaz y documentación actual de Capgo como referencia, aunque el flujo de trabajo es constante.
Crea una clave con un propósito
Entra en la configuración de la organización o cuenta, busca la sección de API o developer-credentials y elige la acción para crear una clave. Dale un nombre que identifique su función, como un pipeline de staging o un worker de producción. Evita nombres basados solo en una persona, ya que la propiedad queda poco clara si el equipo cambia.
Selecciona los permisos más restrictivos para ese flujo. Una tarea que solo lee el estado del deployment no debería tener permiso para borrar apps o alterar canales. Si la interfaz ofrece alcance a nivel de organización y de app, elige el límite más pequeño que cumpla con la tarea.
Copia el secret cuando el dashboard lo muestre. Muchos sistemas de credenciales solo muestran el valor completo durante la creación. Guárdalo en tu gestor de secrets de CI/CD y luego prueba su recuperación en el pipeline sin imprimir el valor. Un local .env el archivo puede ayudar durante el desarrollo, pero debe excluirse del control de versiones y nunca incluirse en un directorio web de Capacitor.
Rotar sin causar una interrupción
Mantén un periodo de solapamiento al rotar una credencial. Añade el reemplazo al almacén de secretos, despliega la configuración del pipeline que lo utiliza, realiza una lectura autenticada inofensiva y solo entonces revoca la clave antigua. Si el servicio admite múltiples claves activas, mantén el valor antiguo disponible hasta que todos los workers y tareas programadas se hayan actualizado.
Para un equipo, registra el propietario de la clave, el propósito, el entorno, la fecha de creación y el procedimiento de revocación en un registro de acceso interno. No incluyas el secreto en sí en ese registro. Esto hace que la respuesta ante incidentes sea práctica sin convertir la documentación en otro repositorio de secretos.
El Estándares API del gobierno del Reino Unido recomiendan diseñar un documento OpenAPI pronto, validar inputs, rechazar atributos desconocidos, usar TLS 1.2 o superior y aplicar OAuth 2.0 para el control de acceso. Esos principios son útiles incluso cuando la integración usa claves API: define el contrato antes de construir la automatización, rechaza inputs inesperados y trata la seguridad de transporte como algo esencial.
Para patrones de almacenamiento y rotación en pipelines, usa guía de Capgo sobre gestión de secretos en pipelines de CI/CD.
Endpoints principales para la gestión de apps
La gestión de apps es el plano de control de todo lo demás. La creación de releases, la asignación de canales, la distribución de bundles y el diagnóstico requieren un identificador de aplicación estable. El error común es pasar un nombre de app legible para humanos en cada job asumiendo que será único. Resuelve la app una sola vez, persiste el identificador canónico y úsalo para las operaciones posteriores.
Una integración en producción debe modelar el ciclo de vida de la app basándose en cuatro capacidades:
| Operación | Intención HTTP | Preocupación de integración |
|---|---|---|
| Listar aplicaciones | GET |
Paginación, alcance de organización, identificadores estables |
| Obtener una aplicación | GET |
Versión de configuración y relación de despliegue |
| Actualizar configuración | PATCH o el método de actualización documentado |
Cambios parciales frente a reemplazo completo |
| Eliminar una aplicación | DELETE |
Acción irreversible, requiere aprobación y controles de auditoría |
No inventes rutas de endpoints basándote en un blog o en un SDK antiguo. Lee la definición actual legible por máquina y genera un cliente tipado o un wrapper de peticiones desde ese contrato. La Especificación OpenAPI describe un formato independiente del lenguaje de programación para APIs HTTP, permitiendo que personas y herramientas descubran endpoints, autenticación, esquemas de petición, respuestas y comportamiento sin inspeccionar el code fuente o el tráfico de red.
Crea un flujo de trabajo basado en identificadores
Un worker de despliegue debe realizar una lectura antes de ejecutar una mutación:
- Resuelve el contexto de la organización y la aplicación.
- Recupera el registro de la app y confirma que pertenece a la cuenta esperada.
- Compara la plataforma y el entorno deseados con la configuración devuelta.
- Guarda el identificador canónico de la app en el estado del job.
- Envía el release o el cambio de configuración usando ese identificador.
- Persiste el identificador de respuesta para realizar polling y diagnósticos posteriores.
Esta secuencia evita un tipo de errores muy costosos, donde una clave válida actualiza la app incorrecta porque una variable del pipeline apunta a un proyecto antiguo. Añade una validación de entorno explícita, como requerir que un job de staging apunte a la app de staging, antes de permitir la escritura.
Usa esquemas de respuesta en lugar de acceso JSON libre. Si API devuelve un objeto de app con campos de identifier, name, status y configuration, valida solo los campos que tu job necesita y tolera adiciones irrelevantes. Rechazar atributos de request desconocidos te protege de enviar claves de configuración mal escritas, mientras que un parsing de respuesta tolerante ayuda al cliente a sobrevivir a expansiones de respuesta que no rompan el flujo.
Para el diseño de rollback, mantén la identidad de la app separada de la identidad del release. Documentación de rollback y versionado de Capgo es la referencia operativa relevante. Un rollback debe seleccionar un estado de release o channel conocido como estable, no recrear la configuración de una aplicación de memoria.
Creación y gestión de releases
Un release de producción puede fallar tras un upload exitoso. El artifact puede estar almacenado correctamente mientras el procesamiento sigue incompleto, la asignación de channel no ha ocurrido o los dispositivos elegibles no han recibido la update. Trata el workflow como una secuencia de cambios de estado observables, con un identificador duradero y un plan de reintento para cada operación.
Preparar el payload del release
Usa el esquema actual de Capgo para los nombres de propiedades, rutas de solicitud y campos obligatorios. Un body de solicitud copiado de un endpoint similar podría aceptarse parcialmente o rechazarse por un error inesperado. En la práctica, el payload contiene tres áreas:
- Identidad de la aplicación: El identificador de la aplicación devuelto por la operación de control-plane correspondiente.
- Metadatos del release: La versión, identidad del bundle, contexto de build e información de compatibilidad que espera API.
- Intención de distribución: El canal o contexto de rollout, cuando la operación de release lo soporte.
Valida el bundle antes de enviarlo. Comprueba que el build de Capacitor contenga los web assets esperados, que su versión coincida con los metadatos de CI y que el job no esté leyendo un archivo incompleto. Calcula un checksum local cuando API lo acepte. Guarda la URL del build, la referencia del commit y el identificador de release del servidor en el registro de deployment para que jobs posteriores puedan correlacionar los eventos de upload, procesamiento y distribución.
Una secuencia fiable es:
- Hacer el build de la aplicación en un workspace limpio.
- Ejecutar checks unitarios, de integración y específicos de la plataforma.
- Crear o hacer upload del bundle mediante la operación de release documentada.
- Realiza polling de la operación o libera el recurso hasta que alcance un estado terminal.
- Asocia el release completado con su canal correspondiente.
- Verifica las señales de adopción y fallos antes de la promoción.
Una respuesta de upload confirma la aceptación del servicio, no la entrega a los usuarios. El estado de procesamiento, la elegibilidad del dispositivo, la conectividad y la pertenencia al canal siguen determinando si una actualización llega al dispositivo.
Haz que los reintentos sean seguros
Un timeout no indica si el servidor rechazó la petición o la completó antes de que fallara la conexión. Por tanto, reenviar el mismo release puede crear duplicados o versiones en conflicto. Usa una clave de idempotencia cuando Capgo la soporte. Sin esa opción, consulta los metadatos del release o un identificador de build generado por el cliente antes de reintentar una mutación.
Los batch uploads necesitan estado a nivel de ítem. Pon cada variante de la app en una cola duradera y registra su resultado de forma independiente. Un reintento del worker debería seleccionar solo los ítems pendientes, en lugar de repetir todo el batch tras un fallo. Si hay un endpoint bulk disponible, confirma si su respuesta incluye un resultado para cada ítem. Un estado de éxito agregado puede ocultar una variante fallida, mientras que un error agregado puede ocultar trabajo completado.
Regla operativa: Guarda el identificador de release del servidor inmediatamente, luego usa ese ID para comprobaciones de procesamiento, asignación de canales y diagnósticos.
Los rate limits afectan tanto a los uploads como al polling. Guía de rate-limiting de API señala que las cuotas deben reflejar la acción realizada y que los clientes necesitan headers útiles y un comportamiento de reintento. Aplica un manejo separado para la creación de releases, el polling de estado, las búsquedas y las mutaciones sensibles. Un bucle de polling que reintente a la velocidad de upload puede consumir la cuota necesaria para una acción correctiva.
Lee los headers de rate-limit cuando se devuelvan, respeta el intervalo de reintento proporcionado por el servidor y usa delays crecientes si no están presentes. Añade jitter para que múltiples workers de CI no reintenten al mismo tiempo. Limita el polling, detente en un estado terminal e incluye el cuerpo de la respuesta final en los logs de CI tras eliminar credenciales y tokens. Si alguien cancela un deployment, registra al actor o job de automatización, el estado actual del release y si el artifact sigue disponible para un reintento posterior.
Estrategia de canales y patrones de rollout
El diseño de canales es una decisión de gobernanza de releases, no solo un ejercicio de nomenclatura. Los canales de staging, beta y production sirven a diferentes audiencias y deben tener reglas de promoción distintas. La elección correcta depende de cuánta incertidumbre quede en el bundle y de qué tan rápido necesite feedback el equipo.
| Canal | Audiencia | Qué verificar | Decisión de promoción |
|---|---|---|---|
| Staging | Dispositivos internos y cuentas de prueba | Instalación, migraciones, compatibilidad nativa, logs | Los checks técnicos pasan |
| Beta | Usuarios seleccionados con acceso anticipado | Comportamiento real, feedback de soporte, adopción de updates | Sin regresiones críticas |
| Producción | Usuarios generales | Estabilidad, diagnósticos, preparación para rollback | Aprobación del responsable del release |
Un canal de staging debe ser determinista. Asigna dispositivos o cuentas de prueba conocidas, protege el canal de cambios accidentales y haz que el CI promueva solo tras pasar los checks necesarios. Beta es útil cuando importa el tráfico similar a producción, pero requiere una audiencia definida y un proceso de soporte para reportar fallos. Production debe ser algo aburrido: el release ya pasó los filtros previos, el objetivo de rollback es conocido y el monitoreo ya está conectado.
El workflow de API debe reflejar esos límites. Un pipeline puede crear el release una sola vez, asignarlo a staging y promover el mismo objeto de release tras la validación. Reconstruir entre canales debilita la trazabilidad, ya que el artifact probado por el equipo podría no ser el mismo que se distribuye a los usuarios.
El ecosistema actual de API también demuestra por qué el mantenimiento es tan importante como la amplitud. API Tracker presenta un gran catálogo de APIs y recursos para desarrolladores, mientras que los comentarios sobre los resúmenes públicos de API resaltan la carga de mantenimiento que surge cuando las entradas cubren finanzas, gobierno, salud, machine learning, clima y transporte. Un catálogo de canales tiene el mismo problema: las entradas obsoletas y la falta de claridad en la propiedad hacen que una lista larga sea menos útil que una pequeña y mantenida.
Para detalles de implementación sobre pruebas controladas, consulta entornos de staging de Capgo con canales. El patrón clave es convertir el movimiento de canales en una acción de API explícita con un límite de aprobación, en lugar de permitir que cualquier build job escriba directamente en producción.
Endpoints de monitoreo y diagnóstico
Un deployment no termina cuando el API devuelve una respuesta exitosa. Termina cuando el equipo puede explicar qué release descubrieron, descargaron e instalaron los dispositivos, y si siguen funcionando correctamente. Eso requiere un workflow que conecte identificadores de release, membresía de canales, registros de dispositivos, logs y datos de adopción.
Empieza con un registro de correlación en tu sistema de deployment. Guarda el identificador de la app, el identificador de release, el canal, la referencia del commit, los metadatos del build, el timestamp de la solicitud y el estado final de API. Cuando llegue un reporte de soporte, el operador debería poder pasar del dispositivo afectado a su canal y release sin buscar entre logs de CI no estructurados.
Consulta de forma específica antes de agregar
Los endpoints de diagnóstico suelen admitir filtros por rango de tiempo, canal, dispositivo, plataforma o release. Usa el filtro más específico para responder tu duda. Una consulta amplia en toda la base de instalaciones es más lenta, difícil de interpretar y propensa a límites de paginación o cuotas.
Una secuencia de investigación práctica es:
- Vista de release: Verifica si el release deseado existe y llegó al canal objetivo.
- Vista de adopción: Compara los dispositivos elegibles con los que detectaron o instalaron la update.
- Vista de fallos: Agrupa los errores por release, plataforma, clase de dispositivo y etapa de instalación.
- Vista de dispositivo: Inspecciona los logs de un dispositivo específico solo si el patrón agregado indica un problema local.
- Vista de incidente: Conserva la respuesta raw y los parámetros de la query usados en la investigación.
No asumas que una baja adopción significa que el bundle está roto. Los dispositivos pueden estar offline, excluidos del channel, usando una versión incompatible o esperando al check de updates. Por el contrario, un alto número de descargas no garantiza un inicio exitoso. Separa la detección, descarga, instalación y salud en runtime siempre que API exponga esos estados.
Conecta diagnósticos con automatización
Un worker programado puede consultar el estado del release y lanzar una alerta si este permanece en un estado no terminal más tiempo del permitido por el pipeline. Otro worker puede recolectar registros de fallos, normalizar códigos de error y adjuntarlos al ticket de deployment. Mantén el payload de la alerta conciso, con links al release, channel y la query de diagnóstico filtrada.
La autenticación y el manejo de errores deben estar en la misma capa de cliente que las llamadas a los endpoints. El worker debe refrescar o reemplazar credenciales según la política de credenciales, clasificar los fallos de autorización por separado de las peticiones malformadas y preservar 429 las respuestas para programar reintentos en lugar de tratarlas como errores genéricos del servidor.
Usa cursores de paginación u offsets documentados exactamente como se especifica. Un job de diagnóstico por lotes debe mantener su posición entre páginas y evitar solicitar la primera página repetidamente. Si los registros cambian mientras se ejecuta una query, usa un límite de tiempo estable o un filtro de release para que el reporte resultante sea reproducible.
Rate Limiting y Security Headers
Los clientes de producción deben inspeccionar los headers de respuesta antes de elegir una ruta de reintento. Captura X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After, y cualquier campo documentado RateLimit-* en el middleware del cliente API. Pásalos al controlador de reintentos y a los logs estructurados. No asumas code cuotas que puedan variar según la cuenta, el endpoint o la operación.
La distinción entre información de capacidad y instrucciones de reintento determina la siguiente petición. Un header de remaining-count indica qué tan cerca está el cliente de un límite. Retry-After especifica cuándo el servidor permite otro intento. Respeta esa instrucción cuando esté presente. Si la respuesta no ofrece guía de tiempos, usa exponential backoff con jitter y un límite de intentos fijo.
Protege la superficie de gestión
Mantén las peticiones de gestión de Capgo en un backend de confianza o un runner de CI. Una aplicación Capacitor puede llamar a un servicio limitado orientado a la app, pero nunca debe recibir credenciales que puedan modificar releases, channels o recursos de la organización. Aplica TLS, valida los bodies y elimina los headers de autorización de los traces y reportes de error.
Aplica controles separados por operación. Cachea o agrupa peticiones de metadatos de solo lectura cuando sea seguro. Asigna límites propios a los uploads, exports, intentos de login y mutaciones de release. Agrupa lecturas de metadatos independientes cuando API soporte operaciones por lote, y ten en cuenta los límites de peticiones e ítems del batch en lugar de asumir que un batch cuesta una sola unidad. Los controles basados en comportamiento también ayudan a detectar patrones de abuso distribuido, como se describe en el guía de seguridad sobre rate-limiting.
Usa timeouts en cada petición y distingue los fallos de transporte de las respuestas HTTP. Un timeout deja el resultado de la mutación en duda, así que consulta su estado antes de reintentar. Una 429 respuesta es feedback explícito del servidor, y el cliente debe programar el siguiente intento basándose en sus headers.
Para despliegues de Capacitor, la guía de rate-limiting de API de Capgo para cumplir con la app-store es una referencia operativa útil. Mantén las credenciales privadas, respeta los headers del servidor y haz que los reintentos sean observables en lugar de silenciosos.
Solución de errores comunes de API
La mayoría de los fallos se dividen en tres grupos: autenticación, validación y throttling. Diagnostica el grupo antes de cambiar code. El status de la respuesta, el cuerpo de error estructurado y los headers suelen dar información suficiente para decidir la siguiente acción.
Fallos de autenticación
Una 401 o una respuesta de autorización equivalente suele significar que la credencial falta, está mal formada, expiró, fue revocada o se envió con el esquema incorrecto. Revisa la variable de entorno dentro del job de CI real, no solo en tu shell local. Confirma que la petición incluya el formato exacto de header de la documentación actual de API y luego prueba la credencial con una operación de solo lectura.
Si la respuesta indica permisos insuficientes en lugar de una identidad inválida, trátalo como un problema de autorización. Pide a un administrador de la organización que revise el scope de la key, el acceso de la app y el entorno. No resuelvas un error de permisos distribuyendo una personal key con privilegios excesivos.
Cuerpos de solicitud inválidos
Una respuesta de validación significa que el servidor recibió la solicitud pero rechazó su estructura o valores. Compara el payload con el esquema actual, prestando atención a los campos obligatorios, tipos, valores enum, objetos anidados e identificadores. Elimina los campos no soportados en lugar de esperar que el servicio los ignore.
Registra un payload redactado y los errores por campo de la respuesta. Añade validación de esquema al CI para que los metadatos de release malformados fallen antes de iniciar un upload. Si la operación es una actualización parcial, confirma que el endpoint espere un cuerpo tipo patch en lugar de un reemplazo completo.
Throttling y mutaciones ambiguas
Una 429 significa que el worker debe dejar de enviar peticiones y seguir las instrucciones de reintento del servidor. Respeta Retry-After cuando esté presente, aplica jitter al calcular el delay de fallback y evita que varios workers concurrentes reintenten al mismo instante.
Para un timeout durante un upload o la creación de una release, no envíes otra mutación inmediatamente. Busca o recupera la operación usando la referencia de build generada por el cliente o el identificador devuelto si se recibió uno. Si no hay un identificador disponible, consulta al soporte documentado o al mecanismo de idempotencia de API si la solicitud original se completó. Esto evita releases duplicadas y hace que el registro de deployment final sea confiable.
Capgo ofrece una API REST pública para gestionar recursos de entrega de apps, releases, channels, dispositivos y flujos de despliegue, permitiendo a los equipos conectar las operaciones de Live Update con sus sistemas de CI/CD y monitoreo actuales. Revisa la Capgo documentación, crea una credencial de prueba con los mínimos privilegios y valida un flujo completo de release y rollback antes de automatizar el despliegue en producción.
