Primeros pasos con la Starter Application de Copera

La Starter Application de Copera es un portal de referencia que muestra cómo construir una aplicación web orientada al cliente impulsada por tu workspace de Copera. Usa un Board como su base de datos, de modo que puedes gestionar usuarios y tickets directamente en Copera mientras tu portal se encarga de la autenticación, el envío y la visualización.

Requisitos previos

Antes de comenzar, asegúrate de tener instalado y disponible lo siguiente:

Requisito	Versión / Notas
Node.js	>= 24.0.0
pnpm	10.16.1
Base de datos	Una instancia local o una base de datos gestionada en la nube
Workspace de Copera	Un workspace activo con un Board configurado (ver Paso 2)

Paso 1: Clona el repositorio

La starter application se publicará en github.com/copera-ai. Una vez disponible, clónala en tu máquina local:

git clone https://github.com/copera-ai/starter-application.git
cd starter-application

nota

Si el repositorio aún no es público, vuelve a consultar github.com/copera-ai o contacta al equipo de Copera para obtener acceso anticipado.

Paso 2: Configura tu Board en Copera

La starter application lee y escribe en un Board de Copera. Necesitas crear un Board con dos tablas — Users y Tickets — y luego copiar los IDs relevantes en el archivo de configuración de la aplicación.

Crea el Board

En tu workspace de Copera, ve a Collaborate en la barra lateral y crea un nuevo Board. Dale un nombre como "Portal Data".

Configura la tabla Users

Tu Board tendrá una tabla predeterminada. Renómbrala a Users y agrega las siguientes columnas:

Nombre de columna	Tipo de campo	Notas
Name	Texto	El nombre visible del usuario
Identifier	Texto	La dirección de correo del usuario (usada para iniciar sesión)
Password	Contraseña	Almacenada de forma segura; usada para la autenticación del portal
Role	Select (Desplegable)	Agrega dos opciones: admin y user

Configura la tabla Tickets

Agrega una segunda tabla al Board y nómbrala Tickets. Agrega las siguientes columnas:

Nombre de columna	Tipo de campo	Notas
Title	Texto	Un resumen breve del ticket
Details	Párrafo (Texto)	Descripción completa de la solicitud
User	Link	Enlace a la tabla Users
Status	Select (Desplegable)	Agrega opciones como open, in progress, closed
Request Type	Select (Desplegable)	Agrega opciones relevantes para tu caso de uso

Encuentra tu Board ID, Table IDs y Column IDs

Necesitas copiar varios IDs en la configuración de la aplicación. Aquí te indicamos dónde encontrar cada uno:

• Board ID — El Board ID aparece en la URL cuando tienes el Board abierto. Se ve así: app.copera.ai/boards/6abc123.... Copia el segmento que va después de /boards/.
• Table ID — Abre el Board y luego haz clic en la pestaña con el nombre de la tabla en la parte superior. El Table ID se muestra en el panel de configuración de la tabla, o puedes encontrarlo en la URL después de navegar a la tabla.
• Column ID — Haz clic en el ícono de configuración (engranaje o menú de tres puntos) en el encabezado de cualquier columna. El panel de configuración de la columna mostrará el ID de la columna. Copia este valor para cada columna que necesites referenciar.

Para un recorrido completo, consulta Finding Board, Table, and Column IDs.

consejo

Mantén un archivo de texto abierto mientras copias los IDs — necesitarás un Board ID, dos Table IDs y varios Column IDs antes de pasar al siguiente paso.

Edita src/config.ts

Abre src/config.ts en el repositorio clonado y completa los IDs que recopilaste:

