API REST: crear y gestionar tus claves

Tu web muestra tu disponibilidad, tu gestor quiere los presupuestos firmados, un script debe crear las solicitudes de un formulario propio. En todos esos casos, una herramienta tiene que hablar con Joinways sin pasar por la pantalla.

Para eso sirve la API REST de Joinways. Cada petición lleva una clave API, creada en « Configuración » > « Desarrolladores ». La clave actúa en tu espacio de trabajo con los permisos del rol de quien la creó.

Lo que vas a aprender

• Crear una clave y elegir su expiración.
• Enviar una primera petición a la API.
• Saber qué cubre la API y sus límites de uso.
• Rotar, renombrar y revocar una clave.

Requisitos previos

• El rol « Propietario » o « Administrador »: solo ellos ven la página « Desarrolladores ».
• El plan Pro o el periodo de prueba. En los demás planes, la página « Desarrolladores » propone pasar al Pro y las llamadas a la API se rechazan.
• Un lugar seguro para guardar la clave: un gestor de secretos o las variables de entorno del servidor de tu herramienta.

Consejo: para conectar un asistente de IA (Claude, ChatGPT, Cursor) no necesitas clave. Pega la URL del servidor MCP y aprueba la conexión: consulta Conectar Joinways a Claude (MCP).

1. Crear una clave

1. Abre « Configuración » > « Desarrolladores ». La pestaña « Claves API » se abre por defecto.
2. Haz clic en « Nueva clave ».
3. En « Nombre de la clave », indica el uso, por ejemplo « Web » o « Contabilidad ».
4. En « Expiración », elige « Nunca expira », « 30 días », « 90 días » o « 1 año ».
5. Haz clic en « Crear clave ».

La clave aparece bajo « Tu clave API (cópiala ahora): ». Cópiala enseguida: Joinways solo guarda su huella y no podrá volver a mostrarla.

Importante: una clave perdida no se recupera. Revócala y crea otra.

La lista « Tus claves API » muestra de cada clave su nombre, su prefijo (jw_ seguido de 8 caracteres), su fecha de creación, su último uso y su expiración. Una clave expirada lleva la etiqueta « Expirada ». Al pie de la tarjeta, « URL base de la API » recuerda la dirección a la que llamar.

Un espacio admite como máximo 10 claves activas. Por encima, aparece el mensaje « Límite de 10 claves alcanzado. Revoca una para crear otra. ».

2. Enviar una primera petición

Todas las direcciones empiezan por https://joinways.app/api/v1. Añade la clave en la cabecera Authorization, con la forma Bearer jw_…:

curl https://joinways.app/api/v1/events -H "Authorization: Bearer jw_tu_clave"

La API responde en JSON. Las listas se paginan con page y per_page (50 por defecto, 500 como máximo). La referencia completa, con cada ruta, sus campos y ejemplos, está en joinways.app/docs/api, también accesible desde el enlace « Documentación de la API » arriba de la página « Desarrolladores ». La especificación OpenAPI está en joinways.app/openapi.yaml.

3. Qué cubre la API

• Eventos: lista, ficha, creación, modificación, estado y etapa, archivo y restauración, jornadas, franjas de espacio, personal, contactos, notas, tareas, archivos, emails, hoja de función (BEO) y su PDF, importación de un presupuesto firmado.
• Horarios por día: un evento de varios días puede tener horarios distintos cada día, con el campo day_hours. Vale null cuando todos los días tienen el mismo horario.
• Solicitudes: lista, ficha, creación, estado, espacios solicitados, conversión en evento, vinculación con un evento existente, fusión de dos solicitudes.
• Presupuestos: lista, detalle con sus líneas, creación, duplicación, anulación, PDF, estado, líneas añadidas, modificadas o reordenadas. Un presupuesto llegado de una plataforma devuelve también las líneas leídas en su PDF (document_lines), solo lectura.
• Catálogo y paquetes: los artículos del catálogo, y los paquetes compuestos creados o modificados por su composición (is_package, components). En un presupuesto, un paquete se añade en una sola línea.
• Empresas, personas y tareas, con las notas de empresa y la búsqueda.
• Lugares: espacios, horarios de apertura, cierres, festivos, disponibilidad y conflictos en un periodo.
• Análisis: vista general, solicitudes, reactividad, indicadores comerciales, contables y de eventos.
• Webhooks, búsqueda global, notificaciones y miembros del equipo.

Cada ruta aplica las reglas de la app. Un evento archivado es de solo lectura, un presupuesto firmado ya no se modifica y un rol sin acceso a las solicitudes o a los presupuestos recibe un error 403 en esas rutas.

4. Qué puede hacer una clave

