Flowyer API

Referencia de la API de Flowyer

Versión de la API: 216c8ec357ff

La API REST completa de Flowyer para desarrolladores: endpoints, parámetros, respuestas y ejemplos de código.

Con la API de Flowyer, su propio software o un asistente de IA puede leer, crear y modificar registros (expedientes, clientes, tareas, registros de horas, gastos y documentos) en nombre de un usuario de Flowyer. Cada solicitud se ejecuta exactamente con los permisos de ese usuario, restringidos además por los ámbitos de la clave o de la autorización. No se puede eliminar nada a través de la API.

Las descripciones de los endpoints y de los campos están en inglés, porque los asistentes de IA leen exactamente el mismo texto.

URL base

Todos los endpoints se encuentran bajo las direcciones siguientes. Utilice siempre exactamente el host https que empieza por www., porque una redirección descartaría la cabecera Authorization.

URL base

https://www.flowyer.es/api/agent
https://www.flowyer.hu/api/agent
https://www.flowyer.com/api/agent
https://www.flowyer.ro/api/agent
https://www.flowyer.de/api/agent
https://www.flowyer.it/api/agent
https://www.flowyer.fr/api/agent

Autenticación

Cada solicitud necesita un token Bearer en la cabecera Authorization. Existen dos tipos de token; los endpoints tratan ambos de la misma manera.

Clave de API personal

El usuario la crea en Flowyer, en Configuración > Claves de API, una vez que un administrador del despacho ha habilitado la API. Una clave empieza por flw_, solo se muestra una vez y puede revocarse en cualquier momento con efecto inmediato.

OAuth 2.1 para aplicaciones conectadas

Una integración destinada a otros usuarios solicita acceso mediante el flujo OAuth 2.1 Authorization Code + PKCE (S256) en lugar de una clave; los clientes pueden registrarse de forma dinámica. Un token de acceso es válido durante 60 minutos, un token de actualización durante 60 días, y el par se sustituye en cada uso. El code_verifier de PKCE tiene entre 43 y 128 caracteres de A-Z, a-z, 0-9 y - . _ ~ (RFC 7636 4.1), es decir, base64url sin relleno: se rechaza un "=" final.

Metadatos del servidor
https://www.flowyer.com/.well-known/oauth-authorization-server
Autorización
https://www.flowyer.com/authorize
Token
https://www.flowyer.com/api/agent/oauth/token
Registro de clientes
https://www.flowyer.com/api/agent/oauth/register
Revocación
https://www.flowyer.com/api/agent/oauth/revoke

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/me' \
  -H 'Authorization: Bearer flw_...'

Ámbitos

Todos los endpoints, salvo GET /me, requieren un ámbito. Si la clave o la autorización no lo tiene, la respuesta es 403 scope_missing. GET /me no necesita ningún ámbito: utilícelo para ver qué puede hacer la credencial.

ÁmbitoSignificadoEndpoints
matters:read Leer expedientes GETListar expedientes GETListar tipos de expediente GETIdentificar expediente por nombre GETObtener expediente GETListar responsables del expediente
matters:create Crear expedientes POSTCrear expediente
matters:update Actualizar expedientes PATCHActualizar expediente POSTAñadir responsable del expediente
clients:read Leer clientes GETListar clientes GETResolver cliente por nombre GETObtener cliente
clients:create Crear clientes POSTCrear cliente
clients:update Actualizar clientes PATCHModificar cliente
contacts:read Leer contactos GETListar personas de contacto GETObtener persona de contacto GETListar personas de contacto del expediente
contacts:create Crear contactos POSTCrear persona de contacto
contacts:update Actualizar contactos PATCHModificar persona de contacto
tasks:read Leer tareas GETListar tareas GETObtener tarea
tasks:create Crear tareas POSTCrear tarea
tasks:update Actualizar tareas PATCHActualizar tarea POSTCerrar tarea
workhours:read Leer registros de horas GETListar registros de horas GETObtener registro de horas
workhours:create Registrar horas POSTRegistrar horas
workhours:update Actualizar registros de horas PATCHActualizar registro de horas
costs:read Leer gastos GETListar gastos GETObtener gasto
costs:create Registrar gastos POSTRegistrar gasto
costs:update Actualizar gastos PATCHModificar gasto
invoices:read Leer facturas GETListar facturas GETObtener factura
documents:read Listar documentos (solo metadatos, sin descarga) GETListar documentos del expediente GETListar carpetas del expediente GETListar versiones del documento
documents:download Descargar documentos (contenido completo) GETDescargar documento
documents:create Subir documentos POSTCrear carpeta del expediente POSTIniciar subida de documento POSTFinalizar subida de documento
documents:update Renombrar documentos PATCHRenombrar documento PATCHRenombrar carpeta del expediente
colleagues:read Listar miembros del equipo (solo nombres) GETListar miembros del equipo
knowledge:read Leer la base de conocimiento GETListar artículos de la base de conocimiento GETObtener artículo de la base de conocimiento GETListar categorías de la base de conocimiento GETObtener categoría de la base de conocimiento
knowledge:create Crear entradas en la base de conocimiento POSTCrear artículo de la base de conocimiento POSTCrear categoría de la base de conocimiento
knowledge:update Actualizar entradas de la base de conocimiento PATCHModificar artículo de la base de conocimiento PATCHModificar categoría de la base de conocimiento
emails:read Leer correos electrónicos de expedientes GETListar correos electrónicos del expediente GETObtener correo electrónico
litigation:read Listar el historial procesal GETListar historial procesal del expediente
litigation:create Crear entradas del historial procesal POSTCrear entrada del historial procesal
litigation:update Actualizar entradas del historial procesal PATCHModificar entrada del historial procesal
mail_register:read Leer el registro de correspondencia GETListar registro de correspondencia GETObtener entrada del registro de correspondencia
mail_register:create Crear asientos en el registro de correspondencia POSTCrear entrada del registro de correspondencia
mail_register:update Actualizar asientos del registro de correspondencia PATCHActualizar entrada del registro de correspondencia
comments:read Leer comentarios de expedientes GETListar comentarios del expediente
comments:create Publicar comentarios en expedientes POSTPublicar comentario en el expediente
comments:update Editar comentarios propios en expedientes PATCHEditar comentario propio del expediente
trials:read Leer vistas GETListar vistas del expediente GETObtener vista
trials:create Crear vistas POSTCrear vista
trials:update Actualizar vistas PATCHActualizar vista
courts:read Listar tribunales GETListar tribunales
hr:read Consultar quién está de vacaciones (solo fechas) GETListar ausencias del equipo
calendar:read Leer eventos del calendario GETListar eventos del calendario GETObtener evento del calendario
calendar:create Crear eventos del calendario POSTCrear evento del calendario
calendar:update Actualizar eventos del calendario PATCHModificar evento del calendario
bookings:read Ver reservas de citas GETListar reservas de cita GETObtener reserva de cita
bookings:create Crear reservas de citas (envía un correo electrónico al cliente) POSTCrear reserva de cita
bookings:update Reprogramar y editar reservas PATCHModificar reserva de cita
bookings:send Confirmar o cancelar reservas (envía un correo electrónico al cliente) POSTConfirmar reserva de cita POSTCancelar reserva de cita
tickets:read Leer tickets de soporte GETListar tickets GETObtener ticket
tickets:reply Responder a tickets (envía un correo electrónico al cliente) POSTResponder al ticket
tickets:update Cambiar el estado de los tickets PATCHCambiar estado del ticket
portal:read Portal del cliente: leer conversaciones y mensajes GETListar portales del cliente GETListar mensajes del portal
portal:reply Portal del cliente: responder al cliente (publica un mensaje y le envía un correo electrónico) POSTResponder en el portal del cliente

Errores

Todos los errores tienen la misma estructura: un código para máquinas (error), un mensaje en inglés (message), el mensaje en el idioma del despacho (message_localized) y detalles opcionales. 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.

HTTPerrorSignificado
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.

Ejemplos de respuesta · 403

{
  "error": "scope_missing",
  "message": "This API key does not have the \"clients:create\" permission. The permissions of an existing key cannot be changed, so the key owner needs to create a new key with this permission in Flowyer under Integrations > AI assistants and use it in place of the old one.",
  "message_localized": "Esta clave de API no tiene el permiso \"clients:create\". Los permisos de una clave existente no se pueden modificar, por lo que el titular de la clave debe crear una nueva clave con este permiso en Flowyer, en Integraciones > Asistentes de IA, y utilizarla en lugar de la anterior.",
  "locale": "es",
  "details": {
    "required_scope": "clients:create"
  },
  "request_id": "3f0c8a5e-2b1d-4c7a-9e6f-5a4b3c2d1e0f"
}

Paginación

Las listas de registros se paginan con los parámetros limit y offset (por defecto 25, como máximo 100 elementos por página). pagination.total es el número total de coincidencias; el offset de la página siguiente es el offset anterior más limit. GET /colleagues, GET /clients/resolve y GET /matters/resolve no están paginados: solo admiten limit (con su propio valor por defecto y máximo, consulte el endpoint) y devuelven total y truncated dentro de data en lugar de un objeto pagination, así que no les envíe offset.

Ejemplos de respuesta · 200

{
  "data": [
    {
      "id": 1234,
      "...": "..."
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 134
  }
}

Reintentos seguros

Cada creación admite una cabecera Idempotency-Key (o un campo idempotency_key). Una solicitud repetida con el mismo valor devuelve el registro creado la primera vez (200, idempotent_replay) en lugar de crear otro. Las claves distintas siempre crean registros distintos. Sin clave, una creación idéntica en un plazo de 120 segundos devuelve el primer registro.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/clients' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{"name": "Kovács Kft."}'

Modificaciones y conflictos

Una modificación es un PATCH en la propia ruta del registro: solo cambian los campos que envíe, y un null explícito vacía un campo cuando la descripción del campo lo permite; en algunos campos, null conserva el valor almacenado, así que lea la descripción del campo. Envíe en expected_updated_at el valor de updated_at de su última lectura. Si otra persona ha modificado el registro mientras tanto, la respuesta es 409 record_conflict; vuelva a leer el registro antes de reintentarlo.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/matters/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{"expected_updated_at": "2026-10-30T09:15:00+01:00", "description": null}'

Fechas y zona horaria

Las fechas tienen el formato AAAA-MM-DD y las marcas de tiempo siguen la norma ISO 8601 con el desfase de la zona horaria del despacho. La zona horaria del despacho figura en el campo office.timezone de GET /me.

Límites

Como máximo 300 solicitudes por minuto por clave o token; por encima de ese límite, la respuesta es 429 y la cabecera Retry-After indica cuándo volver a intentarlo. El cuerpo de una solicitud JSON puede ocupar como máximo 64 KB y un documento subido, como máximo 100 MB.

Versiones

La versión de la descripción OpenAPI cambia con cada modificación y también se envía como cabecera ETag, de modo que los clientes automáticos pueden comprobar con If-None-Match si ha cambiado.

Identificación

Quién soy

GET /api/agent/me

Devuelve el usuario y el despacho en cuyo nombre actúa esta clave de API, los ámbitos de la clave (lo que puede hacer) y los límites de frecuencia. Llámelo primero para saber qué operaciones están disponibles; no requiere ningún ámbito.

Este endpoint no recibe datos de entrada.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
user
object
Campos de user
id
integer
name
string | null
language
string | null
office
object
Campos de office
id
integer
name
string | null
timezone
string

Zona IANA en la que la API lee y escribe las marcas de tiempo, p. ej., Europe/Budapest.

currency_id
integer

La moneda del despacho (id de moneda de Flowyer): costs.create contabiliza en ella cuando se omite currency_id.

currency
string | null

Código ISO de la moneda del despacho, p. ej., HUF, EUR, RON.

key
object
Campos de key
id
integer
name
string

Nombre que el usuario dio a esta clave o, para un token OAuth, la aplicación conectada.

kind
string

"key" = una clave de API estática, "oauth" = un token de acceso OAuth 2.1.

Valores admitidos: "key" "oauth"
prefix
string | null

Primeros caracteres de una clave estática, solo a efectos de identificación; null para OAuth.

expires_at
string <date-time> | null
last_used_at
string <date-time> | null
scopes
string[]

Ámbitos de esta credencial, p. ej., "matters:read". Una operación cuyo ámbito falte responde 403.

available_scopes
string[]

Todos los ámbitos que el titular de la clave podría habilitar en Flowyer.

limits
object
Campos de limits
requests_per_minute
integer
list_max_limit
integer
channel
string

Cómo llegó la solicitud a Flowyer.

Valores admitidos: "rest" "mcp"
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

API deshabilitada para el despacho, licencia caducada o despacho archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

Parámetro de consulta desconocido (esta operación no admite ninguno); details.fields lo indica.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/me' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "user": {
      "id": 1234,
      "name": "string",
      "language": "string"
    },
    "office": {
      "id": 1234,
      "name": "string",
      "timezone": "string",
      "currency_id": 1234,
      "currency": "string"
    },
    "key": {
      "id": 1234,
      "name": "string",
      "kind": "key",
      "prefix": "string",
      "expires_at": "2026-10-30T09:15:00+01:00",
      "last_used_at": "2026-10-30T09:15:00+01:00"
    },
    "scopes": [
      "string"
    ],
    "available_scopes": [
      "string"
    ],
    "limits": {
      "requests_per_minute": 0,
      "list_max_limit": 0
    },
    "channel": "rest"
  }
}

Equipo

Listar miembros del equipo

GET /api/agent/colleagues

Lista los miembros activos del equipo del despacho (id, nombre) para assigned_to_user_id / responsible_user_id. Con q (un nombre tal como se oyó; tolera tildes, mayúsculas y pequeños errores tipográficos) responde con el estado exact/similar/none, como las herramientas de resolución: solo "exact" se puede usar directamente con seguridad.

Ámbito
colleagues:read

Parámetros de consulta

q
stringcomo máximo 255 caracteres

Nombre del miembro del equipo que se busca, tal como se oyó o se dictó, en cualquier orden de palabras. Omítalo para listar todos los miembros activos del equipo.

Ejemplo: "Nagy Péter"
limit
integer>= 1<= 500

Número máximo de miembros del equipo devueltos (valor predeterminado: 200).

Valor por defecto: 200

Respuestas

200

OK.

dataobligatorio
object
Campos de data
status
string | null

Solo con q: exact = una coincidencia segura (su id se puede usar con seguridad), similar = coincidencia aproximada o varias coincidencias (confírmelo antes con el usuario), none = sin coincidencias (pregunte al usuario). Null sin q.

Valores admitidos: "exact" "similar" "none"
colleagues
object[]

Miembros activos del equipo; con q, primero la mejor coincidencia; si no, por nombre.

Campos de colleagues
id
integer

Id del usuario: páselo como assigned_to_user_id / responsible_user_id.

name
string

Nombre visible tal como lo muestra Flowyer (con el tratamiento, si lo hay).

title
string | null

Prefijo del nombre, como "Dr.", o null.

total
integer

Cuántos miembros del equipo coincidían (sin q, todos los miembros activos) antes de recortar la lista a limit.

truncated
boolean

True cuando coincidieron más miembros del equipo de los devueltos: restrinja q o aumente limit.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/colleagues?q=Nagy%20P%C3%A9ter' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "status": "exact",
    "colleagues": [
      {
        "id": 1234,
        "name": "string",
        "title": "string"
      }
    ],
    "total": 1,
    "truncated": true
  }
}

Expedientes

Listar expedientes

GET /api/agent/matters

Muestra los expedientes que el usuario puede ver, del más reciente al más antiguo. Úselo para encontrar un expediente por número de expediente, asunto o cliente antes de hacer referencia a él en otro lugar. Los expedientes archivados se ocultan, salvo que include_archived sea true.

Ámbito
matters:read
Permiso de Flowyer
cases:read

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Búsqueda de texto libre en el asunto y en los nombres de los clientes (sin distinguir acentos ni mayúsculas y minúsculas) y en los demás números de expediente del despacho; o un número de expediente, ya sea exactamente como se devuelve en case_number (el sistema de numeración del despacho) o como año/número de orden, por ejemplo "2026/0025".

Ejemplo: "2026/0025"
client_id
integer>= 1

Solo los expedientes de este cliente.

Ejemplo: 512
responsible_user_id
integer>= 1

Solo los expedientes de los que es responsable este usuario (ids de colleagues.list): como responsable principal, como responsable adicional o como miembro de un grupo de trabajo responsable (igual que el filtro de equipo de la web).

updated_since
string <date-time>

Solo los expedientes modificados en este momento o después (ISO 8601).

Ejemplo: "2026-10-01T00:00:00+02:00"
include_archived
boolean

Incluir los expedientes archivados.

Valor por defecto: false
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters?q=2026%2F0025&client_id=512&updated_since=2026-10-01T00%3A00%3A00%2B02%3A00' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "case_number": "2026/0025",
      "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
      "status": "active",
      "case_type_id": 1234,
      "case_type": "string",
      "responsible_user_id": 1234,
      "responsible": "string",
      "clients": [
        {
          "id": 1234,
          "name": "string"
        }
      ],
      "started_on": "2026-10-30",
      "restricted": true,
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Listar tipos de expediente

GET /api/agent/case-types

Muestra los tipos de expediente de Flowyer (áreas del derecho) como id + nombre en el idioma del despacho, para el case_type_id de matters.create: haga corresponder las palabras del usuario con un nombre y pase ese id. Consulte esta lista una vez en lugar de adivinar; se excluye el marcador "-" (id 0).

Ámbito
matters:read

Este endpoint no recibe datos de entrada.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
case_types
object[]

Los tipos de expediente de Flowyer, ordenados por nombre.

Campos de case_types
id
integer

Id del tipo de expediente: páselo como case_type_id a matters.create.

name
string

Nombre del tipo de expediente (área del derecho) en el idioma del despacho.

total
integer

Número de tipos de expediente devueltos.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

Parámetro de consulta desconocido (esta operación no admite ninguno); details.fields lo indica.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/case-types' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "case_types": [
      {
        "id": 1234,
        "name": "string"
      }
    ],
    "total": 1
  }
}

Identificar expediente por nombre

GET /api/agent/matters/resolve

Encuentra un expediente a partir de un asunto o nombre de cliente pronunciado o mal escrito (tolera acentos, mayúsculas y minúsculas y pequeñas erratas). Devuelve el estado exact/similar/none y los candidatos. Solo "exact" puede usarse directamente con seguridad; en otro caso, confírmelo con el usuario. Cuando hay muchos parecidos, nunca se obtiene "exact": acote con client_id o un nombre más completo.

Ámbito
matters:read
Permiso de Flowyer
cases:read

Parámetros de consulta

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Asunto del expediente o nombre del cliente que se busca, tal como se oyó o se dictó.

Ejemplo: "ingatlan adásvétel"
client_id
integer | null>= 1

Solo los expedientes de este cliente (úselo después de que clients.resolve haya devuelto un cliente exacto).

limit
integer>= 1<= 10

Número máximo de candidatos devueltos (valor predeterminado: 5).

Valor por defecto: 5

Respuestas

200

OK.

dataobligatorio
object
Campos de data
status
string

exact = una coincidencia segura (su id se puede usar con seguridad). similar = una o varias coincidencias aproximadas; confírmelo antes con el usuario. none = sin coincidencias; pregunte al usuario.

Valores admitidos: "exact" "similar" "none"
matters
object[]

Expedientes candidatos, empezando por la mejor coincidencia.

Campos de matters
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
total
integer

Cuántos expedientes coincidieron antes de recortar la lista a limit.

truncated
boolean

True si coincidieron más expedientes de los devueltos, o si había demasiados parecidos para comprobarlos todos; acote con client_id o un nombre más completo, o aumente limit, en lugar de elegir de una lista incompleta.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/resolve?name=ingatlan%20ad%C3%A1sv%C3%A9tel' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "status": "exact",
    "matters": [
      {
        "id": 1234,
        "case_number": "2026/0025",
        "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
        "status": "active",
        "case_type_id": 1234,
        "case_type": "string",
        "responsible_user_id": 1234,
        "responsible": "string",
        "clients": [
          {
            "id": 1234,
            "name": "string"
          }
        ],
        "started_on": "2026-10-30",
        "restricted": true,
        "created_at": "2026-10-30T09:15:00+01:00",
        "updated_at": "2026-10-30T09:15:00+01:00",
        "created_via_api": {
          "kind": "key",
          "key_id": 1234,
          "key_name": "string",
          "user_id": 1234,
          "user": "string",
          "at": "2026-10-30T09:15:00+01:00"
        }
      }
    ],
    "total": 1,
    "truncated": true
  }
}

Obtener expediente

GET /api/agent/matters/{id}

Devuelve un expediente con sus clientes y detalles. Responde 404 si el expediente no existe o el usuario no puede verlo.

Ámbito
matters:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
description
string | null
litigious
boolean
archived_at
string <date> | null

Día en que se archivó el expediente, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "case_number": "2026/0025",
    "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
    "status": "active",
    "case_type_id": 1234,
    "case_type": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "clients": [
      {
        "id": 1234,
        "name": "string"
      }
    ],
    "started_on": "2026-10-30",
    "restricted": true,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "description": "string",
    "litigious": true,
    "archived_at": "2026-10-30"
  }
}

Crear expediente

POST /api/agent/matters

Abre un expediente con el siguiente número de expediente del año. Requiere al menos un cliente existente (búsquelo o créelo antes). El abogado responsable es, por defecto, el usuario de la clave; en caso contrario, recibe una notificación. Las partes, los contactos y los honorarios se configuran en Flowyer.

Ámbito
matters:create
Permiso de Flowyer
cases:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

subjectobligatorio
stringal menos 2 caracterescomo máximo 255 caracteres

Título breve del expediente tal como aparece en las listas. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
case_type_idobligatorio
integer>= 1

Id del tipo de expediente (área del derecho). Obtenga los ids y nombres válidos con case_types.list y elija el que corresponda a las palabras del usuario, o pida al usuario que elija por nombre. Un id desconocido sigue respondiendo 422 con details.known_case_types; un expediente existente muestra su tipo en matters.get case_type_id / case_type.

client_idsobligatorio
integer[]al menos 1 elementoscomo máximo 20 elementos

Ids de los clientes (mandantes). Como mínimo uno y como máximo 20.

Ejemplo: [ 512 ]
responsible_user_id
integer | null>= 1

Abogado responsable: un id de usuario de colleagues.list (busque allí el nombre dictado). Valor predeterminado: el usuario titular de la clave.

started_on
string <date> | null

Fecha de inicio, YYYY-MM-DD. Valor predeterminado: hoy.

Ejemplo: "2026-10-29"
description
string | nullcomo máximo 10000 caracteres

Descripción más extensa, texto sin formato.

main_case_number
string | nullcomo máximo 100 caracteres

Número de referencia principal propio del despacho para el expediente. Obligatorio si el sistema de numeración del despacho lo utiliza (de lo contrario, la API responde 422).

restricted
boolean

true = solo los abogados responsables pueden ver el expediente (muralla china).

Valor por defecto: false
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
description
string | null
litigious
boolean
archived_at
string <date> | null

Día en que se archivó el expediente, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
description
string | null
litigious
boolean
archived_at
string <date> | null

Día en que se archivó el expediente, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
  "case_type_id": 1234,
  "client_ids": [
    512
  ],
  "started_on": "2026-10-29"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "case_number": "2026/0025",
    "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
    "status": "active",
    "case_type_id": 1234,
    "case_type": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "clients": [
      {
        "id": 1234,
        "name": "string"
      }
    ],
    "started_on": "2026-10-30",
    "restricted": true,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "description": "string",
    "litigious": true,
    "archived_at": "2026-10-30"
  },
  "created": true
}

Actualizar expediente

PATCH /api/agent/matters/{id}

Modifica el asunto, la descripción, la fecha de inicio, el indicador de contencioso o el abogado responsable de un expediente. El número de expediente, la muralla china, el estado de archivo, los honorarios y los vínculos con clientes no se pueden editar aquí. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409.

Ámbito
matters:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

subject
string | nullal menos 1 caracteres

Título breve del expediente. Texto sin formato, como máximo 255 caracteres como valor NUEVO; tampoco se pueden introducir "<" ni ">", pero un asunto almacenado más largo o que los contenga puede reenviarse sin cambios. null conserva el asunto actual.

description
string | null

Descripción más extensa, texto sin formato, como máximo 10000 caracteres como valor NUEVO; una descripción almacenada más larga puede reenviarse sin cambios.

started_on
string <date> | null

Fecha de inicio, YYYY-MM-DD. null conserva el valor actual (la fecha de inicio no se puede borrar).

litigious
boolean

Indica si el expediente es contencioso.

responsible_user_id
integer | null>= 0

Nuevo abogado responsable: el id de usuario de un miembro activo del equipo de colleagues.list. Recibe una notificación si no es usted. Enviar el actual (o null / 0, que es lo que devuelve un expediente sin responsable) no cambia nada.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id del expediente. Úselo como matter_id en otros lugares.

Ejemplo: 1234
case_number
string

Número de expediente tal como se muestra en Flowyer, según el sistema de numeración del despacho.

Ejemplo: "2026/0025"
subject
string
Ejemplo: "Kovács Kft. v. Nagy Bt. - contract dispute"
status
string
Valores admitidos: "active" "archived"
case_type_id
integer | null
case_type
string | null

Nombre localizado del tipo de expediente.

responsible_user_id
integer | null
responsible
string | null

Nombre visible del abogado responsable.

clients
object[]

Clientes (mandantes) del expediente.

Campos de clients
id
integer
name
string
started_on
string <date> | null
restricted
boolean

True si solo los abogados responsables pueden ver el expediente (muralla china).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
description
string | null
litigious
boolean
archived_at
string <date> | null

Día en que se archivó el expediente, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/matters/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "subject": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "case_number": "2026/0025",
    "subject": "Kovács Kft. v. Nagy Bt. - contract dispute",
    "status": "active",
    "case_type_id": 1234,
    "case_type": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "clients": [
      {
        "id": 1234,
        "name": "string"
      }
    ],
    "started_on": "2026-10-30",
    "restricted": true,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "description": "string",
    "litigious": true,
    "archived_at": "2026-10-30"
  },
  "updated": true
}

Listar responsables del expediente

GET /api/agent/matters/{id}/responsibles

Muestra los responsables ADICIONALES de un expediente (el responsable principal figura en matters.get): cada uno es un miembro del equipo (type "user", con user_id) o un grupo de trabajo (type "workgroup", con workgroup_id), y todos ellos pueden ver el expediente. Responde 404 si el expediente no es visible.

Ámbito
matters:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
type
string

"user" = un único miembro del equipo; "workgroup" = todos los miembros de un grupo de trabajo.

Valores admitidos: "user" "workgroup"
user_id
integer | null

Id de usuario del miembro del equipo para una entrada "user" (páselo como user_id a matters.responsibles.add); null para un grupo de trabajo.

workgroup_id
integer | null

Id del grupo de trabajo para una entrada "workgroup"; null para un único miembro del equipo. Los grupos de trabajo responsables se gestionan en Flowyer.

name
string | null

Nombre visible del miembro del equipo o del grupo de trabajo.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/responsibles?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "type": "user",
      "user_id": 1234,
      "workgroup_id": 1234,
      "name": "string"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Añadir responsable del expediente

POST /api/agent/matters/{id}/responsibles

Añade a un miembro del equipo (user_id de colleagues.list) como responsable adicional de un expediente. Esto DA a ese miembro del equipo acceso al expediente, así que añada solo a quien deba verlo; recibe una notificación. Idempotente: volver a añadir un responsable existente no cambia nada.

Ámbito
matters:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Expediente del que pasa a ser responsable el miembro del equipo (debe ser visible).

Ejemplo: 1234

Cuerpo de la solicitud application/json

user_idobligatorio
integer>= 1

Miembro del equipo que se añade: un id de usuario de colleagues.list. Al añadirlo, obtiene acceso al expediente.

Ejemplo: 42

Respuestas

200

OK.

dataobligatorio
object
Campos de data
user_id
integer

El miembro del equipo que ahora es responsable del expediente.

name
string | null

Nombre visible del miembro del equipo.

already_responsible
boolean

True si el miembro del equipo ya era responsable del expediente (no ha cambiado nada).

notified
boolean

True si se notificó al miembro del equipo que se le había añadido. Nunca es true cuando el miembro del equipo es usted o cuando ya era responsable.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/responsibles' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": 42
}'

Ejemplos de respuesta

{
  "data": {
    "user_id": 1234,
    "name": "string",
    "already_responsible": true,
    "notified": true
  }
}

Clientes

Listar clientes

GET /api/agent/clients

Lista los clientes del despacho (personas y empresas) por orden alfabético; q busca en el nombre (sin distinguir tildes ni mayúsculas), el correo electrónico y el NIF. Antes de crear un cliente, compruebe el nombre con clients.resolve (también tolera errores tipográficos). Los clientes archivados se ocultan, salvo que include_archived sea true.

Ámbito
clients:read
Permiso de Flowyer
contacts:read

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Buscar en el nombre (sin distinguir tildes ni mayúsculas), el correo electrónico y el NIF.

Ejemplo: "Kovács"
is_person
boolean

true = solo personas físicas, false = solo empresas.

include_archived
boolean
Valor por defecto: false
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/clients?q=Kov%C3%A1cs&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 512,
      "name": "Kovács Kft.",
      "is_person": true,
      "email": "info@example.hu",
      "phone": "string",
      "archived": true,
      "recorded_by_user_id": 1234,
      "recorded_by": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Resolver cliente por nombre

GET /api/agent/clients/resolve

Localiza un cliente a partir de un nombre pronunciado o mal escrito (tolera tildes, mayúsculas y pequeños errores tipográficos). Devuelve el estado exact/similar/none y los clientes candidatos. Solo "exact" se puede usar directamente con seguridad; con "similar" o "none", pregunte al usuario. Un nombre con muchos parecidos nunca es "exact": pida un nombre más completo.

Ámbito
clients:read
Permiso de Flowyer
contacts:read

Parámetros de consulta

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nombre del cliente que se busca, tal como se oyó o se dictó.

Ejemplo: "Józsi ingatlan"
limit
integer>= 1<= 10

Número máximo de candidatos devueltos (valor predeterminado: 5).

Valor por defecto: 5

Respuestas