export const config = {
  boardId: 'YOUR_BOARD_ID',
  tables: {
    users: {
      tableId: 'YOUR_USERS_TABLE_ID',
      columns: {
        name: 'YOUR_NAME_COLUMN_ID',
        identifier: 'YOUR_IDENTIFIER_COLUMN_ID',
        password: 'YOUR_PASSWORD_COLUMN_ID',
        role: 'YOUR_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'YOUR_TICKETS_TABLE_ID',
      columns: {
        title: 'YOUR_TITLE_COLUMN_ID',
        details: 'YOUR_DETAILS_COLUMN_ID',
        user: 'YOUR_USER_COLUMN_ID',
        status: 'YOUR_STATUS_COLUMN_ID',
        requestType: 'YOUR_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Paso 3: Configura las variables de entorno

La aplicación usa un archivo .env para almacenar secretos y detalles de conexión. Copia el archivo de ejemplo para empezar:

cp .env.example .env

Abre .env y completa los siguientes valores:

Variable	Descripción
MONGODB_URI	La cadena de conexión de tu instancia de base de datos (p. ej., mongodb://localhost:27017/starter o tu URI de Atlas)
APP_TOKEN	Cualquier cadena secreta usada para firmar los JWT de la gestión de sesiones del portal (p. ej., una cadena aleatoria larga)
COPERA_API_KEY	Un token de la API de Copera usado por el SDK. Usa una Integration API Key (con prefijo cp_key_) o un Personal Access Token (con prefijo cp_pat_), creado en Workspace Settings → Integrations

Para la app web (frontend), configura una variable adicional:

Variable	Descripción
VITE_SERVER_URL	La URL donde se ejecutará el servidor de la API (p. ej., http://localhost:3000)

consejo

Puedes generar una cadena aleatoria segura para APP_TOKEN usando openssl rand -hex 32 en tu terminal.

Cómo encontrar tu token de la API de Copera

1. En Copera, abre Workspace Settings → Integrations.
2. Para crear una Integration API Key (con prefijo cp_key_), abre la pestaña API Keys y crea una nueva clave. Las Integration API Keys funcionan para operaciones de boards y channels, que es todo lo que necesita la Starter Application.
3. Para crear en su lugar un Personal Access Token (con prefijo cp_pat_), abre la pestaña Personal Tokens y crea un nuevo token. Un PAT desbloquea toda la superficie de la API.
4. Copia el token de inmediato — se muestra solo una vez — y pégalo en COPERA_API_KEY en tu archivo .env.

Para una explicación más detallada de los tipos de tokens y los scopes, consulta la guía de autenticación.

Paso 4: Instala las dependencias y ejecuta

Con la configuración completa, instala las dependencias e inicia juntas la API y la app web:

pnpm install
pnpm dev

Esto inicia ambos servicios de forma simultánea:

• Servidor de la API — se ejecuta en el puerto definido en tu .env (por defecto: http://localhost:3000)
• App web — se ejecuta en el servidor de desarrollo (por defecto: http://localhost:5173)

Abre tu navegador y dirígete a la URL de la app web. Verás la página de inicio de sesión del portal.

Paso 5: Crea tu primer usuario

El portal no tiene un formulario de registro público por defecto — los usuarios se gestionan directamente en tu Board de Copera. Para crear el primer usuario:

1. En Copera, abre el Board que configuraste y navega a la tabla Users.
2. Agrega una nueva fila y completa las columnas Name, Identifier (correo), Password y Role.
3. Regresa a la app web en tu navegador.
4. Inicia sesión usando el correo y la contraseña que acabas de ingresar.

nota

Las contraseñas ingresadas en el Board son gestionadas por la capa de autenticación de la aplicación. El comportamiento exacto depende de cómo la starter app procese las credenciales — consulta los archivos src/config.ts y los del servicio de autenticación para más detalles.

Qué sigue

Ahora que la aplicación está en funcionamiento, aquí tienes algunas direcciones para llevarla más lejos:

• Personaliza el portal para tu caso de uso — Ajusta la UI, agrega nuevas páginas o cambia los campos del formulario de tickets para que se adapten a tu flujo de trabajo.
• Agrega columnas a tu Board — Cualquier nueva columna que agregues en Copera puede referenciarse en la app agregando su Column ID a src/config.ts.
• Usa herramientas de IA para construir nuevas funciones — La starter app está diseñada para ser un punto de partida. Usa asistentes de programación con IA junto con la API de Copera para acelerar el desarrollo.
• Explora la API de Copera — Revisa la API Reference para entender qué operaciones de datos están disponibles más allá de lo que demuestra la starter app.

consejo

Cuando agregues una nueva columna a tu Board en Copera, recuerda también agregar su Column ID a la sección correspondiente de src/config.ts para que la aplicación pueda leer y escribir ese campo.