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.

Referencia de la API para desarrolladores

¿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

Crear una clave de API

  1. Un administrador del despacho habilita el acceso a la API para el despacho en Configuración > Claves de API (está desactivado de forma predeterminada).
  2. 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.
  3. 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.
  4. 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

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" }
}
HTTPerrorSignificado
400invalid_json, use_www_host, bad_requestSolicitud mal formada: cuerpo JSON no válido, host incorrecto (utilice el host con www.) o una solicitud ilegible.
401missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_foundLa 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.
403scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archivedFalta un permiso en la clave o en el usuario, o el despacho no ha habilitado la API.
404not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visibleEl 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).
405delete_not_allowed, update_not_allowed, method_not_allowedNo es posible eliminar a través de la API; solo se puede modificar donde la descripción ofrece una operación PATCH.
409client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_nameYa 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.
413request_too_large, file_too_largeEl 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).
422validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_longUn 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).
429rate_limited, auth_rate_limitedDemasiadas solicitudes (300 por minuto y clave); la cabecera Retry-After indica cuándo volver a intentarlo.
500server_errorError 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.
503office_maintenance, office_setup_incomplete, temporarily_unavailableEl 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.