200

OK.

dataobligatorio
object
Campos de data
status
string

exact = una coincidencia segura (su id se puede usar con seguridad). similar = una o varias coincidencias aproximadas; confírmelo antes con el usuario. none = sin coincidencias; pregunte al usuario.

Valores admitidos: "exact" "similar" "none"
matches
object[]

Clientes candidatos, primero la mejor coincidencia.

Campos de matches
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
total
integer

Cuántos clientes coincidían antes de recortar la lista a limit.

truncated
boolean

True cuando coincidieron más clientes de los devueltos, o había demasiados parecidos para comprobarlos todos; pida al usuario un nombre más completo o aumente limit en lugar de elegir de una lista incompleta.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/clients/resolve?name=J%C3%B3zsi%20ingatlan' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "status": "exact",
    "matches": [
      {
        "id": 512,
        "name": "Kovács Kft.",
        "is_person": true,
        "email": "info@example.hu",
        "phone": "string",
        "archived": true,
        "recorded_by_user_id": 1234,
        "recorded_by": "string",
        "created_at": "2026-10-30T09:15:00+01:00",
        "updated_at": "2026-10-30T09:15:00+01:00",
        "created_via_api": {
          "kind": "key",
          "key_id": 1234,
          "key_name": "string",
          "user_id": 1234,
          "user": "string",
          "at": "2026-10-30T09:15:00+01:00"
        }
      }
    ],
    "total": 1,
    "truncated": true
  }
}

Obtener cliente

GET /api/agent/clients/{id}

Devuelve un cliente con su dirección y sus datos registrales. Nunca se devuelven números de documentos de identidad ni la configuración de honorarios.

Ámbito
clients:read
Permiso de Flowyer
contacts:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del cliente.

Ejemplo: 512

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
address
object
Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
tax_number
string | null

Solo empresas; null para una persona física.

company_registration_number
string | null

Solo empresas; null para una persona física.

representative_name
string | null

Solo empresas; null para una persona física.

representative_position
string | null

Solo empresas; null para una persona física.

main_activity
string | null

Actividad principal. Solo empresas; null para una persona física.

nationality_country
string | null
note
string | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/clients/512' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 512,
    "name": "Kovács Kft.",
    "is_person": true,
    "email": "info@example.hu",
    "phone": "string",
    "archived": true,
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "mailing_address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "tax_number": "string",
    "company_registration_number": "string",
    "representative_name": "string",
    "representative_position": "string",
    "main_activity": "string",
    "nationality_country": "string",
    "note": "string"
  }
}

Crear cliente

POST /api/agent/clients

Crea un cliente (persona o empresa), registrado como creado por el usuario de la clave. Compruebe antes el nombre con clients.resolve (tolera tildes ausentes y errores tipográficos): un 409 solo detecta un cliente activo con exactamente el mismo nombre, salvo que allow_duplicate_name sea true. No se pueden establecer números de documento de identidad ni honorarios.

Ámbito
clients:create
Permiso de Flowyer
contacts:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

nameobligatorio
stringal menos 2 caracterescomo máximo 255 caracteres

Nombre completo de la persona o denominación de la empresa. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Kovács Kft."
is_person
boolean

true para una persona física, false (valor predeterminado) para una empresa.

Valor por defecto: false
email
string | nullcomo máximo 190 caracteres
Ejemplo: "info@kovacskft.hu"
phone
string | nullcomo máximo 64 caracteres
Ejemplo: "+36 1 234 5678"
address
object | null

Domicilio social / domicilio particular.

Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object | null
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
tax_number
string | nullcomo máximo 64 caracteres

NIF de la empresa (solo empresas).

Ejemplo: "12345678-2-41"
company_registration_number
string | nullcomo máximo 64 caracteres

Número de inscripción en el Registro Mercantil (solo empresas).

Ejemplo: "01-09-123456"
representative_name
string | nullcomo máximo 255 caracteres

Solo empresas.

representative_position
string | nullcomo máximo 255 caracteres

Solo empresas.

main_activity
string | nullcomo máximo 255 caracteres

Actividad principal (solo empresas).

nationality_country
string | nullcomo máximo 100 caracteres
note
string | nullcomo máximo 4000 caracteres
allow_duplicate_name
boolean

Crear aunque exista un cliente activo con el mismo nombre.

Valor por defecto: false
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
address
object
Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
tax_number
string | null

Solo empresas; null para una persona física.

company_registration_number
string | null

Solo empresas; null para una persona física.

representative_name
string | null

Solo empresas; null para una persona física.

representative_position
string | null

Solo empresas; null para una persona física.

main_activity
string | null

Actividad principal. Solo empresas; null para una persona física.

nationality_country
string | null
note
string | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
address
object
Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
tax_number
string | null

Solo empresas; null para una persona física.

company_registration_number
string | null

Solo empresas; null para una persona física.

representative_name
string | null

Solo empresas; null para una persona física.

representative_position
string | null

Solo empresas; null para una persona física.

main_activity
string | null

Actividad principal. Solo empresas; null para una persona física.

nationality_country
string | null
note
string | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

Existe un cliente activo con el mismo nombre (client_exists, o client_exists_generic sin el ámbito clients:read, cuando no se puede nombrar el cliente existente; pase allow_duplicate_name para forzarlo), la Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando una solicitud idéntica (duplicate_in_progress).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/clients' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "name": "Kovács Kft.",
  "email": "info@kovacskft.hu",
  "phone": "+36 1 234 5678",
  "tax_number": "12345678-2-41",
  "company_registration_number": "01-09-123456"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 512,
    "name": "Kovács Kft.",
    "is_person": true,
    "email": "info@example.hu",
    "phone": "string",
    "archived": true,
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "mailing_address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "tax_number": "string",
    "company_registration_number": "string",
    "representative_name": "string",
    "representative_position": "string",
    "main_activity": "string",
    "nationality_country": "string",
    "note": "string"
  },
  "created": true
}

Modificar cliente

PATCH /api/agent/clients/{id}

Modifica los campos de contacto de un cliente (nombre, correo electrónico, teléfono, dirección, nota, nacionalidad y representante/actividad de la empresa). Los números de documento de identidad, el NIF, los honorarios y el tipo persona/empresa no se pueden editar aquí. Pase expected_updated_at; un cambio en conflicto responde 409.

Ámbito
clients:update
Permiso de Flowyer
contacts:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

name
string | nullal menos 1 caracteres

Nombre completo o denominación de la empresa. Texto sin formato, como máximo 255 caracteres como valor NUEVO; tampoco se pueden introducir "<" ni ">", pero un nombre almacenado más largo o que los contenga se puede devolver sin cambios. null mantiene el nombre actual.

email
string | nullcomo máximo 190 caracteres
phone
string | nullcomo máximo 64 caracteres
address
object | null

Domicilio social / domicilio particular.

Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object | null
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
representative_name
string | nullcomo máximo 255 caracteres

Solo empresas.

representative_position
string | nullcomo máximo 255 caracteres

Solo empresas.

main_activity
string | nullcomo máximo 255 caracteres

Actividad principal (solo empresas).

nationality_country
string | nullcomo máximo 100 caracteres
note
string | null

Nota en texto libre, como máximo 4000 caracteres como valor NUEVO; una nota almacenada más larga se puede devolver sin cambios. null borra la nota.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id del cliente. Úselo como client_id en otros puntos.

Ejemplo: 512
name
string
Ejemplo: "Kovács Kft."
is_person
boolean

True para una persona física, false para una empresa.

email
string | null
phone
string | null
archived
boolean
recorded_by_user_id
integer | null
recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
address
object
Campos de address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
mailing_address
object
Campos de mailing_address
zip
string | nullcomo máximo 20 caracteres
city
string | nullcomo máximo 100 caracteres
street
string | nullcomo máximo 255 caracteres
tax_number
string | null

Solo empresas; null para una persona física.

company_registration_number
string | null

Solo empresas; null para una persona física.

representative_name
string | null

Solo empresas; null para una persona física.

representative_position
string | null

Solo empresas; null para una persona física.

main_activity
string | null

Actividad principal. Solo empresas; null para una persona física.

nationality_country
string | null
note
string | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/clients/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "name": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 512,
    "name": "Kovács Kft.",
    "is_person": true,
    "email": "info@example.hu",
    "phone": "string",
    "archived": true,
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "mailing_address": {
      "zip": "string",
      "city": "string",
      "street": "string"
    },
    "tax_number": "string",
    "company_registration_number": "string",
    "representative_name": "string",
    "representative_position": "string",
    "main_activity": "string",
    "nationality_country": "string",
    "note": "string"
  },
  "updated": true
}

Contactos

Listar personas de contacto

GET /api/agent/contacts

Lista las personas de contacto de los clientes, por orden alfabético de nombre. Pase client_id para listar las personas de contacto de un solo cliente. q busca en el nombre, el correo electrónico y el teléfono. Para las personas de contacto vinculadas a un expediente, use matters.contacts.

Ámbito
contacts:read
Permiso de Flowyer
contacts:read

Parámetros de consulta

client_id
integer>= 1

Filtra por las personas de contacto de un cliente.

Ejemplo: 512
q
stringcomo máximo 100 caracteres

Buscar en el nombre, el correo electrónico y el teléfono.

Ejemplo: "Anna"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/contacts?client_id=512&q=Anna&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 734,
      "name": "Dr. Kovács Anna",
      "organization": "string",
      "position": "ügyvezető",
      "note": "string",
      "date": "string",
      "emails": [
        {
          "email": "info@example.hu",
          "type": "string",
          "is_primary": true
        }
      ],
      "phones": [
        {
          "phone": "string",
          "type": "string",
          "is_primary": true
        }
      ],
      "addresses": [
        {
          "formatted": "string",
          "postal_code": "string",
          "city": "string",
          "street": "string",
          "country": "string",
          "type": "string",
          "is_primary": true
        }
      ],
      "client_ids": [
        0
      ],
      "matter_ids": [
        0
      ],
      "client_id": 512,
      "email": "info@example.hu",
      "phone": "string",
      "address": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener persona de contacto

GET /api/agent/contacts/{id}

Returns one contact person with all its recorded fields: name, organization, position, e-mails, phones, addresses and note, plus the clients and matters it is linked to.

Ámbito
contacts:read
Permiso de Flowyer
contacts:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la persona de contacto (de contacts.list o matters.contacts).