Una clave lleva los permisos de lectura y escritura del rol de su autor, tal como son hoy. Si un administrador vuelve a ser miembro, sus claves pierden enseguida esos permisos. Si deja el espacio, sus claves dejan de funcionar.

No existen claves de solo lectura. Una clave creada para mostrar la disponibilidad puede, técnicamente, modificar un presupuesto. La protección es por tanto operativa: una clave por herramienta, una expiración cuando sea posible y la revocación a la mínima duda.

5. Límites de uso y reintentos

• Plan Pro: 600 peticiones por minuto y 100 000 al día para el espacio.
• Periodo de prueba: 200 peticiones por minuto y 5 000 al día.
• Por dirección IP: 300 peticiones por minuto, antes incluso de la autenticación.
• Envío de emails: 20 por minuto para el espacio.

Cada respuesta lleva las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al superar un límite, la API responde 429 con una cabecera Retry-After en segundos.

Para repetir una escritura sin riesgo de duplicado, tras un corte de red por ejemplo, envía una cabecera Idempotency-Key con un valor único. Durante 24 horas, la misma petición con el mismo valor devuelve la respuesta de la primera, sin repetir la acción.

6. Rotar, renombrar o revocar una clave

Para sustituir una clave sin interrupción:

1. Crea una clave nueva.
2. Despliégala en tu herramienta y comprueba que funciona.
3. Revoca la antigua.

Para revocar una clave, haz clic en el icono de papelera junto a ella. La ventana « ¿Revocar la clave «Web»? » recuerda que las integraciones que la usan dejan de funcionar de inmediato. Confirma con « Revocar la clave ». La clave desaparece de la lista.

El icono de lápiz renombra una clave sin cambiar su valor. Cada creación, cambio de nombre y revocación queda registrado en un registro de auditoría.

Ejemplo: la disponibilidad de una finca en su web

Una finca de bodas quiere mostrar sus fechas libres en su web. Crea una clave « Web » con expiración de un año y la guarda en el servidor, nunca en el JavaScript de la página. Su web llama a GET /api/v1/venues/{venueId}/conflicts sobre los tres próximos meses: la respuesta lista los eventos que ya ocupan el lugar, teniendo en cuenta los espacios combinados, los tiempos de montaje y desmontaje, los cierres y los días sin apertura. La web marca esas fechas en gris. Dentro de un año, el equipo crea una clave nueva antes de revocar la antigua.

Solución de problemas

La API responde 401

Causa: falta la clave, está mal copiada, expirada o revocada, o su autor ha dejado el espacio. Solución: comprueba la cabecera Authorization: Bearer jw_… y el estado de la clave en « Desarrolladores ». Si hace falta, crea una clave nueva desde una cuenta activa.

La API responde 403

Causa: el espacio ya no tiene el plan Pro ni la prueba (plan_not_eligible), o el rol del autor de la clave no permite la acción. Un rol « Operaciones » no lee ni solicitudes ni presupuestos, un rol « Solo lectura » no escribe nada. Solución: comprueba el plan y el rol en « Configuración » > « Miembros del equipo », o crea la clave desde una cuenta de propietario o administrador.

La API responde 404 con un identificador que existe

Causa: el registro pertenece a otro espacio, o a un lugar que el autor de la clave no ve. Solución: comprueba el identificador y los lugares asignados a ese compañero.

La API responde 409

Causa: el estado del registro rechaza la acción, por ejemplo un evento archivado o un presupuesto firmado. El campo error.details.reason indica el motivo (event_archived, quote_locked…). Solución: lee ese motivo, por ejemplo restaura el evento con POST /api/v1/events/{id}/unarchive antes de modificarlo.

La API responde 429

Causa: se ha alcanzado un límite de uso. Solución: espera el tiempo indicado por Retry-After y espacia o agrupa tus llamadas.

Preguntas frecuentes

¿Puedo crear una clave de solo lectura?

No. Una clave lleva los permisos del rol de su autor. Para limitar el alcance de una filtración, crea una clave por herramienta y revócala en cuanto deje de usarse.

¿La aplicación móvil usa esta API?

No. La aplicación móvil pasa por una interfaz interna, reservada a la app y no documentada. Solo la API /api/v1 es pública, estable y está descrita en la referencia.

¿Una clave da acceso a otros espacios?

No. Una clave solo actúa en el espacio donde se creó. Un identificador de otro espacio responde 404.

¿Qué pasa con una clave cuando su autor deja el espacio?

Deja de funcionar. Crea las claves de las integraciones duraderas desde una cuenta que vaya a quedarse.

Ver también

• Conectar Joinways a Claude (MCP)
• Webhooks: enviar tus eventos de Joinways a tus herramientas
• Conectar Joinways con Zapier
• Seguridad y acceso