Flowyer
Conexión de asistentes de IA externos
Cómo conectar ChatGPT, Claude, Gemini, Grok, DeepSeek o Cursor a Flowyer, y qué puede y qué no puede hacer una clave de API.
¿Qué es esto?
Con una clave de API personal, un asistente de IA externo puede leer y crear registros en Flowyer en su nombre: expedientes, clientes, contactos de clientes, tareas, registros de horas, gastos, documentos, reservas de citas, tickets de soporte, mensajes del portal del cliente, eventos del calendario, entradas de litigios, vistas, asientos del registro de correspondencia, artículos de la base de conocimiento y comentarios; las facturas, los correos electrónicos de un expediente y las solicitudes de ausencia son de solo lectura. Si usted lo permite, también puede modificar registros. Cada solicitud se ejecuta exactamente con sus permisos, restringidos además por lo que usted permita en la clave. Algunas acciones también pueden enviar un mensaje a su cliente (una respuesta a un ticket por correo electrónico, una confirmación de cita, un mensaje del portal del cliente); el sistema solo los envía tras su confirmación expresa e independiente. Los expedientes, clientes y tareas creados por un bot llevan una pequeña marca en las listas que indica qué clave los creó; en los registros de horas, gastos, documentos y contactos de clientes, la clave creadora queda registrada, pero solo la ve un administrador del despacho, en "Registros creados a través de la API".
Lo que una clave NO puede hacer
- Nunca puede eliminar nada (una solicitud DELETE siempre responde 405).
- Solo puede cambiar un registro mediante las operaciones PATCH y los campos ofrecidos, indicando el expected_updated_at del registro (409 en caso de conflicto); no se sobrescribe nada más.
- Solo puede descargar el contenido de un documento con el permiso de descarga independiente (documents:download), mediante el enlace firmado de corta duración de documents.download; no tiene ningún otro acceso a los archivos.
- Nunca ve más que usted: las murallas chinas de los expedientes y los permisos de los módulos se aplican sin cambios.
Crear una clave de API
- Un administrador del despacho habilita el acceso a la API para el despacho en Configuración > Claves de API (está desactivado de forma predeterminada).
- En la misma página se crea una clave: asígnele un nombre (p. ej., "ChatGPT") para saber más adelante qué bot identifica cada clave.
- Marque lo que puede hacer el bot (leer, crear o modificar) y fije una fecha de caducidad. Los permisos de una clave no se pueden cambiar después: si necesita más, cree una nueva clave.
- La clave solo se muestra una vez: cópiela en la configuración del asistente. Puede revocarla en cualquier momento, con efecto inmediato.
Asigne a cada bot su propia clave. Así se pueden revocar por separado, y las listas de expedientes, clientes y tareas muestran cuál creó cada registro.
Permisos disponibles
matters:readLeer expedientesmatters:createCrear expedientesmatters:updateActualizar expedientesclients:readLeer clientesclients:createCrear clientesclients:updateActualizar clientescontacts:readLeer contactoscontacts:createCrear contactoscontacts:updateActualizar contactostasks:readLeer tareastasks:createCrear tareastasks:updateActualizar tareasworkhours:readLeer registros de horasworkhours:createRegistrar horasworkhours:updateActualizar registros de horascosts:readLeer gastoscosts:createRegistrar gastoscosts:updateActualizar gastosinvoices:readLeer facturasdocuments:readListar documentos (solo metadatos, sin descarga)documents:downloadDescargar documentos (contenido completo)documents:createSubir documentosdocuments:updateRenombrar documentoscolleagues:readListar miembros del equipo (solo nombres)knowledge:readLeer la base de conocimientoknowledge:createCrear entradas en la base de conocimientoknowledge:updateActualizar entradas de la base de conocimientoemails:readLeer correos electrónicos de expedienteslitigation:readListar el historial procesallitigation:createCrear entradas del historial procesallitigation:updateActualizar entradas del historial procesalmail_register:readLeer el registro de correspondenciamail_register:createCrear asientos en el registro de correspondenciamail_register:updateActualizar asientos del registro de correspondenciacomments:readLeer comentarios de expedientescomments:createPublicar comentarios en expedientescomments:updateEditar comentarios propios en expedientestrials:readLeer vistastrials:createCrear vistastrials:updateActualizar vistascourts:readListar tribunaleshr:readConsultar quién está de vacaciones (solo fechas)calendar:readLeer eventos del calendariocalendar:createCrear eventos del calendariocalendar:updateActualizar eventos del calendariobookings:readVer reservas de citasbookings:createCrear reservas de citas (envía un correo electrónico al cliente)bookings:updateReprogramar y editar reservasbookings:sendConfirmar o cancelar reservas (envía un correo electrónico al cliente)tickets:readLeer tickets de soportetickets:replyResponder a tickets (envía un correo electrónico al cliente)tickets:updateCambiar el estado de los ticketsportal:readPortal del cliente: leer conversaciones y mensajesportal:replyPortal del cliente: responder al cliente (publica un mensaje y le envía un correo electrónico)
Conexión
Utilice siempre exactamente el host https que empieza por www. (una redirección descartaría la cabecera de autorización). En las conexiones con clave de API, envíe la clave como "Authorization: Bearer <key>"; los clientes MCP, en cambio, se autentican con OAuth iniciando sesión en el navegador, por lo que no es necesario introducir ninguna clave.
- URL base
https://www.flowyer.es/api/agent- OpenAPI
https://www.flowyer.es/api/agent/openapi.json- MCP
-
https://mcp.flowyer.com/mcp
ChatGPT (Actions)
En un GPT personalizado, importe la descripción OpenAPI que figura a continuación en Actions, elija la autenticación por clave de API con el tipo "Bearer" y pegue su clave de Flowyer.
https://www.flowyer.es/api/agent/openapi.json
Grok
Proporcione a Grok la dirección de la descripción OpenAPI y la clave; la descripción le indica qué operaciones existen y qué parámetros admiten.
Claude Code
Claude Code se conecta al servidor MCP; en el primer uso le hace iniciar sesión en el navegador (OAuth), sin necesidad de clave:
claude mcp add --transport http flowyer https://mcp.flowyer.com/mcp
Claude Desktop / Cursor / Gemini CLI / DeepSeek
Claude Desktop, Cursor, Gemini CLI y los clientes MCP basados en DeepSeek admiten la misma dirección MCP en su archivo de configuración; en la primera conexión, el cliente le hace iniciar sesión en el navegador (OAuth), sin necesidad de introducir ninguna clave:
{
"mcpServers": {
"flowyer": {
"url": "https://mcp.flowyer.com/mcp"
}
}
}
REST (curl)
Ejemplos de llamadas REST directas:
curl -H "Authorization: Bearer flw_..." https://www.flowyer.es/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.es/api/agent/matters?q=2026/0025"
curl -X POST -H "Authorization: Bearer flw_..." -H "Content-Type: application/json" \
-H "Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f" \
-d '{"name":"Kovács Kft.","email":"info@kovacs.hu"}' https://www.flowyer.es/api/agent/clients
Reglas
Reintentos seguros (Idempotency-Key)
Cada creación admite una cabecera Idempotency-Key (o un campo idempotency_key): una solicitud repetida con el mismo valor devuelve el mismo registro en lugar de crear otro, y las claves distintas siempre crean registros distintos. Sin clave, una creación idéntica en un plazo de 120 segundos devuelve el primer registro.
Errores
Todos los errores tienen la misma estructura: un código para máquinas (error), un mensaje en inglés (message) y el mensaje en el idioma del despacho (message_localized). El mensaje indica qué hacer a continuación. No tiene sentido reintentar una solicitud sin cambios en caso de 401, 403, 404 y 422, con dos excepciones: con 404 upload_not_finished, termine primero la subida a upload_url y después vuelva a llamar a complete; con un token de acceso OAuth caducado (401 expired_key), renueve primero el token.
{
"error": "scope_missing",
"message": "This API key does not have the \"clients:create\" permission. ...",
"message_localized": "Ehhez az API-kulcshoz nem tartozik \"clients:create\" jogosultság. ...",
"locale": "hu",
"details": { "required_scope": "clients:create" }
}
| HTTP | error | Significado |
|---|---|---|
| 400 | invalid_json, use_www_host, bad_request | Solicitud mal formada: cuerpo JSON no válido, host incorrecto (utilice el host con www.) o una solicitud ilegible. |
| 401 | missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found | La clave falta, no es válida, ha sido revocada o ha caducado, su titular ya no está activo o no se encuentra el despacho de la clave. |
| 403 | scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived | Falta un permiso en la clave o en el usuario, o el despacho no ha habilitado la API. |
| 404 | not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible | El registro no existe o el usuario no puede verlo; endpoint desconocido; el archivo subido aún no ha llegado al almacenamiento (upload_not_finished: súbalo a upload_url y vuelva a llamar a complete); o una creación reintentada cuyo registro se creó anteriormente pero que desde entonces se ha eliminado u ocultado (replay_not_visible: no se ha creado nada nuevo, no lo vuelva a crear). |
| 405 | delete_not_allowed, update_not_allowed, method_not_allowed | No es posible eliminar a través de la API; solo se puede modificar donde la descripción ofrece una operación PATCH. |
| 409 | client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name | Ya existe un cliente con ese nombre; ya existe un documento con ese nombre en la carpeta (duplicate_name); el registro ha cambiado desde que lo leyó (record_conflict: vuelva a leerlo y reenvíe el cambio con el nuevo updated_at); el registro ha sido facturado o bloqueado (record_locked: realice el cambio en Flowyer); la Idempotency-Key se utilizó en otro recurso; o se está procesando una solicitud idéntica. |
| 413 | request_too_large, file_too_large | El cuerpo de la solicitud es demasiado grande (request_too_large) o el archivo que se va a subir supera el límite (file_too_large; details.max indica el límite en bytes). |
| 422 | validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long | Un campo no válido o ausente (details.fields indica cuál); un token de subida no válido, utilizado o caducado (upload_token_invalid: vuelva a iniciar la subida); o una carpeta que no pertenece al expediente (folder_not_in_matter). |
| 429 | rate_limited, auth_rate_limited | Demasiadas solicitudes (300 por minuto y clave); la cabecera Retry-After indica cuándo volver a intentarlo. |
| 500 | server_error | Error inesperado. La solicitud se ha registrado con su request_id; vuelva a intentarlo más tarde y, si se repite, indique ese id al soporte de Flowyer. |
| 503 | office_maintenance, office_setup_incomplete, temporarily_unavailable | El despacho no está disponible temporalmente (mantenimiento o configuración en curso); la cabecera Retry-After indica cuándo volver a intentarlo. |
Privacidad
El proveedor del asistente (p. ej., OpenAI, Anthropic, xAI) ve todos los datos que devuelve la clave. Entregue una clave solo a un bot cuyo tratamiento de datos haya aceptado el despacho, y solo con los permisos que realmente necesite.