Ejemplo: 734

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/contacts/734' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 734,
    "name": "Dr. Kovács Anna",
    "organization": "string",
    "position": "ügyvezető",
    "note": "string",
    "date": "string",
    "emails": [
      {
        "email": "info@example.hu",
        "type": "string",
        "is_primary": true
      }
    ],
    "phones": [
      {
        "phone": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "addresses": [
      {
        "formatted": "string",
        "postal_code": "string",
        "city": "string",
        "street": "string",
        "country": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "client_ids": [
      0
    ],
    "matter_ids": [
      0
    ],
    "client_id": 512,
    "email": "info@example.hu",
    "phone": "string",
    "address": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear persona de contacto

POST /api/agent/contacts

Crea una persona de contacto. Puede vincularla a cualquier número de clientes (client_ids) y expedientes (matter_ids, cada uno visible para usted), o a ninguno. Admite varios correos electrónicos, teléfonos y direcciones (el primero es el principal). name es obligatorio; los campos antiguos únicos client_id/matter_id/email/phone/address siguen funcionando.

Ámbito
contacts:create
Permiso de Flowyer
contacts:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nombre de la persona de contacto. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Dr. Kovács Anna"
organization
string | nullcomo máximo 255 caracteres

Organización / empresa.

position
string | nullcomo máximo 255 caracteres

Función o cargo.

Ejemplo: "ügyvezető"
emails
string[] | nullcomo máximo 20 elementos

Direcciones de correo electrónico; la primera es la principal. Preferible al campo único email.

Ejemplo: [ "anna@kovacskft.hu" ]
email
string | nullcomo máximo 190 caracteres

Correo electrónico único antiguo (compatibilidad; es preferible emails[]).

Ejemplo: "anna@kovacskft.hu"
phones
string[] | nullcomo máximo 20 elementos

Números de teléfono; el primero es el principal. Preferible al campo único phone.

Ejemplo: [ "+36 1 234 5678" ]
phone
string | nullcomo máximo 64 caracteres

Teléfono único antiguo (compatibilidad; es preferible phones[]).

Ejemplo: "+36 1 234 5678"
addresses
string[] | nullcomo máximo 20 elementos

Direcciones postales (texto libre); la primera es la principal. Preferible al campo único address.

address
string | nullcomo máximo 2000 caracteres

Dirección única antigua (compatibilidad; es preferible addresses[]).

note
string | nullcomo máximo 4000 caracteres
client_ids
integer[] | nullcomo máximo 50 elementos

Ids de los clientes (mandantes) a los que se vincula el contacto. Cualquier número, o ninguno. Preferible al campo único client_id.

Ejemplo: [ 512 ]
client_id
integer | null>= 1

Cliente único antiguo que se vincula (compatibilidad; es preferible client_ids[]).

Ejemplo: 512
matter_ids
integer[] | nullcomo máximo 50 elementos

Ids de los expedientes a los que se asocia el contacto (cada uno debe ser visible para usted). Cualquier número, o ninguno. Preferible al campo único matter_id.

Ejemplo: [ 1234 ]
matter_id
integer | null>= 1

Expediente único antiguo que se asocia (compatibilidad; es preferible matter_ids[]).

Ejemplo: 1234
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/contacts' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "name": "Dr. Kovács Anna",
  "position": "ügyvezető",
  "emails": [
    "anna@kovacskft.hu"
  ],
  "email": "anna@kovacskft.hu",
  "phones": [
    "+36 1 234 5678"
  ],
  "phone": "+36 1 234 5678",
  "client_ids": [
    512
  ],
  "client_id": 512,
  "matter_ids": [
    1234
  ],
  "matter_id": 1234
}'

Ejemplos de respuesta

{
  "data": {
    "id": 734,
    "name": "Dr. Kovács Anna",
    "organization": "string",
    "position": "ügyvezető",
    "note": "string",
    "date": "string",
    "emails": [
      {
        "email": "info@example.hu",
        "type": "string",
        "is_primary": true
      }
    ],
    "phones": [
      {
        "phone": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "addresses": [
      {
        "formatted": "string",
        "postal_code": "string",
        "city": "string",
        "street": "string",
        "country": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "client_ids": [
      0
    ],
    "matter_ids": [
      0
    ],
    "client_id": 512,
    "email": "info@example.hu",
    "phone": "string",
    "address": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Modificar persona de contacto

PATCH /api/agent/contacts/{id}

Modifica un contacto: nombre, organización, cargo, nota y, como conjuntos de sustitución completa, los correos electrónicos, teléfonos, direcciones, vínculos con clientes (client_ids) y vínculos con expedientes (matter_ids). Pase expected_updated_at (409 en caso de conflicto). Cambiar el correo electrónico principal de un contacto del portal requiere una confirmación en dos pasos.

Ámbito
contacts:update
Permiso de Flowyer
contacts:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

name
string | nullal menos 1 caracterescomo máximo 255 caracteres

Nombre de la persona de contacto. No se pueden introducir "<" ni ">"; null mantiene el nombre actual.

Patrón: ^[^<>]*$
organization
string | nullcomo máximo 255 caracteres

Organización / empresa. null lo borra.

position
string | nullcomo máximo 255 caracteres

Función o cargo. null lo borra.

emails
string[] | nullcomo máximo 20 elementos

Sustituye TODOS los correos electrónicos; el primero es el principal. Preferible a email. Una matriz vacía borra todos los correos electrónicos. Cambiar el correo electrónico principal de un contacto con acceso al portal del cliente requiere una confirmación en dos pasos (revoca dicho acceso).

email
string | nullcomo máximo 190 caracteres

Correo electrónico principal (compatibilidad; es preferible emails[]). Sustituye el conjunto por este único valor; null borra todos los correos electrónicos. Cambiarlo en un contacto del portal es una acción en dos pasos: la primera llamada devuelve confirmation_required con un confirm_token; vuelva a llamar con el token para continuar.

phones
string[] | nullcomo máximo 20 elementos

Sustituye TODOS los números de teléfono; el primero es el principal. Preferible a phone. Una matriz vacía borra todos los teléfonos.

phone
string | nullcomo máximo 64 caracteres

Teléfono principal (compatibilidad; es preferible phones[]). null borra todos los teléfonos.

addresses
string[] | nullcomo máximo 20 elementos

Sustituye TODAS las direcciones postales (texto libre); la primera es la principal. Preferible a address. Una matriz vacía borra todas las direcciones.

address
string | nullcomo máximo 2000 caracteres

Dirección (principal) en texto libre (compatibilidad; es preferible addresses[]). null borra todas las direcciones.

note
string | nullcomo máximo 4000 caracteres

Nota en texto libre. null la borra.

client_ids
integer[] | nullcomo máximo 50 elementos

Sustituye TODOS los vínculos con clientes (mandantes). Una matriz vacía desvincula a todos los clientes. Omítalo para dejar los vínculos sin cambios.

matter_ids
integer[] | nullcomo máximo 50 elementos

Sustituye TODOS los vínculos con expedientes (cada uno debe ser visible para usted). Una matriz vacía desvincula todos los expedientes. Omítalo para dejarlos sin cambios.

confirm_token
string

Confirmación en dos pasos para un cambio de correo electrónico que revocaría el acceso de la persona de contacto al portal del cliente. Déjelo vacío en la primera llamada; para continuar, vuelva a llamar con los MISMOS argumentos más el token devuelto.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/contacts/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "name": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 734,
    "name": "Dr. Kovács Anna",
    "organization": "string",
    "position": "ügyvezető",
    "note": "string",
    "date": "string",
    "emails": [
      {
        "email": "info@example.hu",
        "type": "string",
        "is_primary": true
      }
    ],
    "phones": [
      {
        "phone": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "addresses": [
      {
        "formatted": "string",
        "postal_code": "string",
        "city": "string",
        "street": "string",
        "country": "string",
        "type": "string",
        "is_primary": true
      }
    ],
    "client_ids": [
      0
    ],
    "matter_ids": [
      0
    ],
    "client_id": 512,
    "email": "info@example.hu",
    "phone": "string",
    "address": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Listar personas de contacto del expediente

GET /api/agent/matters/{id}/contacts

Lists the contact persons attached to a matter (via cases_contacts), alphabetically by name. q searches name, e-mail and phone. A contact may be linked to the matter independently of its clients; see contacts.get for one contact.

Ámbito
contacts:read
Permiso de Flowyer
contacts:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Buscar en el nombre, el correo electrónico y el teléfono.

Ejemplo: "Anna"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de la persona de contacto.

Ejemplo: 734
name
string
Ejemplo: "Dr. Kovács Anna"
organization
string | null

Organisation / company, if recorded.

position
string | null

Role or position, if recorded.

Ejemplo: "ügyvezető"
note
string | null
date
string | null

Legacy free date field. Read-only.

emails
object[]

All e-mail addresses (structured, multi-value).

Campos de emails
email
string
type
string | null
is_primary
boolean
phones
object[]

All phone numbers (structured, multi-value).

Campos de phones
phone
string
type
string | null
is_primary
boolean
addresses
object[]

All postal addresses (structured, multi-value).

Campos de addresses
formatted
string | null
postal_code
string | null
city
string | null
street
string | null
country
string | null
type
string | null
is_primary
boolean
client_ids
integer[]

Ids of the clients this contact is linked to.

matter_ids
integer[]

Ids of the matters this contact is linked to.

client_id
integer | null

Primary/first client id (compat; see client_ids[]).

Ejemplo: 512
email
string | null

Primary e-mail (compat; see emails[]).

phone
string | null

Primary phone (compat; see phones[]).

address
string | null

Primary address (compat; see addresses[]).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/contacts?q=Anna&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 734,
      "name": "Dr. Kovács Anna",
      "organization": "string",
      "position": "ügyvezető",
      "note": "string",
      "date": "string",
      "emails": [
        {
          "email": "info@example.hu",
          "type": "string",
          "is_primary": true
        }
      ],
      "phones": [
        {
          "phone": "string",
          "type": "string",
          "is_primary": true
        }
      ],
      "addresses": [
        {
          "formatted": "string",
          "postal_code": "string",
          "city": "string",
          "street": "string",
          "country": "string",
          "type": "string",
          "is_primary": true
        }
      ],
      "client_ids": [
        0
      ],
      "matter_ids": [
        0
      ],
      "client_id": 512,
      "email": "info@example.hu",
      "phone": "string",
      "address": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Tareas

Listar tareas

GET /api/agent/tasks

Muestra las tareas (pendientes con fecha límite) que el usuario puede ver, empezando por la fecha límite más próxima. Por defecto, las tareas abiertas; permite filtrar por persona asignada, expediente, cliente o intervalo de fechas límite.

Ámbito
tasks:read
Permiso de Flowyer
tasks:read

Parámetros de consulta

status
string

open (predeterminado), closed o all.

Valores admitidos: "open" "closed" "all"
Valor por defecto: "open"
assigned_to_user_id
integer>= 1

Solo las tareas asignadas a este usuario (un id de usuario de colleagues.list).

matter_id
integer>= 1

Solo las tareas de este expediente.

client_id
integer>= 1

Solo las tareas sin expediente de este cliente.

deadline_from
string <date>

Fecha límite en esta fecha o posterior.

Ejemplo: "2026-11-01"
deadline_to
string <date>

Fecha límite en esta fecha o anterior.

Ejemplo: "2026-11-30"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/tasks?deadline_from=2026-11-01&deadline_to=2026-11-30&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 9876,
      "subject": "Submit the statement of defence",
      "description": "string",
      "deadline": "2026-11-15",
      "priority": 2,
      "status": "open",
      "closed_at": "2026-10-30",
      "matter": {
        "id": 1234,
        "case_number": "string"
      },
      "client": {
        "id": 1234,
        "name": "string"
      },
      "assigned_to_user_id": 1234,
      "assigned_to": "string",
      "created_by_user_id": 1234,
      "created_by": "string",
      "flag_id": 1234,
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener tarea

GET /api/agent/tasks/{id}

Devuelve una tarea. Responde 404 si la tarea no existe o el usuario no puede verla.

Ámbito
tasks:read
Permiso de Flowyer
tasks:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la tarea.

Ejemplo: 9876

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/tasks/9876' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "subject": "Submit the statement of defence",
    "description": "string",
    "deadline": "2026-11-15",
    "priority": 2,
    "status": "open",
    "closed_at": "2026-10-30",
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "assigned_to_user_id": 1234,
    "assigned_to": "string",
    "created_by_user_id": 1234,
    "created_by": "string",
    "flag_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear tarea

POST /api/agent/tasks

Crea una tarea (pendiente con fecha límite), ya sea en un expediente (matter_id, visible y no archivado) o sin expediente, opcionalmente para un cliente (client_id). La persona asignada es, por defecto, el usuario de la clave, y recibe una notificación si es otra persona.

Ámbito
tasks:create
Permiso de Flowyer
tasks:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

subjectobligatorio
stringal menos 2 caracterescomo máximo 1000 caracteres

Lo que hay que hacer. Texto sin formato.

Ejemplo: "Submit the statement of defence"
deadlineobligatorio
string <date>

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
matter_id
integer | null>= 1

Expediente al que pertenece la tarea. Omítalo para una tarea sin expediente.

Ejemplo: 1234
client_id
integer | null>= 1

Cliente de una tarea sin expediente. No se admite junto con matter_id (la tarea de un expediente toma el cliente del expediente).

assigned_to_user_id
integer | null>= 1

Miembro del equipo responsable de la tarea: un id de usuario de colleagues.list (busque allí el nombre dictado). Valor predeterminado: el usuario titular de la clave.

priority
integer>= 1<= 3

1 = baja, 2 = media (predeterminado), 3 = alta.

Valor por defecto: 2
description
string | nullcomo máximo 10000 caracteres

Detalles más extensos, texto sin formato.

flag_id
integer | null>= 1

Id de un indicador de tarea del despacho (etiqueta).

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/tasks' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "subject": "Submit the statement of defence",
  "deadline": "2026-11-15",
  "matter_id": 1234
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "subject": "Submit the statement of defence",
    "description": "string",
    "deadline": "2026-11-15",
    "priority": 2,
    "status": "open",
    "closed_at": "2026-10-30",
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "assigned_to_user_id": 1234,
    "assigned_to": "string",
    "created_by_user_id": 1234,
    "created_by": "string",
    "flag_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Actualizar tarea

PATCH /api/agent/tasks/{id}

Modifica una tarea: asunto, fecha límite, descripción, prioridad, indicador, persona asignada o el expediente al que pertenece. Al moverla a un expediente, se vuelve a derivar el vínculo con el tribunal y se descarta el cliente directo; client_id solo es para una tarea sin expediente. Pase expected_updated_at; un cambio en conflicto responde 409.

Ámbito
tasks:update
Permiso de Flowyer
tasks:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

subject
string | nullal menos 1 caracteres

Lo que hay que hacer. Texto sin formato, como máximo 1000 caracteres como valor NUEVO; un asunto almacenado más largo puede reenviarse sin cambios. null conserva el asunto actual.

deadline
string <date> | null

Fecha límite, YYYY-MM-DD. null conserva la fecha límite actual (la fecha límite no se puede borrar).

matter_id
integer | null>= 1

Mover la tarea a este expediente (debe ser visible y no estar archivado), o null para desvincularla. Enviar el expediente actual de la tarea no cambia nada.

client_id
integer | null>= 1

Cliente de una tarea sin expediente. Solo se admite si la tarea no tiene expediente.

assigned_to_user_id
integer | null>= 0

Nueva persona asignada: el id de usuario de un miembro activo del equipo de colleagues.list. Recibe una notificación si no es usted. Enviar la actual (o null / 0, que es lo que devuelve una tarea sin persona asignada) no cambia nada.

priority
integer>= 1<= 3

1 = baja, 2 = media, 3 = alta. Omítalo para conservar la prioridad actual (también si la tarea se devuelve con priority null); null se rechaza.

description
string | null

Detalles más extensos, texto sin formato, como máximo 10000 caracteres como valor NUEVO; una descripción almacenada más larga puede reenviarse sin cambios.

flag_id
integer | null>= 1

Id de un indicador de tarea del despacho (etiqueta), o null para quitarlo.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/tasks/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "subject": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "subject": "Submit the statement of defence",
    "description": "string",
    "deadline": "2026-11-15",
    "priority": 2,
    "status": "open",
    "closed_at": "2026-10-30",
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "assigned_to_user_id": 1234,
    "assigned_to": "string",
    "created_by_user_id": 1234,
    "created_by": "string",
    "flag_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Cerrar tarea

POST /api/agent/tasks/{id}/close

Cierra una tarea. Si se indican minutos, también registra horas (requiere workhours:create y un expediente: el de la propia tarea, o matter_id en una tarea sin expediente); los minutos facturables se recortan al límite de horas del despacho. Un segundo cierre responde 409, de modo que un reintento nunca registra una segunda entrada.

Ámbito
tasks:update
Permiso de Flowyer
tasks:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id de la tarea.

Ejemplo: 9876

Cuerpo de la solicitud application/json

minutes_spent
integer | null>= 0<= 100000

Tiempo dedicado, en minutos. Para registrar cualquier tiempo se necesitan el ámbito workhours:create y un expediente.

minutes_invoiceable
integer | null>= 0<= 100000

Minutos facturables; se recortan al límite de horas del despacho.

minutes_normative
integer | null>= 0<= 100000

Minutos normativos; se almacenan tal cual, sin límite.

matter_id
integer | null>= 1

Asignar este expediente a una tarea SIN EXPEDIENTE al cerrarla (y así permitir registrar horas). No se admite si la tarea ya tiene expediente.

client_id
integer | null>= 1

Cliente directo (Megbízó) de una tarea sin expediente que se cierra sin expediente.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
subject
string
Ejemplo: "Submit the statement of defence"
description
string | null
deadline
string <date> | null

Fecha límite, YYYY-MM-DD.

Ejemplo: "2026-11-15"
priority
integer | null

1 = baja, 2 = media, 3 = alta; null = sin indicar (una tarea antigua sin prioridad).

Ejemplo: 2
status
string
Valores admitidos: "open" "closed"
closed_at
string <date> | null

Día en que se cerró la tarea, YYYY-MM-DD. Flowyer solo registra la fecha, sin hora.

matter
object | null

El expediente al que pertenece la tarea, si lo hay.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente: el primer cliente del expediente o, si la tarea no tiene expediente, el cliente propio de la tarea.

Campos de client
id
integer
name
string
assigned_to_user_id
integer | null
assigned_to
string | null
created_by_user_id
integer | null
created_by
string | null
flag_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created_via_api
object | null
Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
booked_workhour
object | null

El registro de horas creado al cerrar, o null si no se indicó tiempo.

Campos de booked_workhour
id
integer>= 1
minutes
integer
minutes_invoiceable
integer
minutes_normative
integer
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/tasks/9876/close' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "subject": "Submit the statement of defence",
    "description": "string",
    "deadline": "2026-11-15",
    "priority": 2,
    "status": "open",
    "closed_at": "2026-10-30",
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "assigned_to_user_id": 1234,
    "assigned_to": "string",
    "created_by_user_id": 1234,
    "created_by": "string",
    "flag_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "booked_workhour": {
      "id": 1234,
      "minutes": 0,
      "minutes_invoiceable": 0,
      "minutes_normative": 0
    }
  }
}

Horas

Listar registros de horas

GET /api/agent/workhours

Muestra los registros de horas de los expedientes que el usuario puede ver, del más reciente al más antiguo. Por defecto, solo los registros vigentes (aún no facturados); pase status=invoiced para los facturados (solo lectura, id null) o all para ambos. Permite filtrar por expediente, miembro del equipo responsable o intervalo de fechas. Los registros con excluded: true quedan fuera de los totales facturables.

Ámbito
workhours:read
Permiso de Flowyer
workhours:read

Parámetros de consulta

matter_id
integer>= 1

Solo los registros de este expediente.

Ejemplo: 1234
responsible_user_id
integer>= 1

Solo los registros imputados a este miembro del equipo (un id de usuario de colleagues.list).

date_from
string <date>

Solo los registros de esta fecha o posteriores (YYYY-MM-DD).

date_to
string <date>

Solo los registros de esta fecha o anteriores (YYYY-MM-DD).

external_id
stringcomo máximo 64 caracteres

Solo el registro que lleva este identificador externo (p. ej., el id de un registro de tiempo de Clockify). Así se localiza el registro de Flowyer que se debe volver a sincronizar: filtre por él (use status=all si el registro puede estar ya facturado) y actualice el resultado por su id.

status
string

Qué registros se muestran: "live" (predeterminado, aún no facturados), "invoiced" (facturados, solo lectura, del archivo: id es null e invoiced es true) o "all".

Valores admitidos: "live" "invoiced" "all"
Valor por defecto: "live"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer | null

Id del registro de horas; null para un registro facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que se imputa el registro.

date
string <date> | null
activity
string | null

Lo que se hizo (texto sin formato).

minutes
integer | null

Minutos dedicados.

minutes_invoiceable
integer | null

Minutos facturables tras aplicar el límite de horas del despacho (pueden ser menos de los solicitados). Solo cuentan para la facturación mientras excluded sea false.

minutes_normative
integer | null

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null

Miembro del equipo al que se imputa el tiempo.

responsible
string | null
recorded_by_user_id
integer | null

Quién creó el registro.

locked
boolean

True si el registro es de solo lectura a través de la API (un registro facturado siempre está bloqueado).

excluded
boolean

True si un miembro del equipo excluyó el registro del resumen del expediente: no se factura y sus minutos quedan fuera de los totales facturables.

external_id
string | null

Un identificador externo estable que se establece una sola vez al crear (p. ej., el id de un registro de tiempo de Clockify), o null para un registro creado en Flowyer. Para volver a sincronizar un registro de origen modificado, localice el registro de Flowyer filtrando workhours.list por este valor y actualícelo por su id.

invoiced
boolean

True si el registro se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el registro (solo para un registro facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un registro facturado.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/workhours?matter_id=1234&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "matter_id": 1234,
      "date": "2026-10-30",
      "activity": "string",
      "minutes": 0,
      "minutes_invoiceable": 0,
      "minutes_normative": 0,
      "responsible_user_id": 1234,
      "responsible": "string",
      "recorded_by_user_id": 1234,
      "locked": true,
      "excluded": true,
      "external_id": "string",
      "invoiced": true,
      "invoiced_at": "2026-10-30T09:15:00+01:00",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener registro de horas

GET /api/agent/workhours/{id}

Devuelve un registro de horas vigente por su id, si su expediente es visible para el usuario.

Ámbito
workhours:read
Permiso de Flowyer
workhours:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro de horas.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer | null

Id del registro de horas; null para un registro facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que se imputa el registro.

date
string <date> | null
activity
string | null

Lo que se hizo (texto sin formato).

minutes
integer | null

Minutos dedicados.

minutes_invoiceable
integer | null

Minutos facturables tras aplicar el límite de horas del despacho (pueden ser menos de los solicitados). Solo cuentan para la facturación mientras excluded sea false.

minutes_normative
integer | null

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null

Miembro del equipo al que se imputa el tiempo.

responsible
string | null
recorded_by_user_id
integer | null

Quién creó el registro.

locked
boolean

True si el registro es de solo lectura a través de la API (un registro facturado siempre está bloqueado).

excluded
boolean

True si un miembro del equipo excluyó el registro del resumen del expediente: no se factura y sus minutos quedan fuera de los totales facturables.

external_id
string | null

Un identificador externo estable que se establece una sola vez al crear (p. ej., el id de un registro de tiempo de Clockify), o null para un registro creado en Flowyer. Para volver a sincronizar un registro de origen modificado, localice el registro de Flowyer filtrando workhours.list por este valor y actualícelo por su id.

invoiced
boolean

True si el registro se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el registro (solo para un registro facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un registro facturado.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/workhours/1234' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "minutes": 0,
    "minutes_invoiceable": 0,
    "minutes_normative": 0,
    "responsible_user_id": 1234,
    "responsible": "string",
    "recorded_by_user_id": 1234,
    "locked": true,
    "excluded": true,
    "external_id": "string",
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  }
}

Registrar horas

POST /api/agent/workhours

Registra horas en un expediente: fecha, actividad, minutos dedicados y minutos facturables. Si se omiten los minutos facturables, el registro no es facturable: envíe minutes_invoiceable para el trabajo facturable. Se recortan al límite de horas del despacho. El miembro del equipo responsable es, por defecto, el usuario de la clave; en caso contrario, recibe una notificación.

Ámbito
workhours:create
Permiso de Flowyer
workhours:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

matter_idobligatorio
integer>= 1

Expediente al que se imputa el tiempo (debe ser visible).

Ejemplo: 1234
dateobligatorio
string <date>

Fecha del trabajo, YYYY-MM-DD.

Ejemplo: "2026-10-30"
subject
stringal menos 2 caracterescomo máximo 1000 caracteres

Lo que se hizo; la lectura lo devuelve como activity y aquí se admite cualquiera de los dos nombres (uno de ellos es obligatorio). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Drafting the statement of claim"
activity
stringal menos 2 caracterescomo máximo 1000 caracteres

El mismo campo que subject, con el nombre que se usa en lectura. Envíe uno de los dos.

Patrón: ^[^<>]*$
minutes
integer | null>= 0<= 100000

Minutos realmente dedicados.

Ejemplo: 90
minutes_invoiceable
integer | null>= 0<= 100000

Minutos facturables solicitados. Omitidos o null = no facturable (el registro no factura nada; no se derivan de minutes): para el trabajo facturable, envíelos de forma explícita, normalmente iguales a minutes. El límite de horas del despacho puede reducir el valor almacenado. Solo cuentan para la facturación mientras el registro no esté excluido del resumen.

Ejemplo: 60
minutes_normative
integer | null>= 0<= 100000

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null>= 1

Miembro del equipo al que se imputa el tiempo: un id de usuario de colleagues.list (busque allí el nombre dictado). Valor predeterminado: el usuario titular de la clave.

external_id
string | nullcomo máximo 64 caracteres

Un identificador externo estable del sistema desde el que sincroniza (p. ej., el id de un registro de tiempo de Clockify). Almacénelo para que un cambio posterior en ese sistema se vuelva a sincronizar con este mismo registro: el reenvío del mismo external_id se rechaza con 409 (no crea un duplicado), y la lectura lo devuelve. Solo letras, dígitos y _.:-, como máximo 64 caracteres. Omítalo para un registro normal.

Patrón: ^[A-Za-z0-9_.:-]{1,64}$
Ejemplo: "65a1f3c9e4b0a2d1f8c7b6a5"
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer | null

Id del registro de horas; null para un registro facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que se imputa el registro.

date
string <date> | null
activity
string | null

Lo que se hizo (texto sin formato).

minutes
integer | null

Minutos dedicados.

minutes_invoiceable
integer | null

Minutos facturables tras aplicar el límite de horas del despacho (pueden ser menos de los solicitados). Solo cuentan para la facturación mientras excluded sea false.

minutes_normative
integer | null

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null

Miembro del equipo al que se imputa el tiempo.

responsible
string | null
recorded_by_user_id
integer | null

Quién creó el registro.

locked
boolean

True si el registro es de solo lectura a través de la API (un registro facturado siempre está bloqueado).

excluded
boolean

True si un miembro del equipo excluyó el registro del resumen del expediente: no se factura y sus minutos quedan fuera de los totales facturables.

external_id
string | null

Un identificador externo estable que se establece una sola vez al crear (p. ej., el id de un registro de tiempo de Clockify), o null para un registro creado en Flowyer. Para volver a sincronizar un registro de origen modificado, localice el registro de Flowyer filtrando workhours.list por este valor y actualícelo por su id.

invoiced
boolean

True si el registro se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el registro (solo para un registro facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un registro facturado.

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer | null

Id del registro de horas; null para un registro facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que se imputa el registro.

date
string <date> | null
activity
string | null

Lo que se hizo (texto sin formato).

minutes
integer | null

Minutos dedicados.

minutes_invoiceable
integer | null

Minutos facturables tras aplicar el límite de horas del despacho (pueden ser menos de los solicitados). Solo cuentan para la facturación mientras excluded sea false.

minutes_normative
integer | null

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null

Miembro del equipo al que se imputa el tiempo.

responsible
string | null
recorded_by_user_id
integer | null

Quién creó el registro.

locked
boolean

True si el registro es de solo lectura a través de la API (un registro facturado siempre está bloqueado).

excluded
boolean

True si un miembro del equipo excluyó el registro del resumen del expediente: no se factura y sus minutos quedan fuera de los totales facturables.

external_id
string | null

Un identificador externo estable que se establece una sola vez al crear (p. ej., el id de un registro de tiempo de Clockify), o null para un registro creado en Flowyer. Para volver a sincronizar un registro de origen modificado, localice el registro de Flowyer filtrando workhours.list por este valor y actualícelo por su id.

invoiced
boolean

True si el registro se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el registro (solo para un registro facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un registro facturado.

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

Ya existe un registro de horas con el mismo external_id (record_conflict): details.reason es external_id_exists y details.record_id es el id del registro existente, así que actualice ese registro en lugar de volver a crearlo; o external_id_invoiced si el registro coincidente ya se ha facturado y es de solo lectura. La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando en este momento una solicitud idéntica (duplicate_in_progress).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/workhours' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "matter_id": 1234,
  "date": "2026-10-30",
  "subject": "Drafting the statement of claim",
  "minutes": 90,
  "minutes_invoiceable": 60,
  "external_id": "65a1f3c9e4b0a2d1f8c7b6a5"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "minutes": 0,
    "minutes_invoiceable": 0,
    "minutes_normative": 0,
    "responsible_user_id": 1234,
    "responsible": "string",
    "recorded_by_user_id": 1234,
    "locked": true,
    "excluded": true,
    "external_id": "string",
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Actualizar registro de horas

PATCH /api/agent/workhours/{id}

Modifica un registro de horas vigente: fecha, actividad (subject o activity), minutos, minutos facturables (un número modificado se recorta al límite de horas; uno reenviado sin cambios se conserva) y el miembro del equipo responsable. Un registro bloqueado o facturado no se puede modificar (409). Pase expected_updated_at; un conflicto responde 409.

Ámbito
workhours:update
Permiso de Flowyer
workhours:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

date
string <date> | null

Fecha del trabajo, YYYY-MM-DD. null conserva la fecha actual.

subject
string | nullal menos 1 caracteres

Lo que se hizo, el valor que la lectura devuelve como activity (se admite cualquiera de los dos nombres; null en uno de ellos equivale a "not given" y solo se rechazan dos textos distintos). Texto sin formato, como máximo 1000 caracteres como valor NUEVO; tampoco se pueden introducir "<" ni ">", pero un texto almacenado más largo o que los contenga puede reenviarse sin cambios. null conserva el texto actual.

activity
string | nullal menos 1 caracteres

El mismo campo que subject, con el nombre que se usa en lectura. Envíe uno de los dos (null en el otro es válido).

minutes
integer | null>= 0<= 100000

Minutos realmente dedicados; null los borra.

minutes_invoiceable
integer | null>= 0<= 100000

Minutos facturables solicitados. Un número distinto del almacenado se recorta a lo que queda del límite de horas; reenviar el valor que devolvió la lectura lo conserva tal como está registrado (no se vuelve a recortar). null los borra. Solo cuentan para la facturación mientras el registro no esté excluido del resumen (excluded es false).

minutes_normative
integer | null>= 0<= 100000

Minutos normativos (nunca se limitan); null los borra.

responsible_user_id
integer | null>= 0

Nuevo miembro del equipo responsable: el id de usuario de un miembro activo del equipo de colleagues.list; recibe una notificación si no es usted. Enviar el actual (o null / 0, que es lo que devuelve un registro sin responsable) no cambia nada.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer | null

Id del registro de horas; null para un registro facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que se imputa el registro.

date
string <date> | null
activity
string | null

Lo que se hizo (texto sin formato).

minutes
integer | null

Minutos dedicados.

minutes_invoiceable
integer | null

Minutos facturables tras aplicar el límite de horas del despacho (pueden ser menos de los solicitados). Solo cuentan para la facturación mientras excluded sea false.

minutes_normative
integer | null

Minutos normativos (informativos; nunca se limitan).

responsible_user_id
integer | null

Miembro del equipo al que se imputa el tiempo.

responsible
string | null
recorded_by_user_id
integer | null

Quién creó el registro.

locked
boolean

True si el registro es de solo lectura a través de la API (un registro facturado siempre está bloqueado).

excluded
boolean

True si un miembro del equipo excluyó el registro del resumen del expediente: no se factura y sus minutos quedan fuera de los totales facturables.

external_id
string | null

Un identificador externo estable que se establece una sola vez al crear (p. ej., el id de un registro de tiempo de Clockify), o null para un registro creado en Flowyer. Para volver a sincronizar un registro de origen modificado, localice el registro de Flowyer filtrando workhours.list por este valor y actualícelo por su id.

invoiced
boolean

True si el registro se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el registro (solo para un registro facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un registro facturado.

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at), o se ha facturado / bloqueado y ya no se puede modificar mediante la API (record_locked; haga el cambio en Flowyer).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/workhours/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "date": "2026-10-30"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "minutes": 0,
    "minutes_invoiceable": 0,
    "minutes_normative": 0,
    "responsible_user_id": 1234,
    "responsible": "string",
    "recorded_by_user_id": 1234,
    "locked": true,
    "excluded": true,
    "external_id": "string",
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Gastos

Listar gastos

GET /api/agent/costs

Muestra los gastos de los expedientes que el usuario puede ver, del más reciente al más antiguo. Por defecto, solo los gastos vigentes (aún no facturados); pase status=invoiced para los facturados (solo lectura, id null, invoice_id informado) o all para ambos. Permite filtrar por expediente, miembro del equipo responsable o intervalo de fechas. Importes netos; excluded: true queda fuera del resumen.

Ámbito
costs:read
Permiso de Flowyer
cases:read, summary:read

Parámetros de consulta

matter_id
integer>= 1

Solo los gastos de este expediente.

Ejemplo: 1234
responsible_user_id
integer>= 1

Solo los gastos registrados para este miembro del equipo (un id de usuario de colleagues.list).

date_from
string <date>

Solo los gastos de esta fecha o posteriores (YYYY-MM-DD).

date_to
string <date>

Solo los gastos de esta fecha o anteriores (YYYY-MM-DD).

status
string

Qué gastos se muestran: "live" (predeterminado, aún no facturados), "invoiced" (facturados, solo lectura, del archivo: id es null e invoiced es true) o "all".

Valores admitidos: "live" "invoiced" "all"
Valor por defecto: "live"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer | null

Id del gasto; null para un gasto facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que pertenece el gasto.

date
string <date> | null
activity
string | null

Descripción del gasto (texto sin formato).

cost
number | null

Importe neto del gasto (sin IVA).

cost_invoiceable
number | null

Importe neto que se repercute al cliente. Solo cuenta para la facturación mientras excluded sea false.

currency_id
integer | null

Id de la moneda (lista de monedas de Flowyer).

currency
string | null

Código ISO de la moneda, p. ej. HUF, EUR.

responsible_user_id
integer | null
responsible
string | null
excluded
boolean

True cuando un miembro del equipo ha excluido el gasto del resumen del expediente: no se factura y queda fuera de los totales facturables.

locked
boolean

True cuando el gasto lo gestiona Flowyer (reflejado desde una factura recibida o un recargo sobre suplidos) y no se puede modificar mediante la API (costs.update responde 409 record_locked; details.reason indica cuál de los dos).

approved_for_billing
boolean

True cuando un miembro del equipo ha aprobado el gasto para su facturación en el resumen del expediente. Sigue siendo editable mediante la API (como en la web) y la aprobación NO se vuelve a solicitar después: indíquelo antes de cambiar el importe de un gasto aprobado.

invoiced
boolean

True si el gasto se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el gasto (solo para un gasto facturado).

invoice_id
integer | null

La factura en la que se facturó este gasto, si se conoce (solo para un gasto facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un gasto facturado.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/costs?matter_id=1234&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "matter_id": 1234,
      "date": "2026-10-30",
      "activity": "string",
      "cost": 0,
      "cost_invoiceable": 0,
      "currency_id": 1234,
      "currency": "string",
      "responsible_user_id": 1234,
      "responsible": "string",
      "excluded": true,
      "locked": true,
      "approved_for_billing": true,
      "invoiced": true,
      "invoiced_at": "2026-10-30T09:15:00+01:00",
      "invoice_id": 1234,
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener gasto

GET /api/agent/costs/{id}

Devuelve un gasto vigente por id, si su expediente es visible para el usuario. Los importes son netos.

Ámbito
costs:read
Permiso de Flowyer
cases:read, summary:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del gasto.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer | null

Id del gasto; null para un gasto facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que pertenece el gasto.

date
string <date> | null
activity
string | null

Descripción del gasto (texto sin formato).

cost
number | null

Importe neto del gasto (sin IVA).

cost_invoiceable
number | null

Importe neto que se repercute al cliente. Solo cuenta para la facturación mientras excluded sea false.

currency_id
integer | null

Id de la moneda (lista de monedas de Flowyer).

currency
string | null

Código ISO de la moneda, p. ej. HUF, EUR.

responsible_user_id
integer | null
responsible
string | null
excluded
boolean

True cuando un miembro del equipo ha excluido el gasto del resumen del expediente: no se factura y queda fuera de los totales facturables.

locked
boolean

True cuando el gasto lo gestiona Flowyer (reflejado desde una factura recibida o un recargo sobre suplidos) y no se puede modificar mediante la API (costs.update responde 409 record_locked; details.reason indica cuál de los dos).

approved_for_billing
boolean

True cuando un miembro del equipo ha aprobado el gasto para su facturación en el resumen del expediente. Sigue siendo editable mediante la API (como en la web) y la aprobación NO se vuelve a solicitar después: indíquelo antes de cambiar el importe de un gasto aprobado.

invoiced
boolean

True si el gasto se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el gasto (solo para un gasto facturado).

invoice_id
integer | null

La factura en la que se facturó este gasto, si se conoce (solo para un gasto facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un gasto facturado.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/costs/1234' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "cost": 0,
    "cost_invoiceable": 0,
    "currency_id": 1234,
    "currency": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "excluded": true,
    "locked": true,
    "approved_for_billing": true,
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "invoice_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  }
}

Registrar gasto

POST /api/agent/costs

Registra un gasto (suplido) en un expediente: fecha, texto (subject, que se lee como activity), importe neto, importe neto facturado al cliente y moneda (predeterminada: la moneda del despacho). Los importes son netos (sin IVA). El miembro del equipo responsable es, por defecto, el usuario de la clave; en caso contrario, recibe una notificación.

Ámbito
costs:create
Permiso de Flowyer
cases:create, summary:read

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

matter_idobligatorio
integer>= 1

Expediente al que pertenece el gasto (debe ser visible).

Ejemplo: 1234
dateobligatorio
string <date>

Fecha del gasto, YYYY-MM-DD.

Ejemplo: "2026-10-30"
subject
stringal menos 2 caracterescomo máximo 1000 caracteres

Descripción del gasto; en lectura se devuelve como activity y aquí se acepta cualquiera de los dos nombres (uno de ellos es obligatorio). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Court filing fee"
activity
stringal menos 2 caracterescomo máximo 1000 caracteres

El mismo campo que subject, con el nombre que se usa en lectura. Envíe uno de los dos.

Patrón: ^[^<>]*$
costobligatorio
integer>= 0<= 2147483647

Importe neto del gasto (sin IVA), un número entero en la unidad principal de la moneda (no se almacenan céntimos).

Ejemplo: 15000
cost_invoiceable
integer | null>= 0<= 2147483647

Importe neto que se repercute al cliente, un número entero (omítalo si no se factura). Solo cuenta para la facturación mientras el gasto no esté excluido del resumen.

Ejemplo: 15000
currency_id
integer | null>= 1

Id de la moneda de la lista de monedas de Flowyer (no un código ISO). Omítalo para usar la moneda del despacho (GET /me office.currency_id / office.currency); un id desconocido responde 422 con los ids y códigos admitidos en details.allowed.

responsible_user_id
integer | null>= 1

Miembro del equipo responsable: un id de usuario de colleagues.list (busque allí un nombre dictado). Valor predeterminado: el usuario de la clave.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer | null

Id del gasto; null para un gasto facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que pertenece el gasto.

date
string <date> | null
activity
string | null

Descripción del gasto (texto sin formato).

cost
number | null

Importe neto del gasto (sin IVA).

cost_invoiceable
number | null

Importe neto que se repercute al cliente. Solo cuenta para la facturación mientras excluded sea false.

currency_id
integer | null

Id de la moneda (lista de monedas de Flowyer).

currency
string | null

Código ISO de la moneda, p. ej. HUF, EUR.

responsible_user_id
integer | null
responsible
string | null
excluded
boolean

True cuando un miembro del equipo ha excluido el gasto del resumen del expediente: no se factura y queda fuera de los totales facturables.

locked
boolean

True cuando el gasto lo gestiona Flowyer (reflejado desde una factura recibida o un recargo sobre suplidos) y no se puede modificar mediante la API (costs.update responde 409 record_locked; details.reason indica cuál de los dos).

approved_for_billing
boolean

True cuando un miembro del equipo ha aprobado el gasto para su facturación en el resumen del expediente. Sigue siendo editable mediante la API (como en la web) y la aprobación NO se vuelve a solicitar después: indíquelo antes de cambiar el importe de un gasto aprobado.

invoiced
boolean

True si el gasto se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el gasto (solo para un gasto facturado).

invoice_id
integer | null

La factura en la que se facturó este gasto, si se conoce (solo para un gasto facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un gasto facturado.

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer | null

Id del gasto; null para un gasto facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que pertenece el gasto.

date
string <date> | null
activity
string | null

Descripción del gasto (texto sin formato).

cost
number | null

Importe neto del gasto (sin IVA).

cost_invoiceable
number | null

Importe neto que se repercute al cliente. Solo cuenta para la facturación mientras excluded sea false.

currency_id
integer | null

Id de la moneda (lista de monedas de Flowyer).

currency
string | null

Código ISO de la moneda, p. ej. HUF, EUR.

responsible_user_id
integer | null
responsible
string | null
excluded
boolean

True cuando un miembro del equipo ha excluido el gasto del resumen del expediente: no se factura y queda fuera de los totales facturables.

locked
boolean

True cuando el gasto lo gestiona Flowyer (reflejado desde una factura recibida o un recargo sobre suplidos) y no se puede modificar mediante la API (costs.update responde 409 record_locked; details.reason indica cuál de los dos).

approved_for_billing
boolean

True cuando un miembro del equipo ha aprobado el gasto para su facturación en el resumen del expediente. Sigue siendo editable mediante la API (como en la web) y la aprobación NO se vuelve a solicitar después: indíquelo antes de cambiar el importe de un gasto aprobado.

invoiced
boolean

True si el gasto se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el gasto (solo para un gasto facturado).

invoice_id
integer | null

La factura en la que se facturó este gasto, si se conoce (solo para un gasto facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un gasto facturado.

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/costs' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "matter_id": 1234,
  "date": "2026-10-30",
  "subject": "Court filing fee",
  "cost": 15000,
  "cost_invoiceable": 15000
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "cost": 0,
    "cost_invoiceable": 0,
    "currency_id": 1234,
    "currency": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "excluded": true,
    "locked": true,
    "approved_for_billing": true,
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "invoice_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Modificar gasto

PATCH /api/agent/costs/{id}

Modifica un gasto vigente: texto (subject, que se lee como activity), fecha, importes netos, moneda y miembro del equipo responsable. Un gasto marcado con locked: true no se puede modificar (409 record_locked, details.reason). Pase expected_updated_at; un cambio en conflicto responde 409.

Ámbito
costs:update
Permiso de Flowyer
cases:modify, summary:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

date
string <date> | null

Fecha del gasto, YYYY-MM-DD. null mantiene la fecha actual.

subject
string | nullal menos 1 caracteres

Descripción del gasto, el valor que en lectura se devuelve como activity (se acepta cualquiera de los dos nombres; null en uno de ellos equivale a "no indicado" y solo se rechazan dos textos distintos). Texto sin formato, como máximo 1000 caracteres como valor NUEVO; tampoco se pueden introducir "<" ni ">", pero un texto almacenado más largo o que los contenga se puede devolver sin cambios. null mantiene el texto actual.

activity
string | nullal menos 1 caracteres

El mismo campo que subject, con el nombre que se usa en lectura. Envíe uno de los dos (null en el otro es válido).

cost
integer | null>= 0<= 2147483647

Importe neto del gasto (sin IVA), un número entero en la unidad principal de la moneda (no se almacenan céntimos). null borra el importe.

cost_invoiceable
integer | null>= 0<= 2147483647

Importe neto que se repercute al cliente, un número entero; null lo borra. Solo cuenta para la facturación mientras el gasto no esté excluido del resumen (excluded es false).

currency_id
integer | null>= 0

Id de la moneda de la lista de monedas de Flowyer (no un código ISO; la moneda del despacho es GET /me office.currency_id). Un id desconocido responde 422 con los ids y códigos admitidos en details.allowed. null, o el 0 que devuelve en lectura un gasto antiguo sin moneda definida, mantiene la moneda actual.

responsible_user_id
integer | null>= 0

Nuevo miembro del equipo responsable: el id de usuario de un miembro activo del equipo de colleagues.list. Enviar el actual, o null / 0 (lo que devuelve en lectura un gasto sin responsable), no cambia nada.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer | null

Id del gasto; null para un gasto facturado (solo lectura, no tiene id actualizable).

matter_id
integer | null

Expediente al que pertenece el gasto.

date
string <date> | null
activity
string | null

Descripción del gasto (texto sin formato).

cost
number | null

Importe neto del gasto (sin IVA).

cost_invoiceable
number | null

Importe neto que se repercute al cliente. Solo cuenta para la facturación mientras excluded sea false.

currency_id
integer | null

Id de la moneda (lista de monedas de Flowyer).

currency
string | null

Código ISO de la moneda, p. ej. HUF, EUR.

responsible_user_id
integer | null
responsible
string | null
excluded
boolean

True cuando un miembro del equipo ha excluido el gasto del resumen del expediente: no se factura y queda fuera de los totales facturables.

locked
boolean

True cuando el gasto lo gestiona Flowyer (reflejado desde una factura recibida o un recargo sobre suplidos) y no se puede modificar mediante la API (costs.update responde 409 record_locked; details.reason indica cuál de los dos).

approved_for_billing
boolean

True cuando un miembro del equipo ha aprobado el gasto para su facturación en el resumen del expediente. Sigue siendo editable mediante la API (como en la web) y la aprobación NO se vuelve a solicitar después: indíquelo antes de cambiar el importe de un gasto aprobado.

invoiced
boolean

True si el gasto se ha facturado: es de solo lectura, se encuentra en el archivo de facturación y su id es null. Solo se devuelve cuando status es "invoiced" o "all".

invoiced_at
string <date-time> | null

Momento en que se facturó el gasto (solo para un gasto facturado).

invoice_id
integer | null

La factura en la que se facturó este gasto, si se conoce (solo para un gasto facturado).

created_at
string <date-time> | null
updated_at
string <date-time> | null

Reenvíelo como expected_updated_at al actualizar. Null para un gasto facturado.

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at), o se ha facturado / bloqueado y ya no se puede modificar mediante la API (record_locked; haga el cambio en Flowyer).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/costs/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "date": "2026-10-30"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter_id": 1234,
    "date": "2026-10-30",
    "activity": "string",
    "cost": 0,
    "cost_invoiceable": 0,
    "currency_id": 1234,
    "currency": "string",
    "responsible_user_id": 1234,
    "responsible": "string",
    "excluded": true,
    "locked": true,
    "approved_for_billing": true,
    "invoiced": true,
    "invoiced_at": "2026-10-30T09:15:00+01:00",
    "invoice_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Facturas

Listar facturas

GET /api/agent/invoices

Lista las facturas (emitidas y recibidas), de la fecha de emisión más reciente a la más antigua. direction=outgoing es la lista de facturas emitidas del despacho y excluye las facturas proforma (direction=proforma las lista). Solo lectura: las facturas no se pueden crear ni modificar mediante la API. Las facturas de expedientes que el usuario no puede ver quedan ocultas.

Ámbito
invoices:read
Permiso de Flowyer
invoices:read, summary:read

Parámetros de consulta

direction
string

Las tres listas propias del despacho: outgoing = facturas emitidas por el despacho, sin las proformas (una fila antigua sin tipo de documento cuenta como factura, igual que en el panel del despacho); proforma = solicitudes de pago (díjbekérő) emitidas por el despacho; incoming = recibidas.

Valores admitidos: "incoming" "outgoing" "proforma"
paid_status
string
Valores admitidos: "unpaid" "paid" "partially_paid" "cancelled"
client_id
integer>= 1
matter_id
integer>= 1
issued_from
string <date>

Fecha de emisión igual o posterior.

Ejemplo: "2026-01-01"
issued_to
string <date>

Fecha de emisión igual o anterior.

Ejemplo: "2026-12-31"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 301
invoice_number
string | null
Ejemplo: "FLW-2026-0042"
direction
string | null

outgoing = emitida por el despacho, incoming = recibida por el despacho.

Valores admitidos: "incoming" "outgoing"
document_type
string | null

"proforma" es una solicitud de pago, no una factura emitida: no es un ingreso y no debe sumarse con las emitidas. invoices.list direction=outgoing excluye las proformas y direction=proforma las lista. Null en una fila antigua, que cuenta como factura.

Valores admitidos: "invoice" "proforma" "receipt"
source
string | null
Valores admitidos: "manual" "szamlazz_outgoing" "szamlazz_imported"
paid_status
string | null
Valores admitidos: "unpaid" "paid" "partially_paid" "cancelled"
issued_date
string <date> | null
due_date
string <date> | null
paid_date
string <date> | null
completion_date
string <date> | null
net_amount
number | null
gross_amount
number | null
currency
string | null
Ejemplo: "HUF"
payment_method_id
integer | null
payment_method
string | null

Nombre localizado de la forma de pago (p. ej. transferencia bancaria); en inglés si el idioma del despacho no tiene traducción, null si la forma de pago no tiene nombre. Identifique la forma de pago por payment_method_id.

supplier
string | null

Emisor de una factura recibida.

client
object | null
Campos de client
id
integer
name
string
matter_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/invoices?issued_from=2026-01-01&issued_to=2026-12-31&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 301,
      "invoice_number": "FLW-2026-0042",
      "direction": "incoming",
      "document_type": "invoice",
      "source": "manual",
      "paid_status": "unpaid",
      "issued_date": "2026-10-30",
      "due_date": "2026-10-30",
      "paid_date": "2026-10-30",
      "completion_date": "2026-10-30",
      "net_amount": 0,
      "gross_amount": 0,
      "currency": "HUF",
      "payment_method_id": 1234,
      "payment_method": "string",
      "supplier": "string",
      "client": {
        "id": 1234,
        "name": "string"
      },
      "matter_id": 1234,
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener factura

GET /api/agent/invoices/{id}

Devuelve una factura. Solo lectura. Responde 404 si no existe o pertenece a un expediente que el usuario no puede ver.

Ámbito
invoices:read
Permiso de Flowyer
invoices:read, summary:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la factura.

Ejemplo: 301

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 301
invoice_number
string | null
Ejemplo: "FLW-2026-0042"
direction
string | null

outgoing = emitida por el despacho, incoming = recibida por el despacho.

Valores admitidos: "incoming" "outgoing"
document_type
string | null

"proforma" es una solicitud de pago, no una factura emitida: no es un ingreso y no debe sumarse con las emitidas. invoices.list direction=outgoing excluye las proformas y direction=proforma las lista. Null en una fila antigua, que cuenta como factura.

Valores admitidos: "invoice" "proforma" "receipt"
source
string | null
Valores admitidos: "manual" "szamlazz_outgoing" "szamlazz_imported"
paid_status
string | null
Valores admitidos: "unpaid" "paid" "partially_paid" "cancelled"
issued_date
string <date> | null
due_date
string <date> | null
paid_date
string <date> | null
completion_date
string <date> | null
net_amount
number | null
gross_amount
number | null
currency
string | null
Ejemplo: "HUF"
payment_method_id
integer | null
payment_method
string | null

Nombre localizado de la forma de pago (p. ej. transferencia bancaria); en inglés si el idioma del despacho no tiene traducción, null si la forma de pago no tiene nombre. Identifique la forma de pago por payment_method_id.

supplier
string | null

Emisor de una factura recibida.

client
object | null
Campos de client
id
integer
name
string
matter_id
integer | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
notes
string | null
received_date
string <date> | null
sent_date
string <date> | null
proforma_invoice_id
integer | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/invoices/301' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 301,
    "invoice_number": "FLW-2026-0042",
    "direction": "incoming",
    "document_type": "invoice",
    "source": "manual",
    "paid_status": "unpaid",
    "issued_date": "2026-10-30",
    "due_date": "2026-10-30",
    "paid_date": "2026-10-30",
    "completion_date": "2026-10-30",
    "net_amount": 0,
    "gross_amount": 0,
    "currency": "HUF",
    "payment_method_id": 1234,
    "payment_method": "string",
    "supplier": "string",
    "client": {
      "id": 1234,
      "name": "string"
    },
    "matter_id": 1234,
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "notes": "string",
    "received_date": "2026-10-30",
    "sent_date": "2026-10-30",
    "proforma_invoice_id": 1234
  }
}

Documentos

Listar documentos del expediente

GET /api/agent/matters/{id}/documents

Muestra las versiones actuales de los documentos archivados en un expediente: nombres, tamaños, carpetas y quién los subió. Solo metadatos; use documents.download (ámbito documents:download) para obtener un enlace firmado al contenido. Primero aparecen los documentos con nombre, por orden alfabético, y después los importados sin nombre.

Ámbito
documents:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Filtrar por nombre de archivo.

Ejemplo: "contract"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
name
string

Nombre del archivo tal como aparece en Flowyer: el nombre almacenado con el documento o, si se importó de un sistema anterior sin nombre, su nombre de almacenamiento. documents.list se ordena por el nombre almacenado: primero los documentos que lo tienen, por orden alfabético, y después los importados sin nombre almacenado, del más antiguo al más reciente (el orden en que se registraron en Flowyer), que por tanto no están ordenados por el nombre que se muestra aquí. El orden es el mismo en todas las páginas, de modo que limit y offset recorren la lista sin repeticiones ni huecos.

Ejemplo: "Contract_v2.docx"
size
integer | null

Bytes.

version
integer

Número de versión actual del archivo.

folder
object | null

La carpeta en la que está ubicado el documento, o null en la raíz del expediente. documents.upload.complete responde null cuando la carpeta elegida en documents.upload.init se eliminó mientras se subían los bytes: el documento se ubica entonces en la raíz del expediente, que es donde lo muestra Flowyer. Si la raíz ya contiene un documento con ese nombre, la subida se guarda con un nombre con sufijo ("Contract_2.pdf") en lugar de convertirse en una nueva versión de ese documento no relacionado; la respuesta 201 devuelve el name almacenado.

Campos de folder
id
integer
name
string
path
string

Ruta de la carpeta dentro del expediente, separada por "/".

folder_deleted
boolean

True cuando el documento está ubicado en una carpeta que ya no existe, que la propia lista de archivos de Flowyer no muestra (folder es null en ese caso, igual que para un documento en la raíz del expediente). documents.upload.complete solo responde true si la carpeta se eliminó mientras se subían los bytes Y falló el traslado del archivo almacenado a la raíz del expediente: el documento se mantiene entonces en la carpeta eliminada, donde su contenido sigue siendo accesible. False en todos los demás casos, incluida una ubicación normal en la raíz.

created_by_user_id
integer | null
created_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/documents?q=contract&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "name": "Contract_v2.docx",
      "size": 0,
      "version": 0,
      "folder": {
        "id": 1234,
        "name": "string",
        "path": "string"
      },
      "folder_deleted": true,
      "created_by_user_id": 1234,
      "created_by": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Listar carpetas del expediente

GET /api/agent/matters/{id}/folders

Muestra todas las carpetas de un expediente, incluidas las vacías: id, nombre, parent_id y la ruta separada por "/", ordenadas por ruta. Pase un id de carpeta como folder_id a documents.upload.init. Responde 404 si el expediente no es visible para el usuario.

Ámbito
documents:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Solo las carpetas cuya ruta contenga este texto (sin distinguir mayúsculas y minúsculas ni acentos), p. ej., un nombre de carpeta.

Ejemplo: "Beadványok"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de carpeta: páselo como folder_id a documents.upload.init.

name
string

Nombre de la carpeta tal como aparece en Flowyer.

parent_id
integer | null

Id de la carpeta principal; null para una carpeta en la raíz del expediente.

path
string

Ruta de la carpeta dentro del expediente, separada por "/", p. ej., "/Iratok/Beadványok" (la misma ruta que documents.list muestra para la carpeta de un archivo).

updated_at
string <date-time> | null

Páselo a documents.folders.rename como expected_updated_at.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/folders?q=Beadv%C3%A1nyok&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "name": "string",
      "parent_id": 1234,
      "path": "string",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Crear carpeta del expediente

POST /api/agent/matters/{id}/folders

Crea una carpeta en un expediente, en la raíz o dentro de parent_id (una carpeta del MISMO expediente). El nombre es texto sin formato (no se admiten "<" ni ">"). Para archivar un documento en ella, pase el id devuelto como folder_id a documents.upload.init. Responde 404 si el expediente no es visible.

Ámbito
documents:create
Permiso de Flowyer
cases:create

Parámetros de ruta

idobligatorio
integer>= 1

Expediente al que pertenece la carpeta (debe ser visible).

Ejemplo: 1234

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nombre de la carpeta, como máximo 255 caracteres. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Beadványok"
parent_id
integer | null>= 1

Id de la carpeta superior (de documents.folders) dentro del MISMO expediente; omítalo para una carpeta en la raíz del expediente.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer

Id de la carpeta: páselo como folder_id a documents.upload.init, o como parent_id a documents.folders.create.

name
string

Nombre de la carpeta tal como aparece en Flowyer.

parent_id
integer | null

Id de la carpeta principal; null para una carpeta en la raíz del expediente.

path
string

Ruta de la carpeta dentro del expediente, separada por "/", p. ej. "/Iratok/Beadványok".

updated_at
string <date-time> | null

Páselo a documents.folders.rename como expected_updated_at.

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer

Id de la carpeta: páselo como folder_id a documents.upload.init, o como parent_id a documents.folders.create.

name
string

Nombre de la carpeta tal como aparece en Flowyer.

parent_id
integer | null

Id de la carpeta principal; null para una carpeta en la raíz del expediente.

path
string

Ruta de la carpeta dentro del expediente, separada por "/", p. ej. "/Iratok/Beadványok".

updated_at
string <date-time> | null

Páselo a documents.folders.rename como expected_updated_at.

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/folders' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "name": "Beadványok"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "name": "string",
    "parent_id": 1234,
    "path": "string",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Iniciar subida de documento

POST /api/agent/matters/{id}/documents/uploads

Inicia la subida de un documento: devuelve una upload_url firmada y un upload_token. Envíe allí los bytes con PUT y después llame a documents.upload.complete. El PUT es una solicitud HTTPS simple, ajena a esta API y a las herramientas MCP: un asistente sin cliente HTTP propio debe pedir al usuario que suba el archivo en Flowyer.

Ámbito
documents:create
Permiso de Flowyer
cases:create

Parámetros de ruta

idobligatorio
integer>= 1

Expediente al que pertenece el documento (debe ser visible).

Cuerpo de la solicitud application/json

filenameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nombre de archivo con extensión, p. ej., "Contract.pdf". Texto sin formato; no se admiten "<" ni ">". Se rechazan los tipos de archivo ejecutables y web (422 blocked_file_type).

Patrón: ^[^<>]*$
Ejemplo: "Contract.pdf"
content_typeobligatorio
stringal menos 1 caracterescomo máximo 100 caracteres

Tipo MIME enviado en el PUT, p. ej., "application/pdf". Forma parte de la firma y debe coincidir exactamente.

Ejemplo: "application/pdf"
sizeobligatorio
integer>= 1

Tamaño del archivo en bytes, como máximo 104857600 (el límite de subida); un tamaño mayor responde 413 file_too_large.

Ejemplo: 248000
folder_id
integer | null>= 1

Carpeta dentro del expediente: un id de carpeta de documents.folders (también muestra las carpetas vacías). Omítalo para la raíz del expediente.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
upload_url
string

URL firmada. Envíe aquí los bytes del archivo con PUT, con el tipo de contenido indicado Y la cabecera if_generation_match de abajo: una solicitud HTTPS simple realizada por su propio cliente HTTP (ninguna herramienta de la API ni de MCP la envía).

upload_token
string

Páselo a documents.upload.complete una vez que el PUT se haya realizado correctamente.

content_type
string

Envíe exactamente este Content-Type en el PUT.

if_generation_match
string

Envíe este valor como cabecera "x-goog-if-generation-match" en el PUT (siempre "0"). Hace que la subida sea de un solo uso: el PUT solo se acepta mientras el objeto aún no existe, de modo que la URL firmada no puede sobrescribir un documento ya archivado.

object_key
string

Nombre interno de almacenamiento (a título informativo).

expires_in
integer

Segundos hasta que caduquen la URL de subida y el token.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

413

El cuerpo de la solicitud es demasiado grande (request_too_large), o el archivo supera el límite de subida (file_too_large; details.max indica el límite en bytes).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/documents/uploads' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "filename": "Contract.pdf",
  "content_type": "application/pdf",
  "size": 248000
}'

Ejemplos de respuesta

{
  "data": {
    "upload_url": "string",
    "upload_token": "string",
    "content_type": "string",
    "if_generation_match": "string",
    "object_key": "string",
    "expires_in": 0
  }
}

Finalizar subida de documento

POST /api/agent/matters/{id}/documents

Finaliza la subida de un documento: una vez enviados los bytes con PUT a upload_url, registra el archivo en el expediente como nueva versión. Pase el upload_token de documents.upload.init. Los metadatos del archivo se toman del token, no de esta solicitud. Si la carpeta se ha eliminado entretanto, el documento se guarda en la raíz.

Ámbito
documents:create
Permiso de Flowyer
cases:create

Parámetros de ruta

idobligatorio
integer>= 1

Expediente al que pertenece el documento (el mismo que en init).

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

upload_tokenobligatorio
stringal menos 1 caracterescomo máximo 4096 caracteres

El token devuelto por documents.upload.init.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
name
string

Nombre del archivo tal como aparece en Flowyer: el nombre almacenado con el documento o, si se importó de un sistema anterior sin nombre, su nombre de almacenamiento. documents.list se ordena por el nombre almacenado: primero los documentos que lo tienen, por orden alfabético, y después los importados sin nombre almacenado, del más antiguo al más reciente (el orden en que se registraron en Flowyer), que por tanto no están ordenados por el nombre que se muestra aquí. El orden es el mismo en todas las páginas, de modo que limit y offset recorren la lista sin repeticiones ni huecos.

Ejemplo: "Contract_v2.docx"
size
integer | null

Bytes.

version
integer

Número de versión actual del archivo.

folder
object | null

La carpeta en la que está ubicado el documento, o null en la raíz del expediente. documents.upload.complete responde null cuando la carpeta elegida en documents.upload.init se eliminó mientras se subían los bytes: el documento se ubica entonces en la raíz del expediente, que es donde lo muestra Flowyer. Si la raíz ya contiene un documento con ese nombre, la subida se guarda con un nombre con sufijo ("Contract_2.pdf") en lugar de convertirse en una nueva versión de ese documento no relacionado; la respuesta 201 devuelve el name almacenado.

Campos de folder
id
integer
name
string
path
string

Ruta de la carpeta dentro del expediente, separada por "/".

folder_deleted
boolean

True cuando el documento está ubicado en una carpeta que ya no existe, que la propia lista de archivos de Flowyer no muestra (folder es null en ese caso, igual que para un documento en la raíz del expediente). documents.upload.complete solo responde true si la carpeta se eliminó mientras se subían los bytes Y falló el traslado del archivo almacenado a la raíz del expediente: el documento se mantiene entonces en la carpeta eliminada, donde su contenido sigue siendo accesible. False en todos los demás casos, incluida una ubicación normal en la raíz.

created_by_user_id
integer | null
created_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo. También es la respuesta cuando este upload_token ya se completó.

dataobligatorio
object
Campos de data
id
integer
name
string

Nombre del archivo tal como aparece en Flowyer: el nombre almacenado con el documento o, si se importó de un sistema anterior sin nombre, su nombre de almacenamiento. documents.list se ordena por el nombre almacenado: primero los documentos que lo tienen, por orden alfabético, y después los importados sin nombre almacenado, del más antiguo al más reciente (el orden en que se registraron en Flowyer), que por tanto no están ordenados por el nombre que se muestra aquí. El orden es el mismo en todas las páginas, de modo que limit y offset recorren la lista sin repeticiones ni huecos.

Ejemplo: "Contract_v2.docx"
size
integer | null

Bytes.

version
integer

Número de versión actual del archivo.

folder
object | null

La carpeta en la que está ubicado el documento, o null en la raíz del expediente. documents.upload.complete responde null cuando la carpeta elegida en documents.upload.init se eliminó mientras se subían los bytes: el documento se ubica entonces en la raíz del expediente, que es donde lo muestra Flowyer. Si la raíz ya contiene un documento con ese nombre, la subida se guarda con un nombre con sufijo ("Contract_2.pdf") en lugar de convertirse en una nueva versión de ese documento no relacionado; la respuesta 201 devuelve el name almacenado.

Campos de folder
id
integer
name
string
path
string

Ruta de la carpeta dentro del expediente, separada por "/".

folder_deleted
boolean

True cuando el documento está ubicado en una carpeta que ya no existe, que la propia lista de archivos de Flowyer no muestra (folder es null en ese caso, igual que para un documento en la raíz del expediente). documents.upload.complete solo responde true si la carpeta se eliminó mientras se subían los bytes Y falló el traslado del archivo almacenado a la raíz del expediente: el documento se mantiene entonces en la carpeta eliminada, donde su contenido sigue siendo accesible. False en todos los demás casos, incluida una ubicación normal en la raíz.

created_by_user_id
integer | null
created_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe o no es visible para el usuario. upload_not_finished: el archivo aún no ha llegado al almacenamiento; complete el PUT a upload_url y vuelva a llamar a complete. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large), o el archivo supera el límite de subida (file_too_large; details.max indica el límite en bytes).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/documents' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "upload_token": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "name": "Contract_v2.docx",
    "size": 0,
    "version": 0,
    "folder": {
      "id": 1234,
      "name": "string",
      "path": "string"
    },
    "folder_deleted": true,
    "created_by_user_id": 1234,
    "created_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Descargar documento

GET /api/agent/documents/{id}/download

Devuelve una URL firmada de corta duración para descargar un documento por id, si su expediente es visible. Haga un GET a la URL para obtener los bytes; caduca en pocos minutos.

Ámbito
documents:download
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del documento (de documents.list).

Respuestas

200

OK.

dataobligatorio
object
Campos de data
download_url
string

URL firmada. Haga un GET a ella para descargar los bytes del archivo.

filename
string

Nombre del archivo para la descarga.

size
integer | null

Bytes.

expires_in
integer

Segundos hasta que caduque la URL.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/documents/1234/download' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "download_url": "string",
    "filename": "string",
    "size": 0,
    "expires_in": 0
  }
}

Listar versiones del documento

GET /api/agent/documents/{id}/versions

Lista todas las versiones de un documento (pase cualquier id de versión, p. ej. de documents.list): número de versión, nombre, tamaño, quién la subió, fecha y cuál es la actual. Cada versión tiene su propio id; descargue cualquiera con documents.download o léalas todas como historial completo de versiones.

Ámbito
documents:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del documento: cualquiera de sus versiones (de documents.list o documents.versions).

Ejemplo: 1234

Parámetros de consulta

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de la versión: páselo a documents.download (ámbito documents:download) para obtener los bytes de esta versión exacta.

version
integer

Número de versión; el más alto es el actual.

is_current
boolean

True para la versión que Flowyer muestra ahora, false para una versión anterior sustituida.

name
string

Nombre del archivo almacenado con esta versión (su nombre de almacenamiento si se importó sin nombre).

size
integer | null

Bytes.

uploaded_by_user_id
integer | null
uploaded_by
string | null
uploaded_at
string <date-time> | null

Cuándo se registró esta versión.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/documents/1234/versions?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "version": 0,
      "is_current": true,
      "name": "string",
      "size": 0,
      "uploaded_by_user_id": 1234,
      "uploaded_by": "string",
      "uploaded_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Renombrar documento

PATCH /api/agent/documents/{id}

Renombra un documento (solo su nombre visible; el contenido del archivo no cambia). El nuevo nombre debe ser único en la misma carpeta del expediente. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409.

Ámbito
documents:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nuevo nombre de archivo, como máximo 255 caracteres INCLUIDA la extensión. Si omite la extensión, se mantiene la actual, que cuenta para los 255 (así, un nombre sin extensión para "Beadvany.pdf" puede tener como máximo 251 caracteres). Texto sin formato; no se admiten "<" ni ">", por lo que un documento cuyo nombre almacenado contenga alguno solo se puede renombrar en Flowyer.

Patrón: ^[^<>]*$
Ejemplo: "Contract_signed.pdf"

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
name
string

Nombre del archivo tal como aparece en Flowyer: el nombre almacenado con el documento o, si se importó de un sistema anterior sin nombre, su nombre de almacenamiento. documents.list se ordena por el nombre almacenado: primero los documentos que lo tienen, por orden alfabético, y después los importados sin nombre almacenado, del más antiguo al más reciente (el orden en que se registraron en Flowyer), que por tanto no están ordenados por el nombre que se muestra aquí. El orden es el mismo en todas las páginas, de modo que limit y offset recorren la lista sin repeticiones ni huecos.

Ejemplo: "Contract_v2.docx"
size
integer | null

Bytes.

version
integer

Número de versión actual del archivo.

folder
object | null

La carpeta en la que está ubicado el documento, o null en la raíz del expediente. documents.upload.complete responde null cuando la carpeta elegida en documents.upload.init se eliminó mientras se subían los bytes: el documento se ubica entonces en la raíz del expediente, que es donde lo muestra Flowyer. Si la raíz ya contiene un documento con ese nombre, la subida se guarda con un nombre con sufijo ("Contract_2.pdf") en lugar de convertirse en una nueva versión de ese documento no relacionado; la respuesta 201 devuelve el name almacenado.

Campos de folder
id
integer
name
string
path
string

Ruta de la carpeta dentro del expediente, separada por "/".

folder_deleted
boolean

True cuando el documento está ubicado en una carpeta que ya no existe, que la propia lista de archivos de Flowyer no muestra (folder es null en ese caso, igual que para un documento en la raíz del expediente). documents.upload.complete solo responde true si la carpeta se eliminó mientras se subían los bytes Y falló el traslado del archivo almacenado a la raíz del expediente: el documento se mantiene entonces en la carpeta eliminada, donde su contenido sigue siendo accesible. False en todos los demás casos, incluida una ubicación normal en la raíz.

created_by_user_id
integer | null
created_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at), o ya hay otro documento con este nombre en la misma carpeta (duplicate_name; elija otro nombre, no reintente con el mismo).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/documents/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "name": "Contract_signed.pdf"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "name": "Contract_v2.docx",
    "size": 0,
    "version": 0,
    "folder": {
      "id": 1234,
      "name": "string",
      "path": "string"
    },
    "folder_deleted": true,
    "created_by_user_id": 1234,
    "created_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Renombrar carpeta del expediente

PATCH /api/agent/folders/{id}

Renombra una carpeta (solo su nombre; sus archivos y subcarpetas permanecen en su sitio). El nombre es texto sin formato (no se admiten "<" ni ">"). Pase expected_updated_at de su última lectura (documents.folders lo indica); un cambio en conflicto responde 409.

Ámbito
documents:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

nameobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Nuevo nombre de la carpeta, como máximo 255 caracteres. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Beadványok"

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id de la carpeta: páselo como folder_id a documents.upload.init, o como parent_id a documents.folders.create.

name
string

Nombre de la carpeta tal como aparece en Flowyer.

parent_id
integer | null

Id de la carpeta principal; null para una carpeta en la raíz del expediente.

path
string

Ruta de la carpeta dentro del expediente, separada por "/", p. ej. "/Iratok/Beadványok".

updated_at
string <date-time> | null

Páselo a documents.folders.rename como expected_updated_at.

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/folders/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "name": "Beadványok"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "name": "string",
    "parent_id": 1234,
    "path": "string",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Base de conocimiento

Listar artículos de la base de conocimiento

GET /api/agent/knowledge/articles

Lista los artículos de la base de conocimiento que el usuario puede ver (los propios del autor, los artículos globales y los compartidos con el rol del usuario). Por defecto, todos los estados; filtre por estado o pase q para buscar en el texto completo de títulos, extractos, contenido y etiquetas.

Ámbito
knowledge:read

Parámetros de consulta

q
string | nullcomo máximo 255 caracteres

Término de búsqueda de texto completo (títulos, extractos, contenido y nombres de etiquetas). Los operadores booleanos se eliminan.

Ejemplo: "felmondási idő"
status
string | null

Solo los artículos con este estado. Omítalo para listar todos los estados.

Valores admitidos: "draft" "published" "archived"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 9876
slug
string

Slug de URL generado por el servidor.

Ejemplo: "felmondasi-ido"
title
string
Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (HTML enriquecido, tal como está almacenado). Use knowledge.articles.get para obtener el cuerpo completo.

status
string
Valores admitidos: "draft" "published" "archived"
is_featured
boolean

Si el artículo está fijado en la página de inicio de la base de conocimiento (no se puede establecer mediante la API).

category_id
integer | null
category_name
string | null
author_id
integer

Id de usuario del autor; 0 para un artículo global (predeterminado).

author_name
string | null
editor_id
integer | null

Id de usuario del último editor, o null si nunca se ha editado.

editor_name
string | null
views_count
integer
downloads_count
integer
shared_roles
integer[]

Ids de los roles con los que se comparte el artículo (vacío = solo el autor/global).

tags
string[]

Nombres de las etiquetas del artículo.

published_at
string <date-time> | null

Cuándo se publicó el artículo por primera vez, o null.

created_at
string <date-time> | null
updated_at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/knowledge/articles?q=felmond%C3%A1si%20id%C5%91&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 9876,
      "slug": "felmondasi-ido",
      "title": "Felmondási idő a munka törvénykönyvében",
      "excerpt": "string",
      "status": "draft",
      "is_featured": true,
      "category_id": 1234,
      "category_name": "string",
      "author_id": 1234,
      "author_name": "string",
      "editor_id": 1234,
      "editor_name": "string",
      "views_count": 0,
      "downloads_count": 0,
      "shared_roles": [
        0
      ],
      "tags": [
        "string"
      ],
      "published_at": "2026-10-30T09:15:00+01:00",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener artículo de la base de conocimiento

GET /api/agent/knowledge/articles/{id}

Devuelve un artículo de la base de conocimiento, con su contenido completo, etiquetas y roles con los que se comparte. Responde 404 si el artículo no existe o el usuario no puede verlo.

Ámbito
knowledge:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del artículo.

Ejemplo: 9876

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
slug
string

Slug de URL generado por el servidor.

Ejemplo: "felmondasi-ido"
title
string
Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (HTML enriquecido, tal como está almacenado). Use knowledge.articles.get para obtener el cuerpo completo.

status
string
Valores admitidos: "draft" "published" "archived"
is_featured
boolean

Si el artículo está fijado en la página de inicio de la base de conocimiento (no se puede establecer mediante la API).

category_id
integer | null
category_name
string | null
author_id
integer

Id de usuario del autor; 0 para un artículo global (predeterminado).

author_name
string | null
editor_id
integer | null

Id de usuario del último editor, o null si nunca se ha editado.

editor_name
string | null
views_count
integer
downloads_count
integer
shared_roles
integer[]

Ids de los roles con los que se comparte el artículo (vacío = solo el autor/global).

tags
string[]

Nombres de las etiquetas del artículo.

published_at
string <date-time> | null

Cuándo se publicó el artículo por primera vez, o null.

created_at
string <date-time> | null
updated_at
string <date-time> | null
content
string

El cuerpo completo del artículo tal como está almacenado (HTML enriquecido).

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/knowledge/articles/9876' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "slug": "felmondasi-ido",
    "title": "Felmondási idő a munka törvénykönyvében",
    "excerpt": "string",
    "status": "draft",
    "is_featured": true,
    "category_id": 1234,
    "category_name": "string",
    "author_id": 1234,
    "author_name": "string",
    "editor_id": 1234,
    "editor_name": "string",
    "views_count": 0,
    "downloads_count": 0,
    "shared_roles": [
      0
    ],
    "tags": [
      "string"
    ],
    "published_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "content": "string"
  }
}

Crear artículo de la base de conocimiento

POST /api/agent/knowledge/articles

Crea un artículo de la base de conocimiento cuyo autor es el usuario de la clave. El slug se genera a partir del título. La categoría debe existir y estar activa. Compártalo con roles mediante shared_roles (si no, solo lo ve el autor). content y excerpt son HTML y se sanean en el servidor.

Ámbito
knowledge:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

titleobligatorio
stringcomo máximo 500 caracteres

Título del artículo. Texto sin formato.

Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (se admite HTML, saneado en el servidor), como máximo 200 caracteres.

contentobligatorio
string

El cuerpo del artículo. HTML enriquecido, saneado en el servidor con el perfil de la base de conocimiento.

category_idobligatorio
integer>= 1

Id de una categoría existente y activa de la base de conocimiento.

Ejemplo: 12
statusobligatorio
string

draft, published o archived. published registra published_at.

Valores admitidos: "draft" "published" "archived"
tags
string[] | null

Nombres de etiquetas; las etiquetas nuevas se crean cuando es necesario.

shared_roles
integer[] | null

Ids de los roles con los que se comparte el artículo. Vacío significa que solo el autor puede verlo.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
slug
string

Slug de URL generado por el servidor.

Ejemplo: "felmondasi-ido"
title
string
Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (HTML enriquecido, tal como está almacenado). Use knowledge.articles.get para obtener el cuerpo completo.

status
string
Valores admitidos: "draft" "published" "archived"
is_featured
boolean

Si el artículo está fijado en la página de inicio de la base de conocimiento (no se puede establecer mediante la API).

category_id
integer | null
category_name
string | null
author_id
integer

Id de usuario del autor; 0 para un artículo global (predeterminado).

author_name
string | null
editor_id
integer | null

Id de usuario del último editor, o null si nunca se ha editado.

editor_name
string | null
views_count
integer
downloads_count
integer
shared_roles
integer[]

Ids de los roles con los que se comparte el artículo (vacío = solo el autor/global).

tags
string[]

Nombres de las etiquetas del artículo.

published_at
string <date-time> | null

Cuándo se publicó el artículo por primera vez, o null.

created_at
string <date-time> | null
updated_at
string <date-time> | null
content
string

El cuerpo completo del artículo tal como está almacenado (HTML enriquecido).

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
slug
string

Slug de URL generado por el servidor.

Ejemplo: "felmondasi-ido"
title
string
Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (HTML enriquecido, tal como está almacenado). Use knowledge.articles.get para obtener el cuerpo completo.

status
string
Valores admitidos: "draft" "published" "archived"
is_featured
boolean

Si el artículo está fijado en la página de inicio de la base de conocimiento (no se puede establecer mediante la API).

category_id
integer | null
category_name
string | null
author_id
integer

Id de usuario del autor; 0 para un artículo global (predeterminado).

author_name
string | null
editor_id
integer | null

Id de usuario del último editor, o null si nunca se ha editado.

editor_name
string | null
views_count
integer
downloads_count
integer
shared_roles
integer[]

Ids de los roles con los que se comparte el artículo (vacío = solo el autor/global).

tags
string[]

Nombres de las etiquetas del artículo.

published_at
string <date-time> | null

Cuándo se publicó el artículo por primera vez, o null.

created_at
string <date-time> | null
updated_at
string <date-time> | null
content
string

El cuerpo completo del artículo tal como está almacenado (HTML enriquecido).

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/knowledge/articles' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "title": "Felmondási idő a munka törvénykönyvében",
  "content": "string",
  "category_id": 12,
  "status": "draft"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "slug": "felmondasi-ido",
    "title": "Felmondási idő a munka törvénykönyvében",
    "excerpt": "string",
    "status": "draft",
    "is_featured": true,
    "category_id": 1234,
    "category_name": "string",
    "author_id": 1234,
    "author_name": "string",
    "editor_id": 1234,
    "editor_name": "string",
    "views_count": 0,
    "downloads_count": 0,
    "shared_roles": [
      0
    ],
    "tags": [
      "string"
    ],
    "published_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "content": "string"
  },
  "created": true
}

Modificar artículo de la base de conocimiento

PATCH /api/agent/knowledge/articles/{id}

Modifica un artículo de la base de conocimiento: título (el slug se vuelve a generar), extracto, contenido, categoría, estado, etiquetas o roles con los que se comparte. Solo el autor puede editarlo (o cualquiera, si es un artículo global). Pase expected_updated_at; un cambio en conflicto responde 409. content y excerpt se sanean en el servidor.

Ámbito
knowledge:update

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

title
string | null

Título del artículo (texto sin formato). null mantiene el título actual; un título nuevo vuelve a generar el slug.

excerpt
string | null

Resumen breve (se admite HTML, saneado), como máximo 200 caracteres como valor NUEVO. Vacío/null lo borra; omítalo para mantenerlo.

content
string | null

El cuerpo del artículo (HTML enriquecido, saneado). null mantiene el contenido actual; no se puede borrar.

category_id
integer | null>= 1

Traslada el artículo a esta categoría existente y activa. null mantiene la actual.

status
string | null

draft, published o archived. El primer cambio a published registra published_at, que nunca se borra. null mantiene el estado actual.

Valores admitidos: "draft" "published" "archived"
tags
string[] | null

Sustituye el conjunto completo de etiquetas (las nuevas se crean). Una matriz vacía borra todas las etiquetas; omítalo para mantenerlas.

shared_roles
integer[] | null

Sustituye el conjunto completo de roles con los que se comparte. Una matriz vacía elimina todo el uso compartido (solo lo ve el autor); omítalo para mantenerlo.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
slug
string

Slug de URL generado por el servidor.

Ejemplo: "felmondasi-ido"
title
string
Ejemplo: "Felmondási idő a munka törvénykönyvében"
excerpt
string | null

Resumen breve (HTML enriquecido, tal como está almacenado). Use knowledge.articles.get para obtener el cuerpo completo.

status
string
Valores admitidos: "draft" "published" "archived"
is_featured
boolean

Si el artículo está fijado en la página de inicio de la base de conocimiento (no se puede establecer mediante la API).

category_id
integer | null
category_name
string | null
author_id
integer

Id de usuario del autor; 0 para un artículo global (predeterminado).

author_name
string | null
editor_id
integer | null

Id de usuario del último editor, o null si nunca se ha editado.

editor_name
string | null
views_count
integer
downloads_count
integer
shared_roles
integer[]

Ids de los roles con los que se comparte el artículo (vacío = solo el autor/global).

tags
string[]

Nombres de las etiquetas del artículo.

published_at
string <date-time> | null

Cuándo se publicó el artículo por primera vez, o null.

created_at
string <date-time> | null
updated_at
string <date-time> | null
content
string

El cuerpo completo del artículo tal como está almacenado (HTML enriquecido).

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/knowledge/articles/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "title": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "slug": "felmondasi-ido",
    "title": "Felmondási idő a munka törvénykönyvében",
    "excerpt": "string",
    "status": "draft",
    "is_featured": true,
    "category_id": 1234,
    "category_name": "string",
    "author_id": 1234,
    "author_name": "string",
    "editor_id": 1234,
    "editor_name": "string",
    "views_count": 0,
    "downloads_count": 0,
    "shared_roles": [
      0
    ],
    "tags": [
      "string"
    ],
    "published_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "content": "string"
  },
  "updated": true
}

