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 debería responder algo más que “¿qué endpoints existen?”. Debe mostrar cómo encajan la autenticación, los identificadores de recursos, el estado de 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 solo hacer peticiones de prueba aisladas.
Índice de contenidos
- Entender la autenticación de Capgo API
- Generación de tus credenciales API
- Endpoints principales para la gestión de 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
Entender la autenticación de Capgo API
El error de integración más común es enviar una solicitud válida con un 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 un 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 llama la documentación de Capgo API 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 las credenciales en una variable de entorno durante las pruebas locales. En CI/CD, inyéctalas mediante el secret store de la plataforma en lugar de subirlas a un repositorio, incluirlas en un bundle móvil o añadirlas a un query string. Una aplicación móvil no debe contener credenciales de gestión, ya que cualquier cosa enviada a un dispositivo puede ser inspeccionada.
Separa la identidad de la autorización
La autenticación responde a quién realiza la petición. La autorización responde a qué puede cambiar esa identidad. Trátalas como comprobaciones separadas al diseñar un servicio de despliegue.
Una clave personal puede ser ú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 más adecuada 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 permitan esa separación.
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 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: Enviar
Content-Type: application/jsonsolo cuando la petición contiene JSON. - El alcance es suficiente: Una credencial que puede leer metadatos de la app puede que no tenga permiso 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 herramientas de descubrimiento operativo. El registro histórico de ProgrammableWeb describe un directorio que superó las 19.000 APIs en enero de 2018, después de se añadieron 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 y moderna de API 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 apps 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 informal. Las etiquetas exactas del dashboard pueden cambiar, así que usa la interfaz y la documentación actuales de Capgo como referencia, pero el flujo de trabajo no cambia.
Crea una clave con un propósito
Entra en la configuración de la organización o de la cuenta, busca la pantalla de API o de developer-credentials y elige la acción para crear una clave. Dale un nombre que identifique su función, como un pipeline de deploy a staging o un worker de release de producción. Evita nombres basados solo en la identidad de una persona, porque la titularidad queda poco clara cuando cambia el equipo.
Selecciona los permisos más restrictivos disponibles 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, prefiere el límite más pequeño que siga soportando la tarea.
Copia el secreto cuando el dashboard lo muestre. Muchos sistemas de credenciales solo muestran el valor completo durante la creación. Guárdalo en tu gestor de secretos de CI/CD y luego prueba su recuperación dentro del pipeline sin imprimir el valor. Un entorno local .env el archivo puede ser útil durante el desarrollo, pero debe excluirse del control de versiones y nunca incluirse en un directorio web de Capacitor.
Rotar sin provocar una caída
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 pongas 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 considera la seguridad del transporte esencial.
Para patrones de almacenamiento y rotación en el pipeline, usa Guía de Capgo para gestionar 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 que sigue. 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. Un error común es pasar un nombre de app legible para humanos en cada tarea 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 | Aspecto 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 con el 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 post 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 después.
Esta secuencia evita 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 exigir que un job de staging apunte a la app de staging, antes de permitir una 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 y estable, no recrear la configuración de una app de memoria.
Creación y gestión de releases
Un release de producción puede fallar tras un upload exitoso. El artifact puede haberse guardado bien, pero el procesamiento sigue incompleto, no se asignó el channel o los dispositivos no recibieron la update. Trata el workflow como una secuencia de cambios de estado observables, con un identificador persistente y un plan de reintento para cada operación.
Prepara el payload del release
Usa el schema actual de Capgo para nombres de propiedades, rutas de request y campos obligatorios. Un request body copiado de un endpoint similar podría aceptarse parcialmente o rechazarse por un error inesperado. En la práctica, el payload tiene tres áreas:
- Identidad de la aplicación: El identificador de la aplicación devuelto por la operación de control-plane correspondiente.
- Metadata del release: La versión, bundle identity, build context e información de compatibilidad que espera API.
- Intención de distribución: El channel o contexto de rollout, cuando la operación de release lo soporte.
Valida el bundle antes de enviarlo. Verifica que el build de Capacitor contenga los web assets esperados, que su versión coincida con la metadata de CI y que no estés leyendo un archivo a medio escribir. Calcula un checksum local si API lo acepta. Guarda la URL del build, la referencia del commit y el identificador de release del servidor en el registro de deployment para que otros jobs puedan correlacionar el upload, el procesamiento y la distribución.
Una secuencia fiable es:
- Haz el build de la aplicación en un workspace limpio.
- Ejecuta pruebas unitarias, de integración y específicas de plataforma.
- Crea o sube el bundle mediante la operación de release documentada.
- Consulta periódicamente el recurso de operación o release devuelto hasta que alcance un estado terminal.
- Asocia el release completado con su channel previsto.
- Verifica señales de adopción y fallo antes de promover.
Una respuesta de upload confirma que el servicio la aceptó, no que se haya entregado a los usuarios. El estado de procesamiento, la elegibilidad del dispositivo, la conectividad y la pertenencia al channel siguen determinando si una actualización llega a un dispositivo.
Haz seguros los reintentos
Un timeout no revela si el servidor rechazó la petición o la completó antes de que fallara la conexión. Reenviar el mismo release puede crear duplicados o versiones en conflicto. Usa una clave de idempotencia cuando Capgo la soporte. Sin ella, consulta usando los metadatos del release o un identificador de build generado por el cliente antes de reintentar una mutación.
Las cargas por lotes necesitan estado a nivel de elemento. Pon cada variante de la app en una cola persistente y registra su resultado de forma independiente. Un reintento del worker debe seleccionar solo los elementos sin terminar, en lugar de repetir todo el batch tras un fallo. Si hay un endpoint masivo, confirma si su respuesta incluye un resultado para cada elemento. 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 de inmediato y úsalo para comprobaciones de procesamiento, asignación de channel y diagnósticos.
Los rate limits afectan tanto a los uploads como al polling. Guía de rate-limiting de API indica que las cuotas deben reflejar la acción realizada y que los clientes necesitan headers útiles y un comportamiento de retry. 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 reintenta a la velocidad de un upload puede consumir la cuota necesaria para una acción correctiva.
Lee los rate-limit headers cuando se devuelvan, respeta el intervalo de retry 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 body 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 de early-access | Comportamiento real, feedback de soporte, adopción de updates | Sin regresiones críticas |
| Producción | Usuarios generales | Estabilidad, diagnósticos, preparación para rollback | El responsable de la release aprueba |
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 requeridos. Beta es útil cuando importa el tráfico similar a producción, pero requiere una audiencia clara y un proceso de soporte para reportar fallos. Production debe ser aburrido: la release ya pasó los gates previos, el target de rollback es conocido y el monitoreo ya está conectado.
El workflow de API debe reflejar esos límites. Un pipeline puede crear la release una sola vez, asignarla 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 artifact distribuido a los usuarios.
El ecosistema actual de API también demuestra por qué el mantenimiento es tan vital como la variedad. API Tracker presenta un gran catálogo de APIs y recursos para desarrolladores, mientras que los comentarios en torno a las recopilaciones públicas de API destacan la carga de mantenimiento que supone que las entradas abarquen finanzas, gobierno, salud, machine learning, clima y transporte. Un catálogo de canales tiene el mismo problema: las entradas obsoletas y una propiedad poco clara hacen que una lista grande sea menos útil que una más pequeña y bien 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 explícita de API con un límite de aprobación, en lugar de permitir que cualquier job de build escriba directamente en producción.
Endpoints de monitoreo y diagnóstico
Un deployment no está completo cuando el API devuelve una respuesta exitosa. Está completo cuando el equipo puede explicar qué release descubrieron, descargaron e instalaron los dispositivos, y que siguieron ejecutándose correctamente. Eso requiere un workflow que conecte identificadores de release, pertenencia a 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 en logs de CI no estructurados.
Consulta de forma acotada 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 a 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: Comprueba si el release deseado existe y llegó al canal objetivo.
- Vista de adopción: Compara los dispositivos elegibles con los que descubrieron 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 señal de baja adopción significa que el bundle está roto. Los dispositivos pueden estar offline, excluidos del canal, usando una versión incompatible o esperando la comprobación de actualizaciones de la app. Por el contrario, un alto número de descargas no garantiza un inicio exitoso. Separa el descubrimiento, la descarga, la instalación y la salud en runtime siempre que API exponga esos estados.
Conecta los diagnósticos con la 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 que permite el pipeline. Otro worker puede recopilar registros de fallos, normalizar códigos de error y adjuntarlos al ticket de despliegue. Mantén el payload de la alerta conciso, con enlaces al release, al canal y a la consulta de diagnóstico filtrada.
La autenticación y la gestión de errores deben ir en la misma capa de cliente que las llamadas al endpoint. El worker debe refrescar o reemplazar las credenciales según la política de credenciales, clasificar los fallos de autorización por separado de las solicitudes malformadas y conservar 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 pueden cambiar mientras se ejecuta una consulta, usa un límite temporal estable o un filtro de release para que el informe resultante sea reproducible.
Rate limiting y headers de seguridad
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 al cliente, 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 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 la 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, Guía de Capgo sobre rate-limiting para cumplir con las tiendas de apps API 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 la 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 de header exacto 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, revisando 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 vez de un reemplazo completo.
Throttling y mutaciones ambiguas
Una 429 significa que el worker debe dejar de enviar solicitudes y seguir las pautas 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 en el 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 no hay identificador, consulta el soporte documentado o el mecanismo de idempotencia de API para saber si la solicitud original se completó. Esto evita releases duplicadas y garantiza la fiabilidad del registro de deployment final.
Capgo ofrece una API REST pública para gestionar recursos de entrega de apps, lanzamientos, canales, 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 lanzamiento y rollback antes de automatizar la promoción a producción.