Listar categorías de la base de conocimiento

GET /api/agent/knowledge/categories

Lista las categorías de la base de conocimiento que el usuario puede ver: las categorías predeterminadas integradas, las propias del usuario y las compartidas con su rol. En el mismo orden que en Flowyer (posición de orden y, después, nombre).

Ámbito
knowledge:read

Parámetros de consulta

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 42
slug
string

Slug de URL, generado a partir del nombre.

Ejemplo: "munkajog"
name
string
Ejemplo: "Munkajog"
description
string | null

Descripción en texto sin formato, o null.

icon
string | null

Identificador del icono que se muestra junto a la categoría, o null.

order_column
integer

Posición de orden entre las categorías del mismo nivel.

Ejemplo: 0
is_active
boolean
parent_id
integer | null

Id de la categoría principal, o null para una categoría raíz.

author_id
integer

Id de usuario del creador; 0 para una categoría predeterminada integrada visible para todos.

author_name
string | null

Nombre visible del creador, o null para una categoría predeterminada.

articles_count
integer

Número de artículos publicados de esta categoría que el solicitante puede ver.

shared_roles
integer[]

Ids de los roles con los que se comparte esta categoría. Vacío significa que solo la ve el autor (una categoría predeterminada con author_id 0 es visible para todos).

created_at
string <date-time> | null
updated_at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/knowledge/categories?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 42,
      "slug": "munkajog",
      "name": "Munkajog",
      "description": "string",
      "icon": "string",
      "order_column": 0,
      "is_active": true,
      "parent_id": 1234,
      "author_id": 1234,
      "author_name": "string",
      "articles_count": 0,
      "shared_roles": [
        1
      ],
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener categoría de la base de conocimiento

GET /api/agent/knowledge/categories/{id}

Devuelve una categoría de la base de conocimiento. Responde 404 si la categoría no existe o no es visible para el usuario titular de esta clave de API.

Ámbito
knowledge:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la categoría.

Ejemplo: 42

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 42
slug
string

Slug de URL, generado a partir del nombre.

Ejemplo: "munkajog"
name
string
Ejemplo: "Munkajog"
description
string | null

Descripción en texto sin formato, o null.

icon
string | null

Identificador del icono que se muestra junto a la categoría, o null.

order_column
integer

Posición de orden entre las categorías del mismo nivel.

Ejemplo: 0
is_active
boolean
parent_id
integer | null

Id de la categoría principal, o null para una categoría raíz.

author_id
integer

Id de usuario del creador; 0 para una categoría predeterminada integrada visible para todos.

author_name
string | null

Nombre visible del creador, o null para una categoría predeterminada.

articles_count
integer

Número de artículos publicados de esta categoría que el solicitante puede ver.

shared_roles
integer[]

Ids de los roles con los que se comparte esta categoría. Vacío significa que solo la ve el autor (una categoría predeterminada con author_id 0 es visible para todos).

created_at
string <date-time> | null
updated_at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/knowledge/categories/42' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 42,
    "slug": "munkajog",
    "name": "Munkajog",
    "description": "string",
    "icon": "string",
    "order_column": 0,
    "is_active": true,
    "parent_id": 1234,
    "author_id": 1234,
    "author_name": "string",
    "articles_count": 0,
    "shared_roles": [
      1
    ],
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  }
}

Crear categoría de la base de conocimiento

POST /api/agent/knowledge/categories

Crea una categoría de la base de conocimiento. El slug de URL se genera a partir del nombre. Compártala con roles mediante shared_roles, u omítalos para que solo usted (el autor) pueda verla. Si se indica parent_id, debe ser una categoría existente y activa.

Ámbito
knowledge:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

nameobligatorio
stringcomo máximo 255 caracteres

Nombre de la categoría. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Munkajog"
description
string | null

Descripción opcional, texto sin formato.

parent_id
integer | null>= 1

Id de la categoría principal (debe existir y estar activa). Omítalo para una categoría raíz.

icon
string | nullcomo máximo 100 caracteres

Identificador de icono opcional. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
is_active
boolean | null

Si la categoría está activa. Valor predeterminado: true.

Valor por defecto: true
order_column
integer | null>= 0

Posición de orden entre las categorías del mismo nivel. Valor predeterminado: 0.

Ejemplo: 0
shared_roles
integer[] | null

Ids de los roles con los que se comparte esta categoría. Omítalo para que solo usted (el autor) pueda verla.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 42
slug
string

Slug de URL, generado a partir del nombre.

Ejemplo: "munkajog"
name
string
Ejemplo: "Munkajog"
description
string | null

Descripción en texto sin formato, o null.

icon
string | null

Identificador del icono que se muestra junto a la categoría, o null.

order_column
integer

Posición de orden entre las categorías del mismo nivel.

Ejemplo: 0
is_active
boolean
parent_id
integer | null

Id de la categoría principal, o null para una categoría raíz.

author_id
integer

Id de usuario del creador; 0 para una categoría predeterminada integrada visible para todos.

author_name
string | null

Nombre visible del creador, o null para una categoría predeterminada.

articles_count
integer

Número de artículos publicados de esta categoría que el solicitante puede ver.

shared_roles
integer[]

Ids de los roles con los que se comparte esta categoría. Vacío significa que solo la ve el autor (una categoría predeterminada con author_id 0 es visible para todos).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 42
slug
string

Slug de URL, generado a partir del nombre.

Ejemplo: "munkajog"
name
string
Ejemplo: "Munkajog"
description
string | null

Descripción en texto sin formato, o null.

icon
string | null

Identificador del icono que se muestra junto a la categoría, o null.

order_column
integer

Posición de orden entre las categorías del mismo nivel.

Ejemplo: 0
is_active
boolean
parent_id
integer | null

Id de la categoría principal, o null para una categoría raíz.

author_id
integer

Id de usuario del creador; 0 para una categoría predeterminada integrada visible para todos.

author_name
string | null

Nombre visible del creador, o null para una categoría predeterminada.

articles_count
integer

Número de artículos publicados de esta categoría que el solicitante puede ver.

shared_roles
integer[]

Ids de los roles con los que se comparte esta categoría. Vacío significa que solo la ve el autor (una categoría predeterminada con author_id 0 es visible para todos).

created_at
string <date-time> | null
updated_at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/knowledge/categories' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "name": "Munkajog",
  "order_column": 0
}'

Ejemplos de respuesta

{
  "data": {
    "id": 42,
    "slug": "munkajog",
    "name": "Munkajog",
    "description": "string",
    "icon": "string",
    "order_column": 0,
    "is_active": true,
    "parent_id": 1234,
    "author_id": 1234,
    "author_name": "string",
    "articles_count": 0,
    "shared_roles": [
      1
    ],
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Modificar categoría de la base de conocimiento

PATCH /api/agent/knowledge/categories/{id}

Modifica una categoría de la base de conocimiento: nombre (el slug se actualiza en consecuencia), descripción, icono, categoría principal, indicador de activa, posición de orden o roles con los que se comparte. Solo el autor puede modificarla (una categoría predeterminada integrada la puede editar cualquiera). Pase expected_updated_at; un cambio en conflicto responde 409.

Ámbito
knowledge:update

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

name
string | nullal menos 1 caracteres

Nombre de la categoría. Como máximo 255 caracteres como valor NUEVO; no se pueden introducir "<" ni ">", pero un nombre almacenado más largo o que los contenga se puede devolver sin cambios. null mantiene el nombre actual.

description
string | null

Descripción en texto sin formato. null la borra.

parent_id
integer | null>= 1

Traslada la categoría bajo esta categoría principal (debe existir, estar activa y no crear un ciclo), o null para convertirla en categoría raíz.

icon
string | null

Identificador del icono. Como máximo 100 caracteres como valor NUEVO; no se pueden introducir "<" ni ">". null lo borra.

is_active
boolean | null

Indicador de activa. Omítalo o use null para mantener el valor actual.

order_column
integer | null>= 0

Posición de orden entre las categorías del mismo nivel. Omítalo o use null para mantener el valor actual.

shared_roles
integer[] | null

Sustituye el conjunto de ids de roles con los que se comparte esta categoría. Una matriz vacía elimina todo el uso compartido (solo la ve el autor). Omítalo para no cambiar el uso compartido.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 42
slug
string

Slug de URL, generado a partir del nombre.

Ejemplo: "munkajog"
name
string
Ejemplo: "Munkajog"
description
string | null

Descripción en texto sin formato, o null.

icon
string | null

Identificador del icono que se muestra junto a la categoría, o null.

order_column
integer

Posición de orden entre las categorías del mismo nivel.

Ejemplo: 0
is_active
boolean
parent_id
integer | null

Id de la categoría principal, o null para una categoría raíz.

author_id
integer

Id de usuario del creador; 0 para una categoría predeterminada integrada visible para todos.

author_name
string | null

Nombre visible del creador, o null para una categoría predeterminada.

articles_count
integer

Número de artículos publicados de esta categoría que el solicitante puede ver.

shared_roles
integer[]

Ids de los roles con los que se comparte esta categoría. Vacío significa que solo la ve el autor (una categoría predeterminada con author_id 0 es visible para todos).

created_at
string <date-time> | null
updated_at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/knowledge/categories/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "name": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 42,
    "slug": "munkajog",
    "name": "Munkajog",
    "description": "string",
    "icon": "string",
    "order_column": 0,
    "is_active": true,
    "parent_id": 1234,
    "author_id": 1234,
    "author_name": "string",
    "articles_count": 0,
    "shared_roles": [
      1
    ],
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Correos electrónicos

Listar correos electrónicos del expediente

GET /api/agent/matters/{id}/emails

Muestra los correos electrónicos guardados en un expediente: nombre y dirección del remitente, asunto, tamaño y el miembro del equipo que guardó cada uno, empezando por el enviado más recientemente. Solo cabecera y metadatos, nunca el cuerpo ni el HTML sin procesar. Use emails.get para obtener el cuerpo en texto sin formato de un mensaje concreto.

Ámbito
emails:read
Permiso de Flowyer
emails:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

q
stringcomo máximo 100 caracteres

Filtrar por asunto, nombre del remitente o dirección del remitente (sin distinguir acentos ni mayúsculas y minúsculas). No busca en el cuerpo.

Ejemplo: "invoice"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id del correo electrónico (se usa con emails.get).

Ejemplo: 1234
from_name
string | null

Nombre visible de la parte externa. El almacén no guarda columnas de dirección ni de destinatario, por lo que siempre es la parte externa, nunca un miembro del equipo, y la API no puede indicar si el correo era de entrada o de salida.

from_address
string | null

Dirección SMTP de la parte externa.

subject
string | null
sent_at
string <date-time> | null

Momento en que se envió el mensaje. La zona horaria del valor almacenado varía según la vía de entrada (el worker IMAP almacena UTC y el complemento de Outlook almacena la hora local de la zona del despacho), por lo que es aproximado y el orden de la lista basado en él puede desviarse entre fuentes en la diferencia UTC del despacho. created_at es la marca de tiempo fiable.

size
integer | null

Tamaño en bytes del archivo .eml/.msg almacenado.

extension
string | null

"msg" (complemento de Outlook) o "eml" (IMAP / predeterminado); null en algunas filas antiguas.

saved_by_user_id
integer | null

Id de usuario del miembro del equipo que guardó el correo en Flowyer.

saved_by
string | null

Nombre visible de ese miembro del equipo.

created_at
string <date-time> | null

Momento en que el correo se guardó en Flowyer (hora local de la zona del despacho). La marca de tiempo fiable para una paginación estable.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/emails?q=invoice&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "from_name": "string",
      "from_address": "string",
      "subject": "string",
      "sent_at": "2026-10-30T09:15:00+01:00",
      "size": 0,
      "extension": "string",
      "saved_by_user_id": 1234,
      "saved_by": "string",
      "created_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener correo electrónico

GET /api/agent/emails/{id}

Devuelve un correo electrónico guardado en un expediente con su cuerpo en texto sin formato (remitente, asunto, tamaño y quién lo guardó). El cuerpo HTML original nunca se devuelve. Responde 404 si el correo no existe o su expediente no es visible para el usuario titular de esta clave de API.

Ámbito
emails:read
Permiso de Flowyer
emails:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del correo electrónico.

Ejemplo: 1234

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 1234
matter
object | null

El expediente en el que está registrado el correo, o null para un correo sin expediente (guardado fuera de cualquier expediente).

Campos de matter
id
integer
case_number
string
from_name
string | null

Nombre visible de la parte externa (nunca un miembro del equipo; el almacén no tiene columna de dirección del envío).

from_address
string | null

Dirección SMTP de la parte externa.

subject
string | null
body
string | null

El cuerpo del mensaje como texto sin formato. El cuerpo HTML original no se devuelve nunca, de forma deliberada (HTML de terceros no fiable). Texto sin formato en la medida de lo posible: si el HTML original contenía <style>/<script>, su texto interno puede conservarse en él.

sent_at
string <date-time> | null

Cuándo se envió el mensaje. La zona horaria varía según la vía de entrada (IMAP almacena UTC; el complemento de Outlook, la hora local del despacho); created_at es la marca de tiempo fiable.

size
integer | null

Tamaño en bytes del archivo .eml/.msg almacenado.

extension
string | null

"msg" o "eml"; null en algunas filas antiguas.

saved_by_user_id
integer | null

Id de usuario del miembro del equipo que guardó el correo en Flowyer.

saved_by
string | null

Nombre visible de ese miembro del equipo.

created_at
string <date-time> | null

Cuándo se guardó el correo en Flowyer (hora local del despacho).

updated_at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/emails/1234' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 1234,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "from_name": "string",
    "from_address": "string",
    "subject": "string",
    "body": "string",
    "sent_at": "2026-10-30T09:15:00+01:00",
    "size": 0,
    "extension": "string",
    "saved_by_user_id": 1234,
    "saved_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00"
  }
}

Historial procesal

Listar historial procesal del expediente

GET /api/agent/matters/{id}/litigation

Muestra las entradas del historial procesal (pertörténet) de un expediente, empezando por el evento más reciente: una nota fechada con un título, una descripción en HTML y un lugar. Responde 404 si el expediente no es visible para el usuario.

Ámbito
litigation:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 4521
title
string

Título de la entrada. Texto sin formato.

Ejemplo: "Első tárgyalás elhalasztva"
description
string | null

Detalles de la entrada en HTML enriquecido, saneado en el servidor.

location
string | null

Dónde ocurrió (texto sin formato), p. ej. una sala de vistas; admite null.

event_date
string <date> | null

Día de la entrada, YYYY-MM-DD. Flowyer solo registra la fecha, no la hora.

user_id
integer | null

Autor (el usuario que creó la entrada).

created_by
string | null

Nombre visible del autor.

last_editor_id
integer | null

Usuario que editó la entrada por última vez.

last_editor
string | null

Nombre visible del último editor.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a litigation.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/litigation?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 4521,
      "title": "Első tárgyalás elhalasztva",
      "description": "string",
      "location": "string",
      "event_date": "2026-10-30",
      "user_id": 1234,
      "created_by": "string",
      "last_editor_id": 1234,
      "last_editor": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Crear entrada del historial procesal

POST /api/agent/matters/{id}/litigation

Añade una entrada del historial procesal (pertörténet) a un expediente: un título (texto sin formato, no se admiten "<"/">"), una descripción HTML opcional (saneada en el servidor), un lugar opcional y una fecha del evento (por defecto, hoy). Responde 404 si el expediente no es visible.

Ámbito
litigation:create
Permiso de Flowyer
cases:create

Parámetros de ruta

idobligatorio
integer>= 1

Expediente al que pertenece la entrada (debe ser visible).

Ejemplo: 1234

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

titleobligatorio
stringal menos 1 caracterescomo máximo 2000 caracteres

Título de la entrada, como máximo 2000 caracteres. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Első tárgyalás elhalasztva"
description
string | null

Detalles de la entrada. HTML enriquecido, saneado en el servidor con el perfil de la base de conocimiento.

location
string | nullcomo máximo 255 caracteres

Dónde ocurrió (texto sin formato, como máximo 255 caracteres); no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Fővárosi Törvényszék, 215. tárgyaló"
event_date
string <date> | null

Día de la entrada, YYYY-MM-DD. Por defecto, hoy (zona horaria del despacho).

Ejemplo: "2026-11-15"
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4521
title
string

Título de la entrada. Texto sin formato.

Ejemplo: "Első tárgyalás elhalasztva"
description
string | null

Detalles de la entrada en HTML enriquecido, saneado en el servidor.

location
string | null

Dónde ocurrió (texto sin formato), p. ej. una sala de vistas; admite null.

event_date
string <date> | null

Día de la entrada, YYYY-MM-DD. Flowyer solo registra la fecha, no la hora.

user_id
integer | null

Autor (el usuario que creó la entrada).

created_by
string | null

Nombre visible del autor.

last_editor_id
integer | null

Usuario que editó la entrada por última vez.

last_editor
string | null

Nombre visible del último editor.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a litigation.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4521
title
string

Título de la entrada. Texto sin formato.

Ejemplo: "Első tárgyalás elhalasztva"
description
string | null

Detalles de la entrada en HTML enriquecido, saneado en el servidor.

location
string | null

Dónde ocurrió (texto sin formato), p. ej. una sala de vistas; admite null.

event_date
string <date> | null

Día de la entrada, YYYY-MM-DD. Flowyer solo registra la fecha, no la hora.

user_id
integer | null

Autor (el usuario que creó la entrada).

created_by
string | null

Nombre visible del autor.

last_editor_id
integer | null

Usuario que editó la entrada por última vez.

last_editor
string | null

Nombre visible del último editor.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a litigation.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/litigation' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "title": "Első tárgyalás elhalasztva",
  "location": "Fővárosi Törvényszék, 215. tárgyaló",
  "event_date": "2026-11-15"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4521,
    "title": "Első tárgyalás elhalasztva",
    "description": "string",
    "location": "string",
    "event_date": "2026-10-30",
    "user_id": 1234,
    "created_by": "string",
    "last_editor_id": 1234,
    "last_editor": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Modificar entrada del historial procesal

PATCH /api/agent/litigation/{id}

Modifica una entrada del historial procesal (pertörténet): título, descripción, ubicación o fecha del evento. Solo se escriben los campos que envíe; la descripción se sanea en el servidor. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409.

Ámbito
litigation:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

title
string | nullal menos 1 caracterescomo máximo 2000 caracteres

Nuevo título, como máximo 2000 caracteres (texto sin formato; no se admiten "<"/">"). Omítalo para mantener el actual.

Patrón: ^[^<>]*$
Ejemplo: "Ítélethirdetés elhalasztva"
description
string | null

Nuevos detalles (HTML enriquecido, saneado). Omítalo para mantener el actual; null/vacío lo borra.

location
string | nullcomo máximo 255 caracteres

Nueva ubicación (texto sin formato, como máximo 255 caracteres; no se admiten "<"/">"). Omítalo para mantenerla; null/vacío la borra.

Patrón: ^[^<>]*$
event_date
string <date> | null

Nuevo día del evento, YYYY-MM-DD. Omítalo para mantenerlo; null lo borra.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4521
title
string

Título de la entrada. Texto sin formato.

Ejemplo: "Első tárgyalás elhalasztva"
description
string | null

Detalles de la entrada en HTML enriquecido, saneado en el servidor.

location
string | null

Dónde ocurrió (texto sin formato), p. ej. una sala de vistas; admite null.

event_date
string <date> | null

Día de la entrada, YYYY-MM-DD. Flowyer solo registra la fecha, no la hora.

user_id
integer | null

Autor (el usuario que creó la entrada).

created_by
string | null

Nombre visible del autor.

last_editor_id
integer | null

Usuario que editó la entrada por última vez.

last_editor
string | null

Nombre visible del último editor.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a litigation.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/litigation/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "title": "Ítélethirdetés elhalasztva"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4521,
    "title": "Első tárgyalás elhalasztva",
    "description": "string",
    "location": "string",
    "event_date": "2026-10-30",
    "user_id": 1234,
    "created_by": "string",
    "last_editor_id": 1234,
    "last_editor": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Registro de correspondencia

Listar registro de correspondencia

GET /api/agent/mail-register

Muestra las entradas del registro de correspondencia (Postakönyv) registradas en los expedientes que el usuario puede ver, de la más reciente a la más antigua. Permite filtrar por expediente, dirección, texto libre (asunto/remitente/destinatario/número de seguimiento) e intervalo de fechas. La correspondencia de los expedientes archivados se oculta, salvo que include_archived sea true.

Ámbito
mail_register:read
Permiso de Flowyer
mail:read

Parámetros de consulta

matter_id
integer>= 1

Solo las entradas de este expediente (debe ser visible para el usuario).

Ejemplo: 1234
direction
string

Solo las entradas de entrada (recibidas) o de salida (enviadas).

Valores admitidos: "incoming" "outgoing"
q
stringcomo máximo 100 caracteres

Búsqueda de texto libre en el asunto, el remitente, el destinatario, el receptor y el número de seguimiento (sin distinguir mayúsculas y minúsculas).

Ejemplo: "Kúria"
date_from
string <date>

Solo las entradas cuya fecha sea igual o posterior a este día (YYYY-MM-DD).

Ejemplo: "2026-01-01"
date_to
string <date>

Solo las entradas cuya fecha sea igual o anterior a este día (YYYY-MM-DD).

Ejemplo: "2026-12-31"
updated_since
string <date-time>

Solo las entradas modificadas en este momento o después (ISO 8601).

Ejemplo: "2026-10-01T00:00:00+02:00"
include_archived
boolean

Incluir las entradas de los expedientes archivados.

Valor por defecto: false
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de la entrada del registro de correspondencia (se usa con mail_register.get / .update).

Ejemplo: 4321
matter
object | null

El expediente en el que está registrada la entrada.

Campos de matter
id
integer
case_number
string
direction
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD (sin hora).

subject
string | null
sender
string | null

Feladó: el remitente (texto libre).

to
string | null

Címzett: el destinatario (texto libre).

recipient
string | null

Para una carta de entrada: el nombre visible del miembro del equipo que la recibió. Para una carta de salida: el destinatario o receptor en texto libre.

recipient_user_id
integer | null

Solo se informa en una carta de entrada cuyo receptor es un miembro del equipo (un id de usuario); null en una carta de salida.

electronic
boolean

True si el elemento se registró como electrónico (type_of_mail).

delivery_method_id
integer | null

Id del medio de entrega (mail_delivery_methods).

delivery_method
string | null

Etiqueta localizada del medio de entrega (Posta, Cégkapu, Perkapu, ...), o el valor de reserva electrónico/no electrónico en una fila antigua.

tracking_no
string | null

Azonosító: número de seguimiento.

folder_path
string | null
recorded_by_user_id
integer | null

El miembro del equipo que registró la entrada.

recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a mail_register.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/mail-register?matter_id=1234&q=K%C3%BAria&date_from=2026-01-01' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 4321,
      "matter": {
        "id": 1234,
        "case_number": "string"
      },
      "direction": "incoming",
      "date": "2026-10-30",
      "subject": "string",
      "sender": "string",
      "to": "string",
      "recipient": "string",
      "recipient_user_id": 1234,
      "electronic": true,
      "delivery_method_id": 1234,
      "delivery_method": "string",
      "tracking_no": "string",
      "folder_path": "string",
      "recorded_by_user_id": 1234,
      "recorded_by": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener entrada del registro de correspondencia

GET /api/agent/mail-register/{id}

Devuelve una entrada del registro de correspondencia (Postakönyv) por su id, con su updated_at (el token que admite mail_register.update). Responde 404 si la entrada no existe o su expediente no es visible para el usuario.

Ámbito
mail_register:read
Permiso de Flowyer
mail:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la entrada del registro de correspondencia.

Ejemplo: 4321

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer

Id de la entrada del registro de correspondencia (se usa con mail_register.get / .update).

Ejemplo: 4321
matter
object | null

El expediente en el que está registrada la entrada.

Campos de matter
id
integer
case_number
string
direction
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD (sin hora).

subject
string | null
sender
string | null

Feladó: el remitente (texto libre).

to
string | null

Címzett: el destinatario (texto libre).

recipient
string | null

Para una carta de entrada: el nombre visible del miembro del equipo que la recibió. Para una carta de salida: el destinatario o receptor en texto libre.

recipient_user_id
integer | null

Solo se informa en una carta de entrada cuyo receptor es un miembro del equipo (un id de usuario); null en una carta de salida.

electronic
boolean

True si el elemento se registró como electrónico (type_of_mail).

delivery_method_id
integer | null

Id del medio de entrega (mail_delivery_methods).

delivery_method
string | null

Etiqueta localizada del medio de entrega (Posta, Cégkapu, Perkapu, ...), o el valor de reserva electrónico/no electrónico en una fila antigua.

tracking_no
string | null

Azonosító: número de seguimiento.

folder_path
string | null
recorded_by_user_id
integer | null

El miembro del equipo que registró la entrada.

recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a mail_register.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/mail-register/4321' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "direction": "incoming",
    "date": "2026-10-30",
    "subject": "string",
    "sender": "string",
    "to": "string",
    "recipient": "string",
    "recipient_user_id": 1234,
    "electronic": true,
    "delivery_method_id": 1234,
    "delivery_method": "string",
    "tracking_no": "string",
    "folder_path": "string",
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear entrada del registro de correspondencia

POST /api/agent/mail-register

Registra una nueva entrada del registro de correspondencia (Postakönyv) en un expediente. Use recipient_user_id para una carta de entrada recibida por un miembro del equipo, o recipient (texto libre) para una de salida. delivery_method_id debe ser un medio conocido. Responde 404 si el expediente no es visible.

Ámbito
mail_register:create
Permiso de Flowyer
mail:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

matter_idobligatorio
integer>= 1

Expediente al que pertenece la entrada (debe ser visible).

Ejemplo: 1234
directionobligatorio
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
dateobligatorio
string <date>

Fecha postal o de registro, YYYY-MM-DD (sin hora).

Ejemplo: "2026-11-03"
subjectobligatorio
stringal menos 1 caracterescomo máximo 1000 caracteres

Asunto de la correspondencia. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Fellebbezés a Kúriához"
sender
string | nullcomo máximo 1000 caracteres

Feladó: el remitente (texto libre). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
to
string | nullcomo máximo 1000 caracteres

Címzett: el destinatario (texto libre). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
recipient
string | nullcomo máximo 1000 caracteres

Carta de salida: el destinatario o receptor en texto libre. No se admite junto con recipient_user_id. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
recipient_user_id
integer | null>= 1

Carta de entrada: el miembro del equipo que la recibió (un id de usuario de colleagues.list), almacenado como receptor numérico. No se admite junto con recipient.

electronic
boolean

Indica si el elemento es electrónico (type_of_mail); es independiente del medio de entrega. Valor predeterminado: false.

Valor por defecto: false
delivery_method_id
integer | null>= 1

Id del medio de entrega (mail_delivery_methods): p. ej., 1 Posta, 4 Cégkapu, 7 Perkapu. 422 si es desconocido.

tracking_no
string | nullcomo máximo 255 caracteres

Azonosító: número de seguimiento. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
folder_path
string | nullcomo máximo 1000 caracteres
Patrón: ^[^<>]*$
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer

Id de la entrada del registro de correspondencia (se usa con mail_register.get / .update).

Ejemplo: 4321
matter
object | null

El expediente en el que está registrada la entrada.

Campos de matter
id
integer
case_number
string
direction
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD (sin hora).

subject
string | null
sender
string | null

Feladó: el remitente (texto libre).

to
string | null

Címzett: el destinatario (texto libre).

recipient
string | null

Para una carta de entrada: el nombre visible del miembro del equipo que la recibió. Para una carta de salida: el destinatario o receptor en texto libre.

recipient_user_id
integer | null

Solo se informa en una carta de entrada cuyo receptor es un miembro del equipo (un id de usuario); null en una carta de salida.

electronic
boolean

True si el elemento se registró como electrónico (type_of_mail).

delivery_method_id
integer | null

Id del medio de entrega (mail_delivery_methods).

delivery_method
string | null

Etiqueta localizada del medio de entrega (Posta, Cégkapu, Perkapu, ...), o el valor de reserva electrónico/no electrónico en una fila antigua.

tracking_no
string | null

Azonosító: número de seguimiento.

folder_path
string | null
recorded_by_user_id
integer | null

El miembro del equipo que registró la entrada.

recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a mail_register.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer

Id de la entrada del registro de correspondencia (se usa con mail_register.get / .update).

Ejemplo: 4321
matter
object | null

El expediente en el que está registrada la entrada.

Campos de matter
id
integer
case_number
string
direction
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD (sin hora).

subject
string | null
sender
string | null

Feladó: el remitente (texto libre).

to
string | null

Címzett: el destinatario (texto libre).

recipient
string | null

Para una carta de entrada: el nombre visible del miembro del equipo que la recibió. Para una carta de salida: el destinatario o receptor en texto libre.

recipient_user_id
integer | null

Solo se informa en una carta de entrada cuyo receptor es un miembro del equipo (un id de usuario); null en una carta de salida.

electronic
boolean

True si el elemento se registró como electrónico (type_of_mail).

delivery_method_id
integer | null

Id del medio de entrega (mail_delivery_methods).

delivery_method
string | null

Etiqueta localizada del medio de entrega (Posta, Cégkapu, Perkapu, ...), o el valor de reserva electrónico/no electrónico en una fila antigua.

tracking_no
string | null

Azonosító: número de seguimiento.

folder_path
string | null
recorded_by_user_id
integer | null

El miembro del equipo que registró la entrada.

recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a mail_register.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/mail-register' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "matter_id": 1234,
  "direction": "incoming",
  "date": "2026-11-03",
  "subject": "Fellebbezés a Kúriához"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "direction": "incoming",
    "date": "2026-10-30",
    "subject": "string",
    "sender": "string",
    "to": "string",
    "recipient": "string",
    "recipient_user_id": 1234,
    "electronic": true,
    "delivery_method_id": 1234,
    "delivery_method": "string",
    "tracking_no": "string",
    "folder_path": "string",
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Actualizar entrada del registro de correspondencia

PATCH /api/agent/mail-register/{id}

Actualiza una entrada del registro de correspondencia (Postakönyv); solo se modifican los campos que envíe. La entrada permanece en su expediente. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409. Responde 404 si la entrada no es visible.

Ámbito
mail_register:update
Permiso de Flowyer
mail:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

direction
string | null

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD.

subject
string | nullal menos 1 caracterescomo máximo 1000 caracteres

Asunto. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
sender
string | nullcomo máximo 1000 caracteres

Feladó: el remitente (texto libre). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
to
string | nullcomo máximo 1000 caracteres

Címzett: el destinatario (texto libre). Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
recipient
string | nullcomo máximo 1000 caracteres

Carta de salida: el destinatario en texto libre. No se admite junto con recipient_user_id. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
recipient_user_id
integer | null>= 1

Carta de entrada: el miembro del equipo receptor (un id de usuario), almacenado como receptor numérico. No se admite junto con recipient.

electronic
boolean | null

Indica si el elemento es electrónico (type_of_mail).

delivery_method_id
integer | null>= 1

Id del medio de entrega (mail_delivery_methods); 422 si es desconocido.

tracking_no
string | nullcomo máximo 255 caracteres

Azonosító: número de seguimiento. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
folder_path
string | nullcomo máximo 1000 caracteres
Patrón: ^[^<>]*$

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id de la entrada del registro de correspondencia (se usa con mail_register.get / .update).

Ejemplo: 4321
matter
object | null

El expediente en el que está registrada la entrada.

Campos de matter
id
integer
case_number
string
direction
string

incoming = recibida, outgoing = enviada.

Valores admitidos: "incoming" "outgoing"
date
string <date> | null

Fecha postal o de registro, YYYY-MM-DD (sin hora).

subject
string | null
sender
string | null

Feladó: el remitente (texto libre).

to
string | null

Címzett: el destinatario (texto libre).

recipient
string | null

Para una carta de entrada: el nombre visible del miembro del equipo que la recibió. Para una carta de salida: el destinatario o receptor en texto libre.

recipient_user_id
integer | null

Solo se informa en una carta de entrada cuyo receptor es un miembro del equipo (un id de usuario); null en una carta de salida.

electronic
boolean

True si el elemento se registró como electrónico (type_of_mail).

delivery_method_id
integer | null

Id del medio de entrega (mail_delivery_methods).

delivery_method
string | null

Etiqueta localizada del medio de entrega (Posta, Cégkapu, Perkapu, ...), o el valor de reserva electrónico/no electrónico en una fila antigua.

tracking_no
string | null

Azonosító: número de seguimiento.

folder_path
string | null
recorded_by_user_id
integer | null

El miembro del equipo que registró la entrada.

recorded_by
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a mail_register.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la entrada mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/mail-register/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "direction": "incoming"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "direction": "incoming",
    "date": "2026-10-30",
    "subject": "string",
    "sender": "string",
    "to": "string",
    "recipient": "string",
    "recipient_user_id": 1234,
    "electronic": true,
    "delivery_method_id": 1234,
    "delivery_method": "string",
    "tracking_no": "string",
    "folder_path": "string",
    "recorded_by_user_id": 1234,
    "recorded_by": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Comentarios

Listar comentarios del expediente

GET /api/agent/matters/{id}/comments

Muestra los comentarios de un expediente, del más antiguo al más reciente: id, autor, cuerpo (HTML enriquecido) y el parent_id de una respuesta. Lista plana, no anidada: reconstruya los hilos de un nivel a partir de parent_id. Pase top_level_only para excluir las respuestas. Responde 404 si el expediente no es visible para el usuario.

Ámbito
comments:read
Permiso de Flowyer
cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente (debe ser visible).

Ejemplo: 1234

Parámetros de consulta

top_level_only
boolean

Solo los comentarios de primer nivel (excluye las respuestas). Valor predeterminado: false.

Valor por defecto: false
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 9876
matter_id
integer

El expediente (= case_id) al que pertenece el comentario.

parent_id
integer | null

El comentario de nivel superior al que responde; null para un comentario de nivel superior. Las respuestas tienen un solo nivel de profundidad.

author_user_id
integer | null

Id de usuario del autor (null para una importación antigua).

author_name
string | null

Nombre visible del autor, o null.

body
string

El comentario tal como está almacenado: HTML enriquecido, ya limpiado con HTMLPurifier en los comentarios escritos mediante esta API.

created_at
string <date-time> | null

Cuándo se publicó el comentario, ISO 8601 en la zona del despacho.

updated_at
string <date-time> | null

Token de bloqueo optimista: páselo a comments.update como expected_updated_at. Es un token opaco, NO una hora real (puede diferir unas horas del instante real); para mostrar fechas, use created_at y edited_at. null para un comentario antiguo que no lo tenga.

edited
boolean

True cuando el comentario se ha editado después de publicarse.

edited_at
string <date-time> | null

Momento en que se editó el comentario por última vez, ISO 8601 en la zona del despacho (el instante real, coherente con created_at). null si el comentario nunca se ha editado.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/comments?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 9876,
      "matter_id": 1234,
      "parent_id": 1234,
      "author_user_id": 1234,
      "author_name": "string",
      "body": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "edited": true,
      "edited_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Publicar comentario en el expediente

POST /api/agent/matters/{id}/comments

Publica un comentario en un expediente, o una respuesta de un nivel (parent_id = un comentario de PRIMER NIVEL del MISMO expediente). El cuerpo es HTML enriquecido y se sanea en el servidor antes de almacenarse. Responde 404 si el expediente no es visible y 422 si parent_id no es un comentario de primer nivel del expediente.

Ámbito
comments:create
Permiso de Flowyer
cases:create

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente (debe ser visible).

Ejemplo: 1234

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

bodyobligatorio
stringal menos 1 caracteres

El comentario, en HTML enriquecido (tal como lo genera TinyMCE). Se limpia en el servidor con HTMLPurifier antes de almacenarse. Como máximo 100000 caracteres.

Ejemplo: "<p>Egyetértek, a határidő tartható.</p>"
parent_id
integer | null>= 1

Responder a este comentario de PRIMER NIVEL del MISMO expediente (de comments.list, parent_id = null); omítalo para un nuevo comentario de primer nivel.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
matter_id
integer

El expediente (= case_id) al que pertenece el comentario.

parent_id
integer | null

El comentario de nivel superior al que responde; null para un comentario de nivel superior. Las respuestas tienen un solo nivel de profundidad.

author_user_id
integer | null

Id de usuario del autor (null para una importación antigua).

author_name
string | null

Nombre visible del autor, o null.

body
string

El comentario tal como está almacenado: HTML enriquecido, ya limpiado con HTMLPurifier en los comentarios escritos mediante esta API.

created_at
string <date-time> | null

Cuándo se publicó el comentario, ISO 8601 en la zona del despacho.

updated_at
string <date-time> | null

Token de bloqueo optimista: páselo a comments.update como expected_updated_at. Es un token opaco, NO una hora real (puede diferir unas horas del instante real); para mostrar fechas, use created_at y edited_at. null para un comentario antiguo que no lo tenga.

edited
boolean

True cuando el comentario se ha editado después de publicarse.

edited_at
string <date-time> | null

Momento en que se editó el comentario por última vez, ISO 8601 en la zona del despacho (el instante real, coherente con created_at). null si el comentario nunca se ha editado.

created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
matter_id
integer

El expediente (= case_id) al que pertenece el comentario.

parent_id
integer | null

El comentario de nivel superior al que responde; null para un comentario de nivel superior. Las respuestas tienen un solo nivel de profundidad.

author_user_id
integer | null

Id de usuario del autor (null para una importación antigua).

author_name
string | null

Nombre visible del autor, o null.

body
string

El comentario tal como está almacenado: HTML enriquecido, ya limpiado con HTMLPurifier en los comentarios escritos mediante esta API.

created_at
string <date-time> | null

Cuándo se publicó el comentario, ISO 8601 en la zona del despacho.

updated_at
string <date-time> | null

Token de bloqueo optimista: páselo a comments.update como expected_updated_at. Es un token opaco, NO una hora real (puede diferir unas horas del instante real); para mostrar fechas, use created_at y edited_at. null para un comentario antiguo que no lo tenga.

edited
boolean

True cuando el comentario se ha editado después de publicarse.

edited_at
string <date-time> | null

Momento en que se editó el comentario por última vez, ISO 8601 en la zona del despacho (el instante real, coherente con created_at). null si el comentario nunca se ha editado.

created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/comments' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "body": "<p>Egyetértek, a határidő tartható.</p>"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "matter_id": 1234,
    "parent_id": 1234,
    "author_user_id": 1234,
    "author_name": "string",
    "body": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "edited": true,
    "edited_at": "2026-10-30T09:15:00+01:00"
  },
  "created": true
}

Editar comentario propio del expediente

PATCH /api/agent/comments/{id}

Edita uno de sus PROPIOS comentarios (solo el cuerpo; HTML enriquecido, saneado en el servidor antes de guardarse). Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409. Responde 404 para un comentario que no es suyo o que está en un expediente que no puede ver.

Ámbito
comments:update
Permiso de Flowyer
cases:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

bodyobligatorio
stringal menos 1 caracteres

Nuevo cuerpo del comentario, HTML enriquecido (como el que genera TinyMCE). Se limpia en el servidor con HTMLPurifier antes de guardarse. Como máximo 100000 caracteres.

Ejemplo: "<p>Pontosítás: a határidő november 15.</p>"

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 9876
matter_id
integer

El expediente (= case_id) al que pertenece el comentario.

parent_id
integer | null

El comentario de nivel superior al que responde; null para un comentario de nivel superior. Las respuestas tienen un solo nivel de profundidad.

author_user_id
integer | null

Id de usuario del autor (null para una importación antigua).

author_name
string | null

Nombre visible del autor, o null.

body
string

El comentario tal como está almacenado: HTML enriquecido, ya limpiado con HTMLPurifier en los comentarios escritos mediante esta API.

created_at
string <date-time> | null

Cuándo se publicó el comentario, ISO 8601 en la zona del despacho.

updated_at
string <date-time> | null

Token de bloqueo optimista: páselo a comments.update como expected_updated_at. Es un token opaco, NO una hora real (puede diferir unas horas del instante real); para mostrar fechas, use created_at y edited_at. null para un comentario antiguo que no lo tenga.

edited
boolean

True cuando el comentario se ha editado después de publicarse.

edited_at
string <date-time> | null

Momento en que se editó el comentario por última vez, ISO 8601 en la zona del despacho (el instante real, coherente con created_at). null si el comentario nunca se ha editado.

updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/comments/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "body": "<p>Pontosítás: a határidő november 15.</p>"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 9876,
    "matter_id": 1234,
    "parent_id": 1234,
    "author_user_id": 1234,
    "author_name": "string",
    "body": "string",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "edited": true,
    "edited_at": "2026-10-30T09:15:00+01:00"
  },
  "updated": true
}

Vistas

Listar vistas del expediente

GET /api/agent/matters/{id}/trials

Muestra las vistas judiciales (tárgyalások) de un expediente: fecha, tribunal, lugar, los miembros del equipo asistentes y el juez, de la más reciente a la más antigua. Opcionalmente se puede filtrar por un intervalo de días from/to o por updated_since. Responde 404 si el expediente no es visible para el usuario.

Ámbito
trials:read
Permiso de Flowyer
trials:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del expediente.

Ejemplo: 1234

Parámetros de consulta

from
string <date>

Solo las vistas de este día o posteriores (YYYY-MM-DD), en la zona horaria del despacho.

Ejemplo: "2026-01-01"
to
string <date>

Solo las vistas de este día o anteriores (YYYY-MM-DD), en la zona horaria del despacho.

Ejemplo: "2026-12-31"
updated_since
string <date-time>

Solo las vistas modificadas en este momento ISO 8601 o después.

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 4321
matter
object

El expediente al que pertenece la vista.

Campos de matter
id
integer
case_number
string
date
string <date-time> | null

Fecha y hora de la vista, ISO 8601 en la zona horaria del despacho. Se almacena en UTC, por lo que debe comparar instantes y no el texto de la hora local.

Ejemplo: "2026-03-02T09:00:00+01:00"
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo: "required", "not_required" o null si no se ha indicado.

Valores admitidos: "required" "not_required"
court
object | null

El tribunal de la vista, obtenido del registro compartido de tribunales; null si no se ha indicado ningún tribunal.

Campos de court
id
integer
name
string
city
string | null
zip
string | null
address
string | null
source
string

Siempre "registry": el tribunal es una referencia al registro compartido de tribunales (courts.list), no texto libre.

place
string | null

Sala o lugar de la vista. Texto sin formato.

name_of_the_judge
string | null

Nombre del juez. Texto sin formato.

notes
string | null

Notas en texto libre sobre la vista. Texto sin formato.

responsibles
object[]

Miembros del equipo que asisten a la vista (ids de colleagues.list).

Campos de responsibles
user_id
integer
name
string | null
recorded_by
object | null

El miembro del equipo que registró la vista.

Campos de recorded_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a trials.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/matters/1234/trials?from=2026-01-01&to=2026-12-31&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 4321,
      "matter": {
        "id": 1234,
        "case_number": "string"
      },
      "date": "2026-03-02T09:00:00+01:00",
      "participation": "required",
      "court": {
        "id": 1234,
        "name": "string",
        "city": "string",
        "zip": "string",
        "address": "string",
        "source": "string"
      },
      "place": "string",
      "name_of_the_judge": "string",
      "notes": "string",
      "responsibles": [
        {
          "user_id": 1234,
          "name": "string"
        }
      ],
      "recorded_by": {
        "user_id": 1234,
        "name": "string"
      },
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener vista

GET /api/agent/trials/{id}

Devuelve una vista judicial (tárgyalás) con su expediente, su tribunal, los miembros del equipo asistentes y el token de bloqueo updated_at para trials.update. Responde 404 si la vista no existe o el usuario no puede ver su expediente.

Ámbito
trials:read
Permiso de Flowyer
trials:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la vista.

Ejemplo: 4321

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
matter
object

El expediente al que pertenece la vista.

Campos de matter
id
integer
case_number
string
date
string <date-time> | null

Fecha y hora de la vista, ISO 8601 en la zona horaria del despacho. Se almacena en UTC, por lo que debe comparar instantes y no el texto de la hora local.

Ejemplo: "2026-03-02T09:00:00+01:00"
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo: "required", "not_required" o null si no se ha indicado.

Valores admitidos: "required" "not_required"
court
object | null

El tribunal de la vista, obtenido del registro compartido de tribunales; null si no se ha indicado ningún tribunal.

Campos de court
id
integer
name
string
city
string | null
zip
string | null
address
string | null
source
string

Siempre "registry": el tribunal es una referencia al registro compartido de tribunales (courts.list), no texto libre.

place
string | null

Sala o lugar de la vista. Texto sin formato.

name_of_the_judge
string | null

Nombre del juez. Texto sin formato.

notes
string | null

Notas en texto libre sobre la vista. Texto sin formato.

responsibles
object[]

Miembros del equipo que asisten a la vista (ids de colleagues.list).

Campos de responsibles
user_id
integer
name
string | null
recorded_by
object | null

El miembro del equipo que registró la vista.

Campos de recorded_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a trials.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/trials/4321' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "date": "2026-03-02T09:00:00+01:00",
    "participation": "required",
    "court": {
      "id": 1234,
      "name": "string",
      "city": "string",
      "zip": "string",
      "address": "string",
      "source": "string"
    },
    "place": "string",
    "name_of_the_judge": "string",
    "notes": "string",
    "responsibles": [
      {
        "user_id": 1234,
        "name": "string"
      }
    ],
    "recorded_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear vista

POST /api/agent/matters/{id}/trials

Registra una vista judicial (tárgyalás) en un expediente: hora, un tribunal opcional (court_id de courts.list), la sala, el juez, las notas y los miembros del equipo asistentes. El expediente debe ser visible y no estar archivado; los asistentes reciben una notificación. Una hora sin desfase se interpreta en la zona del despacho.

Ámbito
trials:create
Permiso de Flowyer
trials:create

Parámetros de ruta

idobligatorio
integer>= 1

Expediente al que pertenece la vista (debe ser visible y no estar archivado).

Ejemplo: 1234

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

dateobligatorio
string <date-time>

Fecha y hora de la vista, ISO 8601. Si incluye desfase, se respeta; si no, se interpreta en la zona horaria del despacho. Se almacena en UTC.

Ejemplo: "2026-03-02T09:00:00+01:00"
court_id
integer | null>= 1

Tribunal de la vista: un id de courts.list (el registro compartido de tribunales). Omítalo si no se conoce el tribunal.

Ejemplo: 42
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo. Omítalo para dejarlo sin indicar.

Valores admitidos: "required" "not_required"
place
string | nullcomo máximo 1000 caracteres

Sala o lugar de la vista. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "II. emelet 205."
name_of_the_judge
string | nullcomo máximo 255 caracteres

Nombre del juez. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
notes
string | nullcomo máximo 10000 caracteres

Notas en texto libre sobre la vista. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
responsible_user_ids
integer[] | null

Ids de usuario de los miembros del equipo (de colleagues.list) que asisten a la vista.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
matter
object

El expediente al que pertenece la vista.

Campos de matter
id
integer
case_number
string
date
string <date-time> | null

Fecha y hora de la vista, ISO 8601 en la zona horaria del despacho. Se almacena en UTC, por lo que debe comparar instantes y no el texto de la hora local.

Ejemplo: "2026-03-02T09:00:00+01:00"
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo: "required", "not_required" o null si no se ha indicado.

Valores admitidos: "required" "not_required"
court
object | null

El tribunal de la vista, obtenido del registro compartido de tribunales; null si no se ha indicado ningún tribunal.

Campos de court
id
integer
name
string
city
string | null
zip
string | null
address
string | null
source
string

Siempre "registry": el tribunal es una referencia al registro compartido de tribunales (courts.list), no texto libre.

place
string | null

Sala o lugar de la vista. Texto sin formato.

name_of_the_judge
string | null

Nombre del juez. Texto sin formato.

notes
string | null

Notas en texto libre sobre la vista. Texto sin formato.

responsibles
object[]

Miembros del equipo que asisten a la vista (ids de colleagues.list).

Campos de responsibles
user_id
integer
name
string | null
recorded_by
object | null

El miembro del equipo que registró la vista.

Campos de recorded_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a trials.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
matter
object

El expediente al que pertenece la vista.

Campos de matter
id
integer
case_number
string
date
string <date-time> | null

Fecha y hora de la vista, ISO 8601 en la zona horaria del despacho. Se almacena en UTC, por lo que debe comparar instantes y no el texto de la hora local.

Ejemplo: "2026-03-02T09:00:00+01:00"
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo: "required", "not_required" o null si no se ha indicado.

Valores admitidos: "required" "not_required"
court
object | null

El tribunal de la vista, obtenido del registro compartido de tribunales; null si no se ha indicado ningún tribunal.

Campos de court
id
integer
name
string
city
string | null
zip
string | null
address
string | null
source
string

Siempre "registry": el tribunal es una referencia al registro compartido de tribunales (courts.list), no texto libre.

place
string | null

Sala o lugar de la vista. Texto sin formato.

name_of_the_judge
string | null

Nombre del juez. Texto sin formato.

notes
string | null

Notas en texto libre sobre la vista. Texto sin formato.

responsibles
object[]

Miembros del equipo que asisten a la vista (ids de colleagues.list).

Campos de responsibles
user_id
integer
name
string | null
recorded_by
object | null

El miembro del equipo que registró la vista.

Campos de recorded_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a trials.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/matters/1234/trials' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "date": "2026-03-02T09:00:00+01:00",
  "court_id": 42,
  "place": "II. emelet 205."
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "date": "2026-03-02T09:00:00+01:00",
    "participation": "required",
    "court": {
      "id": 1234,
      "name": "string",
      "city": "string",
      "zip": "string",
      "address": "string",
      "source": "string"
    },
    "place": "string",
    "name_of_the_judge": "string",
    "notes": "string",
    "responsibles": [
      {
        "user_id": 1234,
        "name": "string"
      }
    ],
    "recorded_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Actualizar vista

PATCH /api/agent/trials/{id}

Actualiza una vista judicial (tárgyalás): su hora, tribunal, lugar, juez, notas, indicador de asistencia y asistentes. Solo escribe los campos que envíe; envíe responsible_user_ids para sustituir la lista completa de asistentes. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409.

Ámbito
trials:update
Permiso de Flowyer
trials:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

date
string <date-time>

Nueva fecha y hora de la vista, ISO 8601 (se respeta el desfase; una hora sin zona se interpreta en la zona del despacho). Se almacena en UTC.

Ejemplo: "2026-03-02T09:00:00+01:00"
court_id
integer | null>= 1

Nuevo id de tribunal de courts.list; null para quitar el tribunal.

participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo; null para borrarlo.

Valores admitidos: "required" "not_required"
place
string | nullcomo máximo 1000 caracteres

Sala o lugar. Texto sin formato; no se admiten "<" ni ">". "" lo borra.

Patrón: ^[^<>]*$
name_of_the_judge
string | nullcomo máximo 255 caracteres

Nombre del juez. Texto sin formato; no se admiten "<" ni ">". "" lo borra.

Patrón: ^[^<>]*$
notes
string | nullcomo máximo 10000 caracteres

Notas en texto libre. Texto sin formato; no se admiten "<" ni ">". "" las borra.

Patrón: ^[^<>]*$
responsible_user_ids
integer[] | null

Conjunto completo de sustitución de los ids de usuario de los asistentes (de colleagues.list). Omítalo para dejar los asistentes sin cambios.

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
matter
object

El expediente al que pertenece la vista.

Campos de matter
id
integer
case_number
string
date
string <date-time> | null

Fecha y hora de la vista, ISO 8601 en la zona horaria del despacho. Se almacena en UTC, por lo que debe comparar instantes y no el texto de la hora local.

Ejemplo: "2026-03-02T09:00:00+01:00"
participation
string | null

Indica si es obligatoria la asistencia de un miembro del equipo: "required", "not_required" o null si no se ha indicado.

Valores admitidos: "required" "not_required"
court
object | null

El tribunal de la vista, obtenido del registro compartido de tribunales; null si no se ha indicado ningún tribunal.

Campos de court
id
integer
name
string
city
string | null
zip
string | null
address
string | null
source
string

Siempre "registry": el tribunal es una referencia al registro compartido de tribunales (courts.list), no texto libre.

place
string | null

Sala o lugar de la vista. Texto sin formato.

name_of_the_judge
string | null

Nombre del juez. Texto sin formato.

notes
string | null

Notas en texto libre sobre la vista. Texto sin formato.

responsibles
object[]

Miembros del equipo que asisten a la vista (ids de colleagues.list).

Campos de responsibles
user_id
integer
name
string | null
recorded_by
object | null

El miembro del equipo que registró la vista.

Campos de recorded_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a trials.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/trials/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "date": "2026-03-02T09:00:00+01:00"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "date": "2026-03-02T09:00:00+01:00",
    "participation": "required",
    "court": {
      "id": 1234,
      "name": "string",
      "city": "string",
      "zip": "string",
      "address": "string",
      "source": "string"
    },
    "place": "string",
    "name_of_the_judge": "string",
    "notes": "string",
    "responsibles": [
      {
        "user_id": 1234,
        "name": "string"
      }
    ],
    "recorded_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Tribunales

Listar tribunales

GET /api/agent/courts

Lista el registro compartido de tribunales (id, nombre, localidad) para el court_id de trials.create / trials.update. Con q (un nombre de tribunal tal como se oyó; tolera tildes, mayúsculas y pequeños errores tipográficos) responde con el estado exact/similar/none: solo "exact" se puede usar directamente con seguridad. Es el directorio de tribunales húngaros.

Ámbito
courts:read

Parámetros de consulta

q
stringcomo máximo 255 caracteres

Nombre del tribunal que se busca, tal como se oyó o se dictó, en cualquier orden de palabras. Omítalo para listar todos los tribunales.

Ejemplo: "Fővárosi Törvényszék"
limit
integer>= 1<= 500

Número máximo de tribunales devueltos (valor predeterminado: 200).

Valor por defecto: 200

Respuestas

200

OK.

dataobligatorio
object
Campos de data
status
string | null

Solo con q: exact = una coincidencia segura (su id se puede usar con seguridad), similar = coincidencia aproximada o varias coincidencias (confírmelo antes con el usuario), none = sin coincidencias (pregunte al usuario). Null sin q.

Valores admitidos: "exact" "similar" "none"
courts
object[]

Tribunales; con q, primero la mejor coincidencia; si no, por nombre.

Campos de courts
id
integer

Id del tribunal: páselo como court_id a trials.create / trials.update.

name
string

Nombre del tribunal tal como aparece en Flowyer.

city
string | null
zip
string | null
address
string | null
total
integer

Cuántos tribunales coincidían (sin q, todos los tribunales) antes de recortar la lista a limit.

truncated
boolean

True cuando coincidieron más tribunales de los devueltos: restrinja q o aumente limit.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/courts?q=F%C5%91v%C3%A1rosi%20T%C3%B6rv%C3%A9nysz%C3%A9k' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "status": "exact",
    "courts": [
      {
        "id": 1234,
        "name": "string",
        "city": "string",
        "zip": "string",
        "address": "string"
      }
    ],
    "total": 1,
    "truncated": true
  }
}

RR. HH.

Listar ausencias del equipo

GET /api/agent/hr/leaves

Lista las ausencias aprobadas del equipo (quién está o estará ausente): el miembro del equipo, las fechas de inicio y fin, el número de días laborables, una categoría anonimizada por privacidad (leave/unpaid; la baja por enfermedad se integra en leave y nunca es identificable) y el sustituto, si lo hay. Nunca devuelve el tipo de ausencia, las notas ni quién la aprobó.

Ámbito
hr:read
Permiso de Flowyer
hr-admin:read

Parámetros de consulta

user_id
integer>= 1

Solo las ausencias de este miembro del equipo. Un id de usuario central (de colleagues.list), asociado al empleado de la ausencia.

Ejemplo: 1234
on_date
string <date>

Quién está ausente exactamente este día (start_date <= on_date <= end_date). Si se indica, prevalece sobre date_from, date_to y timeframe.

date_from
string <date>

Solo las ausencias que siguen en curso en esta fecha o después (end_date >= date_from). Valor predeterminado: hoy, por lo que las ausencias totalmente pasadas quedan excluidas por defecto.

date_to
string <date>

Solo las ausencias que empiezan en esta fecha o antes (start_date <= date_to). Omítalo para un futuro sin límite.

timeframe
string

Condición adicional sobre la fecha de inicio respecto a hoy: current = ya iniciada (en curso), upcoming = aún no iniciada, all = sin condición adicional. Se ignora si se indica on_date.

Valores admitidos: "current" "upcoming" "all"
Valor por defecto: "all"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id de la solicitud de ausencia (solo una referencia; no es sensible).

user_id
integer

El miembro del equipo ausente (id de usuario central).

user
string | null

Nombre visible del miembro del equipo.

start_date
string <date>

Primer día de la ausencia (YYYY-MM-DD).

end_date
string <date>

Último día de la ausencia, incluido (YYYY-MM-DD).

days_count
number | null

Días laborables de ausencia. No revela el tipo.

category
string

Tipo de ausencia anonimizado por privacidad: las vacaciones anuales y la baja por enfermedad pasan a ser "leave" (la baja por enfermedad nunca es identificable); la ausencia no retribuida sigue siendo "unpaid". El tipo de ausencia original nunca se expone.

Valores admitidos: "leave" "unpaid"
status
string

Siempre "approved": solo se devuelven las ausencias aprobadas; las pending, rejected y cancelled nunca aparecen.

Valores admitidos: "approved"
substitute_user_id
integer | null

Miembro del equipo que sustituye durante esta ausencia (id de usuario central), o null.

substitute_user
string | null

Nombre visible del sustituto, o null.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/hr/leaves?user_id=1234&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 1234,
      "user_id": 1234,
      "user": "string",
      "start_date": "2026-10-30",
      "end_date": "2026-10-30",
      "days_count": 0,
      "category": "leave",
      "status": "approved",
      "substitute_user_id": 1234,
      "substitute_user": "string"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Calendario

Listar eventos del calendario

GET /api/agent/calendar/events

Lista los eventos del calendario que se solapan con un rango de fechas [from, to]: el calendario del despacho, el suyo propio y los calendarios compartidos con usted. Los eventos periódicos se devuelven una sola vez (is_recurring), NO desglosados. Ordenados por inicio. Un evento personal no compartido con usted nunca aparece.

Ámbito
calendar:read
Permiso de Flowyer
calendar-office:read

Parámetros de consulta

fromobligatorio
string <date-time>

Inicio del rango (incluido), ISO 8601. Se devuelven los eventos que se solapan con [from, to]. Una hora sin desfase se interpreta en la zona del despacho.

Ejemplo: "2026-03-01T00:00:00+01:00"
toobligatorio
string <date-time>

Fin del rango (incluido), ISO 8601. Debe ser igual o posterior a from (si no, 422) y como máximo 366 días después.

Ejemplo: "2026-03-31T23:59:59+01:00"
calendar_ids
integer[]

Restringe a estos ids de calendario contenedor; cada uno se cruza con los calendarios que usted puede ver, de modo que un id que no puede ver se descarta sin aviso. Omítalo para incluir todos los calendarios visibles.

include_recurring
boolean

Incluye los eventos maestros periódicos cuya regla se solapa con el rango (devueltos sin desglosar, is_recurring = true). Valor predeterminado: true.

Valor por defecto: true
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 5501
calendar
object

El calendario al que pertenece el evento.

Campos de calendar
id
integer | null

Id del calendario contenedor, o null para el calendario compartido implícito del despacho (un evento antiguo sin contenedor).

name
string | null
type
string

"office" = el calendario compartido del despacho (todos los usuarios del despacho pueden verlo y editarlo); "personal" = el calendario propio de un usuario, visible solo para su propietario y para aquellos con quienes se comparte.

Valores admitidos: "office" "personal"
owner
object | null

Propietario de un calendario personal; null para el calendario del despacho.

Campos de owner
user_id
integer
name
string | null
title
string | null

Título del evento. Texto sin formato.

description
string | null

Descripción del evento. Texto sin formato.

location
string | null

Ubicación. Texto sin formato.

participants
string | null

Participantes, texto libre. Texto sin formato.

start
string | null

Evento de día completo: la fecha de inicio "YYYY-MM-DD". Evento con hora: ISO 8601 en la zona horaria del despacho (el instante UTC almacenado).

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. En un evento de día completo, la fecha de fin está INCLUIDA (el valor almacenado, no el valor +1 día que usa una cuadrícula de calendario). Null cuando el evento no tiene fin.

all_day
boolean

True para un evento de día completo (start/end son fechas simples); false para un evento con hora (start/end son instantes ISO 8601).

color
string | null

Color de visualización, p. ej. "#2c7be5".

is_recurring
boolean

True cuando el evento es un maestro periódico. Los eventos periódicos se devuelven una sola vez, NO desglosados en ocurrencias, y no se pueden modificar mediante calendar.events.update.

recurrence
object | null

La regla de repetición de un maestro periódico, o null para un evento único. Solo lectura.

Campos de recurrence
freq
string | null

daily | weekly | monthly | yearly.

interval
integer | null
byweekday
string | null

Códigos de día de la semana separados por comas (p. ej. "MO,WE,FR").

until
string | null
count
integer | null
created_by
object | null

El miembro del equipo que creó el evento.

Campos de created_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a calendar.events.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/calendar/events?from=2026-03-01T00%3A00%3A00%2B01%3A00&to=2026-03-31T23%3A59%3A59%2B01%3A00&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 5501,
      "calendar": {
        "id": 1234,
        "name": "string",
        "type": "office",
        "owner": {
          "user_id": 1234,
          "name": "string"
        }
      },
      "title": "string",
      "description": "string",
      "location": "string",
      "participants": "string",
      "start": "2026-03-02T09:00:00+01:00",
      "end": "string",
      "all_day": true,
      "color": "string",
      "is_recurring": true,
      "recurrence": {
        "freq": "string",
        "interval": 0,
        "byweekday": "string",
        "until": "string",
        "count": 0
      },
      "created_by": {
        "user_id": 1234,
        "name": "string"
      },
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener evento del calendario

GET /api/agent/calendar/events/{id}

Devuelve un evento del calendario con su calendario, el resumen de repetición y el token de bloqueo updated_at para calendar.events.update. Responde 404 si el evento no existe o su calendario no es visible para el usuario.

Ámbito
calendar:read
Permiso de Flowyer
calendar-office:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del evento.

Ejemplo: 5501

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 5501
calendar
object

El calendario al que pertenece el evento.

Campos de calendar
id
integer | null

Id del calendario contenedor, o null para el calendario compartido implícito del despacho (un evento antiguo sin contenedor).

name
string | null
type
string

"office" = el calendario compartido del despacho (todos los usuarios del despacho pueden verlo y editarlo); "personal" = el calendario propio de un usuario, visible solo para su propietario y para aquellos con quienes se comparte.

Valores admitidos: "office" "personal"
owner
object | null

Propietario de un calendario personal; null para el calendario del despacho.

Campos de owner
user_id
integer
name
string | null
title
string | null

Título del evento. Texto sin formato.

description
string | null

Descripción del evento. Texto sin formato.

location
string | null

Ubicación. Texto sin formato.

participants
string | null

Participantes, texto libre. Texto sin formato.

start
string | null

Evento de día completo: la fecha de inicio "YYYY-MM-DD". Evento con hora: ISO 8601 en la zona horaria del despacho (el instante UTC almacenado).

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. En un evento de día completo, la fecha de fin está INCLUIDA (el valor almacenado, no el valor +1 día que usa una cuadrícula de calendario). Null cuando el evento no tiene fin.

all_day
boolean

True para un evento de día completo (start/end son fechas simples); false para un evento con hora (start/end son instantes ISO 8601).

color
string | null

Color de visualización, p. ej. "#2c7be5".

is_recurring
boolean

True cuando el evento es un maestro periódico. Los eventos periódicos se devuelven una sola vez, NO desglosados en ocurrencias, y no se pueden modificar mediante calendar.events.update.

recurrence
object | null

La regla de repetición de un maestro periódico, o null para un evento único. Solo lectura.

Campos de recurrence
freq
string | null

daily | weekly | monthly | yearly.

interval
integer | null
byweekday
string | null

Códigos de día de la semana separados por comas (p. ej. "MO,WE,FR").

until
string | null
count
integer | null
created_by
object | null

El miembro del equipo que creó el evento.

Campos de created_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a calendar.events.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/calendar/events/5501' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 5501,
    "calendar": {
      "id": 1234,
      "name": "string",
      "type": "office",
      "owner": {
        "user_id": 1234,
        "name": "string"
      }
    },
    "title": "string",
    "description": "string",
    "location": "string",
    "participants": "string",
    "start": "2026-03-02T09:00:00+01:00",
    "end": "string",
    "all_day": true,
    "color": "string",
    "is_recurring": true,
    "recurrence": {
      "freq": "string",
      "interval": 0,
      "byweekday": "string",
      "until": "string",
      "count": 0
    },
    "created_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear evento del calendario

POST /api/agent/calendar/events

Crea un único evento del calendario (con hora o de día completo). Por defecto, en su propio calendario personal; pase calendar_id para usar el calendario del despacho o cualquier calendario que pueda editar. Un start/end con hora respeta un desfase ISO 8601; el fin de un evento de día completo está incluido. Aquí no se crean eventos periódicos.

Ámbito
calendar:create
Permiso de Flowyer
calendar-office:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

titleobligatorio
stringal menos 1 caracterescomo máximo 255 caracteres

Título del evento. Texto sin formato; no se admiten "<" ni ">" (se incluye sin escapar en la notificación de recordatorio).

Patrón: ^[^<>]*$
Ejemplo: "Ügyfél egyeztetés"
startobligatorio
string

Día completo (all_day true): una fecha "YYYY-MM-DD". Con hora (all_day false): ISO 8601; se respeta el desfase y una hora sin zona se interpreta en la zona del despacho.

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. Valor predeterminado = start. En un evento de día completo, la fecha de fin está INCLUIDA. No puede ser anterior a start (si no, 422).

all_day
boolean

Si el evento es de día completo. Valor predeterminado: false (con hora).

Valor por defecto: false
calendar_id
integer | null>= 1

El calendario en el que se crea el evento. Valor predeterminado: su propio calendario personal o, si no tiene, el calendario del despacho. Debe tener permiso de edición sobre él (el calendario del despacho lo puede editar cualquier usuario del despacho; un calendario personal, solo su propietario o alguien con quien se haya compartido para editar); si no, 403. Solo donde la función de calendario personal esté activada.

location
string | nullcomo máximo 1000 caracteres

Ubicación. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
description
string | nullcomo máximo 10000 caracteres

Descripción, texto sin formato (no HTML); no se admiten "<" ni ">".

Patrón: ^[^<>]*$
participants
string | nullcomo máximo 1000 caracteres

Participantes, texto libre. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
color
string | nullcomo máximo 32 caracteres

Color de visualización, p. ej. "#2c7be5".

Patrón: ^#?[A-Za-z0-9_-]{1,31}$
idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 5501
calendar
object

El calendario al que pertenece el evento.

Campos de calendar
id
integer | null

Id del calendario contenedor, o null para el calendario compartido implícito del despacho (un evento antiguo sin contenedor).

name
string | null
type
string

"office" = el calendario compartido del despacho (todos los usuarios del despacho pueden verlo y editarlo); "personal" = el calendario propio de un usuario, visible solo para su propietario y para aquellos con quienes se comparte.

Valores admitidos: "office" "personal"
owner
object | null

Propietario de un calendario personal; null para el calendario del despacho.

Campos de owner
user_id
integer
name
string | null
title
string | null

Título del evento. Texto sin formato.

description
string | null

Descripción del evento. Texto sin formato.

location
string | null

Ubicación. Texto sin formato.

participants
string | null

Participantes, texto libre. Texto sin formato.

start
string | null

Evento de día completo: la fecha de inicio "YYYY-MM-DD". Evento con hora: ISO 8601 en la zona horaria del despacho (el instante UTC almacenado).

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. En un evento de día completo, la fecha de fin está INCLUIDA (el valor almacenado, no el valor +1 día que usa una cuadrícula de calendario). Null cuando el evento no tiene fin.

all_day
boolean

True para un evento de día completo (start/end son fechas simples); false para un evento con hora (start/end son instantes ISO 8601).

color
string | null

Color de visualización, p. ej. "#2c7be5".

is_recurring
boolean

True cuando el evento es un maestro periódico. Los eventos periódicos se devuelven una sola vez, NO desglosados en ocurrencias, y no se pueden modificar mediante calendar.events.update.

recurrence
object | null

La regla de repetición de un maestro periódico, o null para un evento único. Solo lectura.

Campos de recurrence
freq
string | null

daily | weekly | monthly | yearly.

interval
integer | null
byweekday
string | null

Códigos de día de la semana separados por comas (p. ej. "MO,WE,FR").

until
string | null
count
integer | null
created_by
object | null

El miembro del equipo que creó el evento.

Campos de created_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a calendar.events.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 5501
calendar
object

El calendario al que pertenece el evento.

Campos de calendar
id
integer | null

Id del calendario contenedor, o null para el calendario compartido implícito del despacho (un evento antiguo sin contenedor).

name
string | null
type
string

"office" = el calendario compartido del despacho (todos los usuarios del despacho pueden verlo y editarlo); "personal" = el calendario propio de un usuario, visible solo para su propietario y para aquellos con quienes se comparte.

Valores admitidos: "office" "personal"
owner
object | null

Propietario de un calendario personal; null para el calendario del despacho.

Campos de owner
user_id
integer
name
string | null
title
string | null

Título del evento. Texto sin formato.

description
string | null

Descripción del evento. Texto sin formato.

location
string | null

Ubicación. Texto sin formato.

participants
string | null

Participantes, texto libre. Texto sin formato.

start
string | null

Evento de día completo: la fecha de inicio "YYYY-MM-DD". Evento con hora: ISO 8601 en la zona horaria del despacho (el instante UTC almacenado).

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. En un evento de día completo, la fecha de fin está INCLUIDA (el valor almacenado, no el valor +1 día que usa una cuadrícula de calendario). Null cuando el evento no tiene fin.

all_day
boolean

True para un evento de día completo (start/end son fechas simples); false para un evento con hora (start/end son instantes ISO 8601).

color
string | null

Color de visualización, p. ej. "#2c7be5".

is_recurring
boolean

True cuando el evento es un maestro periódico. Los eventos periódicos se devuelven una sola vez, NO desglosados en ocurrencias, y no se pueden modificar mediante calendar.events.update.

recurrence
object | null

La regla de repetición de un maestro periódico, o null para un evento único. Solo lectura.

Campos de recurrence
freq
string | null

daily | weekly | monthly | yearly.

interval
integer | null
byweekday
string | null

Códigos de día de la semana separados por comas (p. ej. "MO,WE,FR").

until
string | null
count
integer | null
created_by
object | null

El miembro del equipo que creó el evento.

Campos de created_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a calendar.events.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/calendar/events' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "title": "Ügyfél egyeztetés",
  "start": "2026-03-02T09:00:00+01:00"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 5501,
    "calendar": {
      "id": 1234,
      "name": "string",
      "type": "office",
      "owner": {
        "user_id": 1234,
        "name": "string"
      }
    },
    "title": "string",
    "description": "string",
    "location": "string",
    "participants": "string",
    "start": "2026-03-02T09:00:00+01:00",
    "end": "string",
    "all_day": true,
    "color": "string",
    "is_recurring": true,
    "recurrence": {
      "freq": "string",
      "interval": 0,
      "byweekday": "string",
      "until": "string",
      "count": 0
    },
    "created_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Modificar evento del calendario

PATCH /api/agent/calendar/events/{id}

Modifica un único evento del calendario: título, start/end, all_day, ubicación, descripción, participantes, color. Solo escribe los campos que envíe; "" borra ubicación/descripción/participantes. Un evento periódico responde 422. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409.

Ámbito
calendar:update
Permiso de Flowyer
calendar-office:modify

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

title
stringal menos 1 caracterescomo máximo 255 caracteres

Nuevo título. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
start
string

Nuevo inicio. Día completo: "YYYY-MM-DD". Con hora: ISO 8601 (se respeta el desfase y una hora sin zona se interpreta en la zona del despacho). Se recodifica si cambia all_day.

end
string | null

Nuevo fin, con la misma codificación que start; "" lo borra. En un evento de día completo, la fecha de fin está incluida. No puede ser anterior a start (si no, 422).

all_day
boolean

Si se envía, start/end se recodifican en consecuencia; si se omite, se usa el valor actual de all_day de la fila.

location
string | nullcomo máximo 1000 caracteres

Ubicación. Texto sin formato; no se admiten "<" ni ">". "" la borra.

Patrón: ^[^<>]*$
description
string | nullcomo máximo 10000 caracteres

Descripción, texto sin formato (no HTML); no se admiten "<" ni ">". "" la borra.

Patrón: ^[^<>]*$
participants
string | nullcomo máximo 1000 caracteres

Participantes, texto libre. Texto sin formato; no se admiten "<" ni ">". "" lo borra.

Patrón: ^[^<>]*$
color
string | nullcomo máximo 32 caracteres

Color de visualización, p. ej. "#2c7be5". "" lo borra.

Patrón: ^#?[A-Za-z0-9_-]{1,31}$

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 5501
calendar
object

El calendario al que pertenece el evento.

Campos de calendar
id
integer | null

Id del calendario contenedor, o null para el calendario compartido implícito del despacho (un evento antiguo sin contenedor).

name
string | null
type
string

"office" = el calendario compartido del despacho (todos los usuarios del despacho pueden verlo y editarlo); "personal" = el calendario propio de un usuario, visible solo para su propietario y para aquellos con quienes se comparte.

Valores admitidos: "office" "personal"
owner
object | null

Propietario de un calendario personal; null para el calendario del despacho.

Campos de owner
user_id
integer
name
string | null
title
string | null

Título del evento. Texto sin formato.

description
string | null

Descripción del evento. Texto sin formato.

location
string | null

Ubicación. Texto sin formato.

participants
string | null

Participantes, texto libre. Texto sin formato.

start
string | null

Evento de día completo: la fecha de inicio "YYYY-MM-DD". Evento con hora: ISO 8601 en la zona horaria del despacho (el instante UTC almacenado).

Ejemplo: "2026-03-02T09:00:00+01:00"
end
string | null

Misma codificación que start. En un evento de día completo, la fecha de fin está INCLUIDA (el valor almacenado, no el valor +1 día que usa una cuadrícula de calendario). Null cuando el evento no tiene fin.

all_day
boolean

True para un evento de día completo (start/end son fechas simples); false para un evento con hora (start/end son instantes ISO 8601).

color
string | null

Color de visualización, p. ej. "#2c7be5".

is_recurring
boolean

True cuando el evento es un maestro periódico. Los eventos periódicos se devuelven una sola vez, NO desglosados en ocurrencias, y no se pueden modificar mediante calendar.events.update.

recurrence
object | null

La regla de repetición de un maestro periódico, o null para un evento único. Solo lectura.

Campos de recurrence
freq
string | null

daily | weekly | monthly | yearly.

interval
integer | null
byweekday
string | null

Códigos de día de la semana separados por comas (p. ej. "MO,WE,FR").

until
string | null
count
integer | null
created_by
object | null

El miembro del equipo que creó el evento.

Campos de created_by
user_id
integer
name
string | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a calendar.events.update como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó el registro mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/calendar/events/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "title": "string"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 5501,
    "calendar": {
      "id": 1234,
      "name": "string",
      "type": "office",
      "owner": {
        "user_id": 1234,
        "name": "string"
      }
    },
    "title": "string",
    "description": "string",
    "location": "string",
    "participants": "string",
    "start": "2026-03-02T09:00:00+01:00",
    "end": "string",
    "all_day": true,
    "color": "string",
    "is_recurring": true,
    "recurrence": {
      "freq": "string",
      "interval": 0,
      "byweekday": "string",
      "until": "string",
      "count": 0
    },
    "created_by": {
      "user_id": 1234,
      "name": "string"
    },
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Reservas de citas

Listar reservas de cita

GET /api/agent/bookings

Lista las reservas de cita del despacho (időpontfoglalások), de la más reciente a la más antigua. Opcionalmente se pueden filtrar por un rango de días from/to (zona horaria de la reserva), por un abogado (user_id), por un estado o por updated_since. Todo titular de una clave ve las reservas de todos los abogados.

Ámbito
bookings:read

Parámetros de consulta

from
string <date>

Solo las reservas de este día (YYYY-MM-DD) o posteriores, comparado literalmente con la fecha en la zona de la reserva.

Ejemplo: "2026-01-01"
to
string <date>

Solo las reservas de este día (YYYY-MM-DD) o anteriores.

Ejemplo: "2026-12-31"
user_id
integer>= 1

Filtra por un único abogado (user_id de colleagues.list). Omítalo para incluir a todos los abogados del despacho.

status
string

Filtra por estado.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
updated_since
string <date-time>

Solo las reservas modificadas en esta hora ISO 8601 o después (updated_at es una hora sin zona horaria, expresada en la zona del despacho).

limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/bookings?from=2026-01-01&to=2026-12-31&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 4321,
      "booking_number": "string",
      "status": "pending",
      "source": "flowyer",
      "lawyer": {
        "user_id": 1234,
        "name": "string"
      },
      "date": "2026-10-30",
      "start_time": "string",
      "end_time": "string",
      "start": "2026-10-30T09:15:00+01:00",
      "end": "2026-10-30T09:15:00+01:00",
      "timezone": "string",
      "location_preference": "office",
      "meeting_link": "string",
      "client": {
        "name": "string",
        "email": "info@example.hu",
        "phone": "string",
        "description": "string"
      },
      "gdpr_consent": true,
      "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
      "cancel_reason": "string",
      "payment": {
        "status": "none",
        "method": "card",
        "amount": 0,
        "currency": "string",
        "invoice_number": "string"
      },
      "confirmed_at": "2026-10-30T09:15:00+01:00",
      "cancelled_at": "2026-10-30T09:15:00+01:00",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener reserva de cita

GET /api/agent/bookings/{id}

Devuelve una reserva de cita con el abogado, los datos del cliente, los instantes de inicio y fin, el estado de pago y el token de bloqueo updated_at para bookings.update / .confirm / .cancel. Responde 404 si la reserva no existe en este despacho.

Ámbito
bookings:read

Parámetros de ruta

idobligatorio
integer>= 1

Id de la reserva.

Ejemplo: 4321

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/bookings/4321' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "booking_number": "string",
    "status": "pending",
    "source": "flowyer",
    "lawyer": {
      "user_id": 1234,
      "name": "string"
    },
    "date": "2026-10-30",
    "start_time": "string",
    "end_time": "string",
    "start": "2026-10-30T09:15:00+01:00",
    "end": "2026-10-30T09:15:00+01:00",
    "timezone": "string",
    "location_preference": "office",
    "meeting_link": "string",
    "client": {
      "name": "string",
      "email": "info@example.hu",
      "phone": "string",
      "description": "string"
    },
    "gdpr_consent": true,
    "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
    "cancel_reason": "string",
    "payment": {
      "status": "none",
      "method": "card",
      "amount": 0,
      "currency": "string",
      "invoice_number": "string"
    },
    "confirmed_at": "2026-10-30T09:15:00+01:00",
    "cancelled_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Crear reserva de cita

POST /api/agent/bookings

Books an appointment and emails the client the confirmation. Needs a free slot, else 409; source is "manual". Two-step: a call with no confirm_token returns confirmation_required + a preview + token; re-call with the token to proceed. An Idempotency-Key replay never re-books.

Ámbito
bookings:create

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

user_idobligatorio
integer>= 1

Abogado con el que es la cita (user_id de colleagues.list; debe ser un miembro activo del equipo del despacho).

Ejemplo: 42
dateobligatorio
string <date>

Día de la cita (YYYY-MM-DD) en la zona horaria de la reserva.

Ejemplo: "2026-03-02"
timeobligatorio
string

Hora de inicio HH:MM (24 h) en la zona horaria de la reserva. La hora de fin es time + la duración de franja del despacho. Debe ser un hueco libre.

Patrón: ^([01]\d|2[0-3]):[0-5]\d$
Ejemplo: "09:00"
client_nameobligatorio
stringcomo máximo 255 caracteres

Nombre del cliente. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
Ejemplo: "Kovács Anna"
client_emailobligatorio
stringcomo máximo 255 caracteres

Correo electrónico del cliente: destinatario de la confirmación.

Ejemplo: "anna@example.com"
client_phone
string | nullcomo máximo 50 caracteres

Teléfono del cliente. Texto sin formato.

Patrón: ^[^<>]*$
client_description
string | nullcomo máximo 2000 caracteres

Asunto / notas del cliente. Texto sin formato.

Patrón: ^[^<>]*$
location_preference
string

Consulta en el despacho o en línea. Valor predeterminado: "office".

Valores admitidos: "office" "online"
Valor por defecto: "office"
meeting_link
string | nullcomo máximo 500 caracteres

URL de la reunión en línea (http/https), para una consulta en línea.

gdpr_consent
boolean

Registra el consentimiento del cliente para el tratamiento de datos. Valor predeterminado: true (el personal del despacho reserva en nombre del cliente).

Valor por defecto: true
auto_confirm
boolean

Si es true (o el despacho tiene activada la confirmación automática), la reserva se crea ya confirmada: se ejecuta la sincronización del calendario y el cliente recibe una confirmación en lugar de una solicitud. En caso contrario, queda en pending.

Valor por defecto: false
confirm_token
string

Two-step send confirmation. Leave empty on the first call; the action then returns "confirmation_required" with a preview and a confirm_token. To actually book and email the client, call again with the SAME arguments and this field set to that token.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/bookings' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "user_id": 42,
  "date": "2026-03-02",
  "time": "09:00",
  "client_name": "Kovács Anna",
  "client_email": "anna@example.com"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "booking_number": "string",
    "status": "pending",
    "source": "flowyer",
    "lawyer": {
      "user_id": 1234,
      "name": "string"
    },
    "date": "2026-10-30",
    "start_time": "string",
    "end_time": "string",
    "start": "2026-10-30T09:15:00+01:00",
    "end": "2026-10-30T09:15:00+01:00",
    "timezone": "string",
    "location_preference": "office",
    "meeting_link": "string",
    "client": {
      "name": "string",
      "email": "info@example.hu",
      "phone": "string",
      "description": "string"
    },
    "gdpr_consent": true,
    "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
    "cancel_reason": "string",
    "payment": {
      "status": "none",
      "method": "card",
      "amount": 0,
      "currency": "string",
      "invoice_number": "string"
    },
    "confirmed_at": "2026-10-30T09:15:00+01:00",
    "cancelled_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Modificar reserva de cita

PATCH /api/agent/bookings/{id}

Reprograma (date + time juntos, comprobando de nuevo que el hueco esté libre) o edita una reserva (teléfono, notas, enlace de la reunión, ubicación). Solo escribe los campos que envíe. Notifica la reprogramación al abogado, nunca al cliente. Pase expected_updated_at de su última lectura; una escritura obsoleta responde 409.

Ámbito
bookings:update

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

date
string <date>

Nuevo día (YYYY-MM-DD) en la zona horaria de la reserva. Envíe date Y time juntos para reprogramar.

Ejemplo: "2026-03-05"
time
string

Nueva hora de inicio HH:MM. La hora de fin se recalcula a partir de la duración de franja del despacho. Envíe date Y time juntos.

Patrón: ^([01]\d|2[0-3]):[0-5]\d$
Ejemplo: "11:00"
client_phone
string | nullcomo máximo 50 caracteres

Teléfono del cliente. Texto sin formato. "" lo borra.

Patrón: ^[^<>]*$
client_description
string | nullcomo máximo 2000 caracteres

Asunto / notas. Texto sin formato. "" lo borra.

Patrón: ^[^<>]*$
meeting_link
string | nullcomo máximo 500 caracteres

URL de la reunión en línea (http/https). "" la borra.

location_preference
string

Consulta en el despacho o en línea.

Valores admitidos: "office" "online"

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/bookings/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "date": "2026-03-05",
  "time": "11:00"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "booking_number": "string",
    "status": "pending",
    "source": "flowyer",
    "lawyer": {
      "user_id": 1234,
      "name": "string"
    },
    "date": "2026-10-30",
    "start_time": "string",
    "end_time": "string",
    "start": "2026-10-30T09:15:00+01:00",
    "end": "2026-10-30T09:15:00+01:00",
    "timezone": "string",
    "location_preference": "office",
    "meeting_link": "string",
    "client": {
      "name": "string",
      "email": "info@example.hu",
      "phone": "string",
      "description": "string"
    },
    "gdpr_consent": true,
    "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
    "cancel_reason": "string",
    "payment": {
      "status": "none",
      "method": "card",
      "amount": 0,
      "currency": "string",
      "invoice_number": "string"
    },
    "confirmed_at": "2026-10-30T09:15:00+01:00",
    "cancelled_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Confirmar reserva de cita

POST /api/agent/bookings/{id}/confirm

Confirms a pending booking and emails the client (with the meeting link for online). Only pending, else 409. Two-step: a call with no confirm_token returns confirmation_required + a preview + token; re-call with the token to proceed. Optional expected_updated_at lock token.

Ámbito
bookings:send

Parámetros de ruta

idobligatorio
integer>= 1

Id de la reserva.

Ejemplo: 4321

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

Token opcional de bloqueo optimista: el updated_at de su última lectura. Si la reserva ha cambiado desde entonces, la API responde 409 y usted debe volver a leerla antes de reintentar.

meeting_link
string | nullcomo máximo 500 caracteres

URL de la reunión en línea (http/https) que se establece en la reserva antes de enviar el correo electrónico de confirmación.

confirm_token
string

Two-step send confirmation. Leave empty on the first call; the action then returns "confirmation_required" with a preview and a confirm_token. To actually confirm and email the client, call again with the SAME arguments and this field set to that token.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/bookings/4321/confirm' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "booking_number": "string",
    "status": "pending",
    "source": "flowyer",
    "lawyer": {
      "user_id": 1234,
      "name": "string"
    },
    "date": "2026-10-30",
    "start_time": "string",
    "end_time": "string",
    "start": "2026-10-30T09:15:00+01:00",
    "end": "2026-10-30T09:15:00+01:00",
    "timezone": "string",
    "location_preference": "office",
    "meeting_link": "string",
    "client": {
      "name": "string",
      "email": "info@example.hu",
      "phone": "string",
      "description": "string"
    },
    "gdpr_consent": true,
    "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
    "cancel_reason": "string",
    "payment": {
      "status": "none",
      "method": "card",
      "amount": 0,
      "currency": "string",
      "invoice_number": "string"
    },
    "confirmed_at": "2026-10-30T09:15:00+01:00",
    "cancelled_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Cancelar reserva de cita

POST /api/agent/bookings/{id}/cancel

Cancels a booking and emails the client and lawyer. Already cancelled/completed answers 409. A paid booking is never refunded. Two-step: a call with no confirm_token returns confirmation_required + a preview + token; re-call with the token to proceed. Optional expected_updated_at.

Ámbito
bookings:send

Parámetros de ruta

idobligatorio
integer>= 1

Id de la reserva.

Ejemplo: 4321

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

Token opcional de bloqueo optimista: el updated_at de su última lectura. Si la reserva ha cambiado desde entonces, la API responde 409.

reason
string | nullcomo máximo 255 caracteres

Motivo registrado como cancel_reason y mostrado en el correo electrónico de cancelación. Texto sin formato; no se admiten "<" ni ">".

Patrón: ^[^<>]*$
confirm_token
string

Two-step send confirmation. Leave empty on the first call; the action then returns "confirmation_required" with a preview and a confirm_token. To actually cancel and email the client, call again with the SAME arguments and this field set to that token.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer
Ejemplo: 4321
booking_number
string

Número de reserva legible, p. ej. "#B-0001".

status
string

pending = pendiente de confirmación por el abogado; confirmed = aprobada; cancelled/completed; awaiting_payment/expired corresponden al flujo de pago previo a la confirmación.

Valores admitidos: "pending" "confirmed" "cancelled" "completed" "awaiting_payment" "expired"
source
string

Origen de la reserva. Una reserva creada mediante la API es "manual".

Valores admitidos: "flowyer" "website" "embed_widget" "manual"
lawyer
object | null

El abogado (user_id de colleagues.list) con el que es la cita.

Campos de lawyer
user_id
integer
name
string | null
date
string <date> | null

Fecha de calendario en la zona horaria de la reserva (YYYY-MM-DD), almacenada literalmente.

start_time
string | null

Hora de inicio HH:MM en la zona horaria de la reserva.

end_time
string | null

Hora de fin HH:MM en la zona horaria de la reserva.

start
string <date-time> | null

Instante ISO 8601 inequívoco del inicio, compuesto con la zona horaria de la reserva. Utilícelo para comparar instantes entre zonas.

end
string <date-time> | null

Instante ISO 8601 inequívoco del fin.

timezone
string

La zona horaria de la reserva (booking_settings.timezone), p. ej. "Europe/Budapest". Rige date, start_time y end_time.

location_preference
string

Si la consulta es en el despacho o en línea.

Valores admitidos: "office" "online"
meeting_link
string | null

URL de la reunión en línea, si está definida.

client
object

El cliente externo que reservó: nombre, correo electrónico, teléfono y asunto/notas. Datos personales, solo para el personal del despacho.

Campos de client
name
string | null
email
string | null
phone
string | null
description
string | null
gdpr_consent
boolean

Si consta registrado el consentimiento del cliente para el tratamiento de datos.

gdpr_consent_at
string <date-time> | null

Cuándo se registró el consentimiento.

cancel_reason
string | null

Motivo registrado al cancelar.

payment
object

Estado de pago de solo lectura. La API nunca modifica el pago; las tarifas de reserva se gestionan en Flowyer.

Campos de payment
status
string
Valores admitidos: "none" "awaiting" "partial" "paid" "refunded"
method
string | null
Valores admitidos: "card" "transfer"
amount
number | null
currency
string | null
invoice_number
string | null
confirmed_at
string <date-time> | null
cancelled_at
string <date-time> | null
created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a bookings.update / bookings.confirm / bookings.cancel como expected_updated_at.

created_via_api
object | null

Presente cuando un agente externo creó la reserva mediante esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/bookings/4321/cancel' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "booking_number": "string",
    "status": "pending",
    "source": "flowyer",
    "lawyer": {
      "user_id": 1234,
      "name": "string"
    },
    "date": "2026-10-30",
    "start_time": "string",
    "end_time": "string",
    "start": "2026-10-30T09:15:00+01:00",
    "end": "2026-10-30T09:15:00+01:00",
    "timezone": "string",
    "location_preference": "office",
    "meeting_link": "string",
    "client": {
      "name": "string",
      "email": "info@example.hu",
      "phone": "string",
      "description": "string"
    },
    "gdpr_consent": true,
    "gdpr_consent_at": "2026-10-30T09:15:00+01:00",
    "cancel_reason": "string",
    "payment": {
      "status": "none",
      "method": "card",
      "amount": 0,
      "currency": "string",
      "invoice_number": "string"
    },
    "confirmed_at": "2026-10-30T09:15:00+01:00",
    "cancelled_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  }
}

Tickets

Listar tickets

GET /api/agent/tickets

Muestra los tickets de soporte que el usuario puede ver (visibilidad por buzón), empezando por la actividad más reciente. Permite filtrar por estado (por defecto open_states = new+open+pending; "all" incluye los cerrados), buzón, persona asignada, correo electrónico del solicitante o texto libre en el asunto, el solicitante o el número de ticket.

Ámbito
tickets:read
Permiso de Flowyer
ticketing:read

Parámetros de consulta

status
string

open_states (predeterminado) = new+open+pending (la vista predeterminada de la web); "all" incluye los cerrados; o un estado concreto.

Valores admitidos: "new" "open" "pending" "closed" "open_states" "all"
Valor por defecto: "open_states"
mailbox_id
integer>= 1

Solo los tickets de este buzón. Un buzón que el usuario no puede ver devuelve una lista vacía (nunca una filtración).

Ejemplo: 7
assigned_to_user_id
integer>= 0

Solo los tickets asignados a este miembro del equipo (id de colleagues.list); 0 = solo los tickets sin asignar. Omítalo para cualquier persona asignada.

requester_email
stringcomo máximo 255 caracteres

Solo los tickets cuyo correo electrónico de solicitante externo coincida exactamente (sin distinguir mayúsculas y minúsculas).

Ejemplo: "ugyfel@example.com"
q
stringcomo máximo 100 caracteres

Búsqueda de texto libre en el asunto, el nombre o correo electrónico del solicitante y el número de ticket (sin distinguir mayúsculas y minúsculas).

Ejemplo: "számla"
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id del ticket (se usa con tickets.get / tickets.update).

Ejemplo: 4321
ticket_number
string | null

Número de ticket legible, p. ej., FLW-000123.

subject
string | null
status
string
Valores admitidos: "new" "open" "pending" "closed"
priority
string
Valores admitidos: "low" "normal" "high"
mailbox
object | null

El buzón por el que llegó el ticket (registro central).

Campos de mailbox
id
integer
email
string | null
display_name
string | null
requester
object

La persona externa que escribió.

Campos de requester
email
string | null
name
string | null
assigned_to
object | null

El miembro del equipo al que está asignado el ticket, o null si no está asignado.

Campos de assigned_to
user_id
integer
name
string | null
matter
object | null

El expediente vinculado al ticket, o null.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente vinculado al ticket, o null.

Campos de client
id
integer
name
string
last_message_at
string <date-time> | null

Hora de la actividad más reciente del hilo; la lista se ordena por este valor, empezando por la más reciente.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a tickets.update como expected_updated_at.

created_via_api
object | null

Presente si el ticket se creó a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/tickets?mailbox_id=7&requester_email=ugyfel%40example.com&q=sz%C3%A1mla' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 4321,
      "ticket_number": "string",
      "subject": "string",
      "status": "new",
      "priority": "low",
      "mailbox": {
        "id": 1234,
        "email": "info@example.hu",
        "display_name": "string"
      },
      "requester": {
        "email": "info@example.hu",
        "name": "string"
      },
      "assigned_to": {
        "user_id": 1234,
        "name": "string"
      },
      "matter": {
        "id": 1234,
        "case_number": "string"
      },
      "client": {
        "id": 1234,
        "name": "string"
      },
      "last_message_at": "2026-10-30T09:15:00+01:00",
      "created_at": "2026-10-30T09:15:00+01:00",
      "updated_at": "2026-10-30T09:15:00+01:00",
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Obtener ticket

GET /api/agent/tickets/{id}

Devuelve un ticket de soporte con su hilo de mensajes (del más antiguo al más reciente) y el expediente o cliente vinculado. Responde 404 si el ticket no existe o está en un buzón que el usuario no puede ver. La lectura nunca modifica el ticket (un ticket NEW no pasa a OPEN).

Ámbito
tickets:read
Permiso de Flowyer
ticketing:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del ticket.

Ejemplo: 4321

Parámetros de consulta

messages_limit
integer | null>= 1<= 500

Devolver solo los N mensajes más recientes del hilo (presentados igualmente del más antiguo al más reciente). Omítalo para obtener el hilo completo.

Respuestas

200

OK.

dataobligatorio
object
Campos de data
id
integer

Id del ticket (se usa con tickets.get / tickets.update).

Ejemplo: 4321
ticket_number
string | null

Número de ticket legible, p. ej., FLW-000123.

subject
string | null
status
string
Valores admitidos: "new" "open" "pending" "closed"
priority
string
Valores admitidos: "low" "normal" "high"
mailbox
object | null

El buzón por el que llegó el ticket (registro central).

Campos de mailbox
id
integer
email
string | null
display_name
string | null
requester
object

La persona externa que escribió.

Campos de requester
email
string | null
name
string | null
assigned_to
object | null

El miembro del equipo al que está asignado el ticket, o null si no está asignado.

Campos de assigned_to
user_id
integer
name
string | null
matter
object | null

El expediente vinculado al ticket, o null.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente vinculado al ticket, o null.

Campos de client
id
integer
name
string
last_message_at
string <date-time> | null

Hora de la actividad más reciente del hilo; la lista se ordena por este valor, empezando por la más reciente.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a tickets.update como expected_updated_at.

created_via_api
object | null

Presente si el ticket se creó a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
messages
object[]

El hilo de mensajes, del más antiguo al más reciente.

Campos de messages
id
integer
direction
string

in = del solicitante, out = respuesta o acuse automático enviado desde el buzón, note = interna.

Valores admitidos: "in" "out" "note"
from
object
Campos de from
email
string | null
name
string | null
to
object[]
Campos de to
email
string
name
string | null
cc
object[]
Campos de cc
email
string
name
string | null
sent_status
string | null

Estado de entrega de un mensaje saliente; null para in/note.

Valores admitidos: "pending" "sent" "failed" "scheduled"
body_text
string | null

Cuerpo del mensaje en texto sin formato. El cuerpo HTML se omite deliberadamente para mantener el hilo compacto; si el texto almacenado está vacío, se genera a partir del HTML.

has_attachments
boolean
author
object | null

El miembro del equipo que escribió un mensaje out/note; null para un mensaje entrante.

Campos de author
user_id
integer
name
string | null
created_at
string <date-time> | null
linked_matter
object | null

El expediente vinculado al ticket (igual que matter).

Campos de linked_matter
id
integer
case_number
string
linked_client
object | null

El cliente vinculado al ticket (igual que client).

Campos de linked_client
id
integer
name
string
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/tickets/4321' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "ticket_number": "string",
    "subject": "string",
    "status": "new",
    "priority": "low",
    "mailbox": {
      "id": 1234,
      "email": "info@example.hu",
      "display_name": "string"
    },
    "requester": {
      "email": "info@example.hu",
      "name": "string"
    },
    "assigned_to": {
      "user_id": 1234,
      "name": "string"
    },
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "last_message_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    },
    "messages": [
      {
        "id": 1234,
        "direction": "in",
        "from": {
          "email": "info@example.hu",
          "name": "string"
        },
        "to": [
          {
            "email": "info@example.hu",
            "name": "string"
          }
        ],
        "cc": [
          {
            "email": "info@example.hu",
            "name": "string"
          }
        ],
        "sent_status": "pending",
        "body_text": "string",
        "has_attachments": true,
        "author": {
          "user_id": 1234,
          "name": "string"
        },
        "created_at": "2026-10-30T09:15:00+01:00"
      }
    ],
    "linked_matter": {
      "id": 1234,
      "case_number": "string"
    },
    "linked_client": {
      "id": 1234,
      "name": "string"
    }
  }
}

Responder al ticket

POST /api/agent/tickets/{id}/reply

Replies to a support ticket and emails it to the external requester. Rich HTML, sanitised server-side. Two-step: a call with no confirm_token returns confirmation_required + a preview + token; re-call with the token to proceed. The same Idempotency-Key never resends.

Ámbito
tickets:reply
Permiso de Flowyer
ticketing:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del ticket (debe ser visible según la ACL del buzón).

Ejemplo: 4321

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

body_htmlobligatorio
stringal menos 1 caracteres

La respuesta, en HTML enriquecido (tal como lo genera TinyMCE). Se limpia en el servidor con HTMLPurifier antes de almacenarse y antes de enviarse. Como máximo 100000 caracteres; se rechaza si tras el saneamiento queda vacía.

Ejemplo: "<p>Köszönjük megkeresését, csatoltan küldjük a választ.</p>"
cc
string[]como máximo 10 elementos

Destinatarios adicionales en Cc (como máximo 10). El solicitante y el buzón se excluyen automáticamente; una dirección no válida responde 422.

status
string

Estado del ticket que se establece tras responder (por defecto "pending" = a la espera del solicitante). Registra un evento de cambio de estado.

Valores admitidos: "new" "open" "pending" "closed"
Valor por defecto: "pending"
append_signature
boolean

Añadir la firma de tickets guardada del usuario de la clave SOLO al correo SALIENTE (nunca se almacena en el hilo).

Valor por defecto: false
confirm_token
string

Two-step send confirmation. Leave empty on the first call; the action then returns "confirmation_required" with a preview and a confirm_token. To actually send, call again with the SAME arguments and this field set to that token.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
ticket_id
integer
Ejemplo: 4321
message_id
integer

Id de la fila saliente de ticket_messages creada.

Ejemplo: 98765
direction
string

Siempre "out".

sent_status
string | null

"pending" en el momento de la creación; el envío asíncrono lo cambia después a sent/failed.

Valores admitidos: "pending" "sent" "failed" "scheduled"
status
string

El estado del ticket después de la respuesta.

Valores admitidos: "new" "open" "pending" "closed"
created_at
string <date-time> | null
created_via_api
object | null

Presente si la respuesta se creó a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
ticket_id
integer
Ejemplo: 4321
message_id
integer

Id de la fila saliente de ticket_messages creada.

Ejemplo: 98765
direction
string

Siempre "out".

sent_status
string | null

"pending" en el momento de la creación; el envío asíncrono lo cambia después a sent/failed.

Valores admitidos: "pending" "sent" "failed" "scheduled"
status
string

El estado del ticket después de la respuesta.

Valores admitidos: "new" "open" "pending" "closed"
created_at
string <date-time> | null
created_via_api
object | null

Presente si la respuesta se creó a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/tickets/4321/reply' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "body_html": "<p>Köszönjük megkeresését, csatoltan küldjük a választ.</p>"
}'

Ejemplos de respuesta

{
  "data": {
    "ticket_id": 4321,
    "message_id": 98765,
    "direction": "string",
    "sent_status": "pending",
    "status": "new",
    "created_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "created": true
}

Cambiar estado del ticket

PATCH /api/agent/tickets/{id}

Cambia el estado de un ticket (new, open, pending o closed). "closed" establece closed_at; cualquier otro estado lo borra. Pase expected_updated_at de su última lectura; un cambio en conflicto responde 409. Responde 404 si el ticket no es visible.

Ámbito
tickets:update
Permiso de Flowyer
ticketing:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del registro que se va a modificar.

Cuerpo de la solicitud application/json

expected_updated_at
string <date-time> | null

El valor de updated_at de su lectura más reciente de este registro (obligatorio siempre que el registro lo tenga). Si el registro ha cambiado desde entonces (lo ha editado un miembro del equipo), la API responde 409 y debe volver a leerlo antes de reintentar. Un registro antiguo cuyo updated_at es null admite null.

statusobligatorio
string

El nuevo estado. "closed" establece closed_at; cualquier otro estado lo borra.

Valores admitidos: "new" "open" "pending" "closed"
Ejemplo: "open"

Respuestas

200

Actualizado.

dataobligatorio
object
Campos de data
id
integer

Id del ticket (se usa con tickets.get / tickets.update).

Ejemplo: 4321
ticket_number
string | null

Número de ticket legible, p. ej., FLW-000123.

subject
string | null
status
string
Valores admitidos: "new" "open" "pending" "closed"
priority
string
Valores admitidos: "low" "normal" "high"
mailbox
object | null

El buzón por el que llegó el ticket (registro central).

Campos de mailbox
id
integer
email
string | null
display_name
string | null
requester
object

La persona externa que escribió.

Campos de requester
email
string | null
name
string | null
assigned_to
object | null

El miembro del equipo al que está asignado el ticket, o null si no está asignado.

Campos de assigned_to
user_id
integer
name
string | null
matter
object | null

El expediente vinculado al ticket, o null.

Campos de matter
id
integer
case_number
string
client
object | null

El cliente vinculado al ticket, o null.

Campos de client
id
integer
name
string
last_message_at
string <date-time> | null

Hora de la actividad más reciente del hilo; la lista se ordena por este valor, empezando por la más reciente.

created_at
string <date-time> | null
updated_at
string <date-time> | null

Páselo a tickets.update como expected_updated_at.

created_via_api
object | null

Presente si el ticket se creó a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
updated
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

El registro ha cambiado desde que lo leyó (record_conflict: expected_updated_at ya no coincide; vuelva a leerlo y reintente con el nuevo updated_at).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X PATCH 'https://www.flowyer.es/api/agent/tickets/1234' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_updated_at": "2026-10-30T09:15:00+01:00",
  "status": "open"
}'

Ejemplos de respuesta

{
  "data": {
    "id": 4321,
    "ticket_number": "string",
    "subject": "string",
    "status": "new",
    "priority": "low",
    "mailbox": {
      "id": 1234,
      "email": "info@example.hu",
      "display_name": "string"
    },
    "requester": {
      "email": "info@example.hu",
      "name": "string"
    },
    "assigned_to": {
      "user_id": 1234,
      "name": "string"
    },
    "matter": {
      "id": 1234,
      "case_number": "string"
    },
    "client": {
      "id": 1234,
      "name": "string"
    },
    "last_message_at": "2026-10-30T09:15:00+01:00",
    "created_at": "2026-10-30T09:15:00+01:00",
    "updated_at": "2026-10-30T09:15:00+01:00",
    "created_via_api": {
      "kind": "key",
      "key_id": 1234,
      "key_name": "string",
      "user_id": 1234,
      "user": "string",
      "at": "2026-10-30T09:15:00+01:00"
    }
  },
  "updated": true
}

Portal del cliente

Listar portales del cliente

GET /api/agent/portals

Muestra los portales del cliente (hilos) a los que el usuario puede acceder: el expediente, los participantes del lado del cliente, el número de mensajes y de participantes y la hora del último mensaje, empezando por el más reciente. Opcionalmente se puede filtrar por un expediente (matter_id). Un expediente tiene como máximo un portal.

Ámbito
portal:read
Permiso de Flowyer
client-portal:read, cases:read

Parámetros de consulta

matter_id
integer>= 1

Solo el portal de este expediente (404 matter_not_visible si el expediente no es visible). Un expediente tiene como máximo un portal.

Ejemplo: 1234
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

Id del portal (hilo): el identificador para portal.messages.list y portal.reply.

Ejemplo: 57
matter
object

El expediente al que pertenece el portal.

Campos de matter
id
integer
case_number
string
client_participants
object[]

Los participantes externos del lado del cliente con los que se comunica el despacho.

Campos de client_participants
name
string | null
kind
string

client = un mandante, contact = un contacto del cliente, email = un acceso antiguo solo por correo electrónico.

Valores admitidos: "client" "contact" "email"
participant_count
integer

Número de participantes activos (equipo y cliente).

message_count
integer

Número de mensajes no eliminados del hilo.

last_message_at
string <date-time> | null

Momento en que se publicó el mensaje no eliminado más reciente, ISO 8601 en la zona del despacho; null para un hilo vacío.

unread_for_me
integer | null

Mensajes no leídos de la fila de participante del propio usuario que actúa; null si el usuario que actúa no es participante de este portal.

created_at
string <date-time> | null
paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/portals?matter_id=1234&limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 57,
      "matter": {
        "id": 1234,
        "case_number": "string"
      },
      "client_participants": [
        {
          "name": "string",
          "kind": "client"
        }
      ],
      "participant_count": 0,
      "message_count": 0,
      "last_message_at": "2026-10-30T09:15:00+01:00",
      "unread_for_me": 0,
      "created_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Listar mensajes del portal

GET /api/agent/portals/{id}/messages

Muestra los mensajes de un hilo del portal del cliente, del más antiguo al más reciente, con el autor (equipo o cliente), el cuerpo en texto sin formato y los metadatos de los adjuntos, si los hay. Responde 404 si el portal no existe o no es accesible. No marca los mensajes como leídos.

Ámbito
portal:read
Permiso de Flowyer
client-portal:read, cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del portal (debe ser accesible).

Ejemplo: 57

Parámetros de consulta

include_deleted
boolean

Incluir los mensajes eliminados (su cuerpo aparece vacío). Valor predeterminado: false.

Valor por defecto: false
limit
integer>= 1<= 100

Tamaño de página, 1-100. Valor predeterminado: 25.

Valor por defecto: 25
Ejemplo: 25
offset
integer>= 0

Número de registros que se omiten. Use offset + limit de la página anterior para obtener la siguiente; pagination.total es el recuento completo.

Valor por defecto: 0
Ejemplo: 0

Respuestas

200

OK.

dataobligatorio
object[]
Campos de data
id
integer

portal_messages.id.

Ejemplo: 8012
author
object

Quién escribió el mensaje.

Campos de author
participant_id
integer | null
name
string | null
kind
string

staff = un miembro del equipo del despacho, client = el cliente externo.

Valores admitidos: "staff" "client"
direction
string

from_firm = un autor del equipo, from_client = el cliente externo.

Valores admitidos: "from_firm" "from_client"
body
string

El mensaje en texto sin formato (<br> convertido en saltos de línea). Cadena vacía para un mensaje eliminado.

attachment
object | null

Metadatos del adjunto cuando el mensaje tiene un documento; su descarga queda fuera del alcance. Null si no hay ninguno.

Campos de attachment
portal_document_id
integer
file_name
string
is_deleted
boolean
deleted_at
string <date-time> | null
created_at
string <date-time> | null

Momento en que se publicó el mensaje, ISO 8601 en la zona del despacho.

paginationobligatorio
object
Campos de pagination
limitobligatorio
integer
offsetobligatorio
integer
totalobligatorio
integer

Número total de registros coincidentes.

400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl 'https://www.flowyer.es/api/agent/portals/57/messages?limit=25' \
  -H 'Authorization: Bearer flw_...'

Ejemplos de respuesta

{
  "data": [
    {
      "id": 8012,
      "author": {
        "participant_id": 1234,
        "name": "string",
        "kind": "staff"
      },
      "direction": "from_firm",
      "body": "string",
      "attachment": {
        "portal_document_id": 1234,
        "file_name": "string"
      },
      "is_deleted": true,
      "deleted_at": "2026-10-30T09:15:00+01:00",
      "created_at": "2026-10-30T09:15:00+01:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

Responder en el portal del cliente

POST /api/agent/portals/{id}/messages

Posts a staff reply in a client portal thread; the client sees it and gets an e-mail notice. Plain text, escaped on store. Two-step: a call with no confirm_token returns confirmation_required + a preview + token; re-call with the token to proceed. 404 if not accessible.

Ámbito
portal:reply
Permiso de Flowyer
client-portal:read, cases:read

Parámetros de ruta

idobligatorio
integer>= 1

Id del portal en el que se responde (debe ser accesible).

Ejemplo: 57

Parámetros de cabecera

Idempotency-Key
stringcomo máximo 128 caracteres

Recomendado en toda creación. Un valor único por operación lógica (p. ej. un UUID). El mismo valor devuelve el mismo registro: reintentar con él devuelve el registro creado la primera vez en lugar de crear un segundo. Valores distintos siempre crean registros distintos. Los clientes que no pueden enviar cabeceras pueden pasar el mismo valor en el campo idempotency_key del cuerpo. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$

Cuerpo de la solicitud application/json

bodyobligatorio
stringal menos 1 caracterescomo máximo 20000 caracteres

La respuesta, en texto sin formato. Se admiten los corchetes angulares, que se escapan al almacenarse. Como máximo 20000 caracteres.

Ejemplo: "Tisztelt Ügyfelünk! A beadványt ma benyújtottuk."
confirm_token
string

Two-step send confirmation. Leave empty on the first call; the action then returns "confirmation_required" with a preview and a confirm_token. To actually post the reply and notify the client, call again with the SAME arguments and this field set to that token.

idempotency_key
stringcomo máximo 128 caracteres

Misma función que la cabecera Idempotency-Key, para clientes que no pueden enviar cabeceras personalizadas. Letras, dígitos, _, -, : o ., como máximo 128 caracteres.

Patrón: ^[A-Za-z0-9_\-:.]{1,128}$
Ejemplo: "b8f1c2e0-6f7a-4d2e-9c1b-2a3d4e5f6a7b"

Respuestas

201

Creado.

dataobligatorio
object
Campos de data
message
object

La respuesta publicada.

Campos de message
id
integer
Ejemplo: 8012
author
object

El usuario del equipo que actúa y que publicó la respuesta.

Campos de author
participant_id
integer | null
name
string | null
kind
string

staff = un miembro del equipo del despacho, client = el cliente externo.

Valores admitidos: "staff" "client"
direction
string

Siempre "from_firm" para una respuesta publicada a través de esta API.

Valores admitidos: "from_firm" "from_client"
body
string

El mensaje publicado en texto sin formato.

created_at
string <date-time> | null
portal
object

El portal (hilo) y su expediente en el que se publicó la respuesta.

Campos de portal
id
integer
matter
object
Campos de matter
id
integer
case_number
string
created_via_api
object | null

Procedencia del mensaje creado a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: true
200

Repetición idempotente: esta Idempotency-Key (o, sin clave, una solicitud idéntica en un plazo de 120 segundos) ya creó el registro; se devuelve de nuevo y no se ha creado nada nuevo.

dataobligatorio
object
Campos de data
message
object

La respuesta publicada.

Campos de message
id
integer
Ejemplo: 8012
author
object

El usuario del equipo que actúa y que publicó la respuesta.

Campos de author
participant_id
integer | null
name
string | null
kind
string

staff = un miembro del equipo del despacho, client = el cliente externo.

Valores admitidos: "staff" "client"
direction
string

Siempre "from_firm" para una respuesta publicada a través de esta API.

Valores admitidos: "from_firm" "from_client"
body
string

El mensaje publicado en texto sin formato.

created_at
string <date-time> | null
portal
object

El portal (hilo) y su expediente en el que se publicó la respuesta.

Campos de portal
id
integer
matter
object
Campos de matter
id
integer
case_number
string
created_via_api
object | null

Procedencia del mensaje creado a través de esta API.

Campos de created_via_api
kind
string

"key": creado con una clave de API estática; "oauth": creado por una aplicación conectada mediante OAuth.

Valores admitidos: "key" "oauth"
key_id
integer

Id de la clave de API (kind "key") o de la aplicación conectada (kind "oauth"); ambos se numeran por separado.

key_name
string

Nombre que el usuario dio a la clave de API, p. ej. "Grok integration", o el nombre de la aplicación conectada para kind "oauth", p. ej. "Claude".

user_id
integer
user
string | null
at
string <date-time> | null
created
boolean
Valor: false
idempotent_replay
boolean
Valor: true
400

Solicitud mal formada: cuerpo JSON no válido, host incorrecto (use el host www.) o solicitud ilegible.

401

La clave falta, no es válida, se ha revocado o ha caducado, o su usuario ya no está activo.

403

Falta el ámbito (scope_missing), falta el permiso del módulo de Flowyer (module_forbidden), la API está desactivada para el despacho, la licencia ha caducado o el despacho está archivado.

404

Endpoint desconocido, o el registro no existe / no es visible para el usuario. replay_not_visible: esta Idempotency-Key (o, sin clave, una solicitud idéntica) ya creó el registro (details.record_id), pero desde entonces se ha eliminado o no es visible para el usuario; no se ha creado nada nuevo, no vuelva a crearlo.

405

Método no disponible en esta ruta (DELETE y PUT nunca lo están; PATCH solo donde se ofrece una actualización).

409

La Idempotency-Key se utilizó para otro tipo de recurso (idempotency_key_reused) o, sin clave, se está procesando ahora mismo una solicitud idéntica (duplicate_in_progress; reintente en breve).

413

El cuerpo de la solicitud es demasiado grande (request_too_large).

422

La validación ha fallado o hay un campo desconocido; details.fields enumera los errores de los campos.

429

Se ha superado el límite de solicitudes; Retry-After indica cuándo reintentar.

503

El despacho no está disponible temporalmente (mantenimiento o configuración en curso); Retry-After indica cuándo reintentar.

default

Cualquier otro error, con el mismo formato de respuesta.

Ejemplos de solicitud

curl -X POST 'https://www.flowyer.es/api/agent/portals/57/messages' \
  -H 'Authorization: Bearer flw_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f' \
  -d '{
  "body": "Tisztelt Ügyfelünk! A beadványt ma benyújtottuk."
}'

Ejemplos de respuesta

{
  "data": {
    "message": {
      "id": 8012,
      "author": {
        "participant_id": 1234,
        "name": "string",
        "kind": "staff"
      },
      "direction": "from_firm",
      "body": "string",
      "created_at": "2026-10-30T09:15:00+01:00",
      "portal": {
        "id": 1234,
        "matter": {
          "id": 1234,
          "case_number": "string"
        }
      },
      "created_via_api": {
        "kind": "key",
        "key_id": 1234,
        "key_name": "string",
        "user_id": 1234,
        "user": "string",
        "at": "2026-10-30T09:15:00+01:00"
      }
    }
  },
  "created": true
}