4. Reglas para todos los comandos
Estas valen llames al endpoint que llames. Léelas una vez antes de portar el primer comando; las páginas de cada comando las dan por sabidas.
4.1 Fechas y números
Sección titulada «4.1 Fechas y números»- Las fechas son
dd/MM/yyyyen toda la V2 — el mismo formato que usaba la V1, con una excepción: los comandos 40 y 41 de la V1 tomaban la fecha de validez del presupuesto comoyyyy-mm-dd. En V2 esdd/MM/yyyycomo todo lo demás. - Los importes viajan como números JSON, con punto decimal (
1000.00). Algunas respuestas devuelven cadenas formateadas con coma ("20,00"): parsea a la defensiva.
4.2 Booleanos
Sección titulada «4.2 Booleanos»La V1 usaba 0/1 casi siempre. La V2 mantiene 1/0 en la mayoría de flags, pero unos cuantos campos heredados usan -1 como verdadero, que es la convención interna de flowww:
| Campo | Verdadero | Falso |
|---|---|---|
ClientTemp | -1 (temporal) | 0 (permanente) |
ClientVIP | -1 | 0 |
ClientAppDisabled | -1 | 0 |
DiscountAccumulated | -1 (se acumula) | 0 u omitido (sustituye) |
todo lo demás (ClientFWA, ClientForceEmail, consentimientos…) | 1 | 0 |
4.3 clinicID
Sección titulada «4.3 clinicID»Todos los endpoints que se pueden acotar a un centro aceptan ?clinicID=. Es la clínica desde la que se ejecuta la llamada, como si el usuario hubiera cambiado de centro en la aplicación; no es un filtro de búsqueda. Si lo omites, la llamada se ejecuta desde la clínica por defecto del usuario de API. Es obligatorio donde la documentación lo indique, por ejemplo en GET /paymethod.
- Envíalo explícitamente en todas las llamadas, y siempre el mismo en todas las llamadas de un flujo multipaso: un presupuesto o un ticket creado desde una clínica no se puede editar desde otra.
- Escríbelo exactamente como
clinicID. Un valor que no sea numérico se rechaza con 400invalid-clinicid; una clínica que no existe devuelve 400 con errorCode714.
4.4 Leer el resultado
Sección titulada «4.4 Leer el resultado»En la V1, recibir 200 OK no significaba que el comando hubiera salido bien. Había que abrir el XML: <Result>1</Result> indicaba éxito; si no, <ResultError> daba el motivo del fallo.
En la V2, lee la respuesta en este orden:
- Mira el estado HTTP. Un
200o201indica que la llamada ha terminado; un4xxpuede señalar datos inválidos, credenciales, permisos, un conflicto o un límite; un5xx, un problema del servicio. - Si hay un fallo, lee el cuerpo cuando exista.
errorCode,errorDescription,message,erroryfieldpueden ayudarte a identificarlo. Ninguno de esos campos está garantizado en todas las respuestas: algunos401y429, por ejemplo, no incluyenerrorCode. - Si la llamada forma parte de un flujo de varias operaciones, comprueba el recurso al final. Algunas llamadas devuelven
200con el cuerpo vacío y otras pueden terminar sin dejar el ticket o pedido en el estado esperado. Haz unGETantes de dar por completado todo el flujo.
| Estado HTTP | Cómo interpretarlo | Qué hacer |
|---|---|---|
200 / 201 | La llamada ha terminado. Algunas creaciones devuelven 201; otras operaciones devuelven 200 sin cuerpo. | Guarda el id si se devuelve y confirma el estado final en los flujos de varios pasos. |
400 | Dato inválido, regla de negocio incumplida, o el usuario de API no tiene el permiso (errorCode 15; el 436 es clínica suspendida). | Revisa field, errorCode y errorDescription cuando estén presentes; corrige el dato, la configuración o el perfil de permisos. |
401 | Falta la API key, no es válida o han cambiado las credenciales de su usuario. | Detente y revisa la key; no repitas la petición en bucle. |
403 | El plan no da acceso a la API, o /getapikey ha rechazado las credenciales, la system key, el OTP o la lista blanca de IPs. Un permiso que falta no es un 403. | Comprueba el plan y las credenciales; si es un permiso, mira el 400 de arriba. |
404 | El recurso o la ruta no existen; algunos listados usan 404 cuando no hay resultados. | Interprétalo según el endpoint antes de tratarlo como un fallo. |
409 | Hay un conflicto, como un cliente duplicado o un ticket que no se puede cerrar. | Lee el motivo y resuelve el conflicto antes de repetir la llamada. |
429 | Exceso de concurrencia o cuota mensual agotada. | Distingue los dos casos por el mensaje; solo el primero se reintenta tras Retry-After (ver 4.6). |
502 / 503 | Problema temporal entre la gateway y el sistema. | Si la llamada creaba algo, comprueba primero si se ejecutó (ver 4.6). |
Registra siempre el estado HTTP y el cuerpo recibido, incluso si no es JSON o no trae errorCode. En los errores de negocio, errorCode y errorDescription son especialmente útiles para diagnosticar qué regla se ha aplicado.
4.5 La configuración del sistema decide más que antes
Sección titulada «4.5 La configuración del sistema decide más que antes»La V1 ejecutaba su propia lógica simplificada y se saltaba muchas de las reglas que la clínica tiene configuradas. La V2 ejecuta las mismas operaciones que la aplicación, así que la configuración de la clínica se aplica por completo: campos obligatorios del cliente, reglas de caja, control de duplicados, autorización de descuentos, comprobaciones al cerrar, control de stock… Una petición que la V1 aceptaba puede rechazarse en V2 por cómo esté configurado ese sistema, y la misma petición puede comportarse distinto en dos sistemas.
Cada sección enumera los ajustes que se sabe que afectan a ese comando. Cuando una llamada falle con 400 y un errorCode numérico, lee el errorDescription: te dice qué regla ha saltado. El arreglo suele ser completar el dato o revisar ese ajuste con la clínica, no cambiar la petición. Prueba la integración contra una copia de la configuración real de cada cliente, no solo contra un sistema en blanco.
4.6 Reintentos, límites e idempotencia
Sección titulada «4.6 Reintentos, límites e idempotencia»La V1 hacía cada operación en una petición. En V2 la mayoría de operaciones llevan varias, y ninguna de las llamadas que crean algo es idempotente: repetirla lo crea otra vez (un segundo ticket, una línea duplicada, un segundo pago).
| Respuesta | ¿Se ha ejecutado? | ¿Reintentar? |
|---|---|---|
429 “Too many concurrent requests…” (con Retry-After) | No. | Sí, pasados los segundos indicados, y baja tu paralelismo. |
| 429 “API quota exceeded…” | No. | No. Espera al reinicio mensual o cambia de plan. |
503 (con Retry-After) | No. | Sí, pasados los segundos indicados. |
| 502, timeout, conexión perdida | Puede que sí. | Solo después de comprobarlo: lee el recurso (GET) y envía solo lo que falte. |
| Error de negocio 4xx | No. | Así no: corrige antes el dato o la configuración. |
Todas las peticiones cuentan contra la cuota, también las que fallan. Las respuestas llevan las cabeceras API-Quota-Limit, API-Quota-Used, API-Quota-Remaining y API-Quota-Reset.
4.7 Clientes fusionados
Sección titulada «4.7 Clientes fusionados»Cuando se fusionan dos clientes en flowww, la ficha absorbida se elimina. Los comandos 17 y 19 de la V1 traducían en silencio el id antiguo al del superviviente. La V2 no lo hace nunca: un id antiguo devuelve 404 en GET y en PATCH, y no se le puede crear un ticket.
Si tu integración guarda ids de cliente de flowww, gestiona ese 404: vuelve a buscar el cliente (GET /client?clientData= por email, teléfono o documento), guarda el id nuevo y reintenta. Suscríbete a crm.client.merge (ver 4.9) para enterarte en el momento.
4.8 Cuotas
Sección titulada «4.8 Cuotas»La V1 no tenía cuota: podías llamarla tantas veces como quisieras y nadie medía nada. La V2 sí mide, así que es un límite con el que tu integración no tenía que convivir. La cuota se calcula por sistema como clínicas licenciadas × peticiones por plan: 100.000 peticiones por clínica y mes en Ultimate, 10.000 en Legend. Si las clínicas de un sistema tienen planes distintos, se aplica a todas el más restrictivo. Como varios comandos de la V1 pasan a ser varias llamadas de V2 (ver 19, 39 y 40), recalcula tu volumen mensual antes de cambiar.
4.9 Deja de hacer polling: webhooks
Sección titulada «4.9 Deja de hacer polling: webhooks»Las integraciones que llamaban al comando 120 (o al 100, o al 17) en un temporizador deberían suscribirse en su lugar. Registra un endpoint HTTPS con POST /webhooks y elige los eventos que te interesen:
- Clientes —
crm.client.created,crm.client.updated,crm.client.deleted,crm.client.merge - Agenda —
diary.appointment.saved,diary.appointment.moved,diary.appointment.deleted,diary.appointment.validated - Ventas —
sales.ticket.closed,sales.cashdesk.closed - y además turnos, horarios de usuarios, usuarios y clínicas
4.10 Qué clientes ve una llamada
Sección titulada «4.10 Qué clientes ve una llamada»Algunos sistemas — normalmente franquicias y grupos de varios centros — están configurados para que cada cliente pertenezca a la clínica que lo creó. Esa configuración no se ve desde la API, pero decide lo que encuentran tus llamadas:
- Leer, actualizar o borrar un cliente solo funciona si el cliente es de la clínica de la llamada. Desde otro
clinicIDla respuesta es 404, aunque el cliente exista y el mismo usuario lo vea desde otra parte. - Una búsqueda devuelve solo los clientes de las clínicas donde el usuario de API tiene centro de trabajo, no los de todo el sistema — así que
GET /client?clientData=yPOST /client/advanced-searchpueden no encontrar un cliente que sí está. - Fusionar dos clientes de clínicas distintas exige una confirmación explícita.
Sin esa configuración, todos los clientes del sistema se ven desde cualquier clínica. Si tu integración de V1 funcionaba con un usuario único que lo veía todo, comprueba en qué caso estás antes de cambiar, y da al usuario de API un centro de trabajo en cada clínica a la que tenga que llegar. Afecta a los comandos 17, 18, 24 y 42.
4.11 Ids en vez de códigos: los catálogos
Sección titulada «4.11 Ids en vez de códigos: los catálogos»La V1 tomaba los códigos ISO y los resolvía ella. La V2 espera el id de flowww en todos los sitios donde aparecen esos campos — al crear o actualizar un cliente (08, 18), al leerlo (17) y al filtrar una búsqueda por ClientCountryID o ClientProvinceID (24). La API te da los catálogos:
| Catálogo | Llamada | Qué devuelve |
|---|---|---|
| Países | GET /system/countries | Un array de CountryID, CountryName, CountryDialCode y CountryISO3166_1_alfa2 — traduce directamente el código de la V1 al id. España es 201. |
| Provincias | GET /system/provinces?countryID=201 | Un array de ProvinceID y ProvinceName, las de ese país. Madrid es 32. |
| Ciudades | GET /system/cities?provinceID=… | Un array de CityID y CityName. Se piden por provincia, no por país, y no traen el código postal. No todos los países tienen sus ciudades cargadas: una provincia sin ninguna devuelve 404. |
Léelos una vez y cachéalos: cambian poco y cada llamada cuenta para tu cuota. Si tu integración de V1 guardaba códigos ISO, tradúcelos una vez durante la migración y no en cada llamada.
4.12 Versiones de la API
Sección titulada «4.12 Versiones de la API»- Los comandos nuevos salen en la V2. Lo que lees en esta guía sigue creciendo sin que tengas que moverte a ninguna parte.
- Lo que no puede salir sin más es una corrección que cambie un campo ya publicado — su tipo, su forma, los valores que admite. Cambiarla de un día para otro rompería a quien hoy lo está leyendo.
- No hay rutas nuevas: no existe
/v2.1. La corrección se despliega en/v2, pero no se activa por defecto hasta una fecha límite que se anuncia antes en el changelog. - Hasta esa fecha decides tú cuándo la ves, mandando la cabecera
preview-versioncon el año y el mes de la fecha límite. Con ella, la respuesta llega ya corregida; sin ella, exactamente igual que hoy. - Llegada la fecha, la corrección pasa a ser el comportamiento normal y la cabecera deja de tener efecto. Puedes quitarla cuando te venga bien: no molesta.
curl --location 'https://api.flowww.net/v2/budget/123456' \ --header 'Authorization: Bearer <api_key>' \ --header 'preview-version: 2026-03'Así pruebas el cambio contra tus propios datos y desde tu propia integración, sin cambiar la ruta base ni esperar al día D: cuando llegue, ya no tienes que desplegar nada.
Dos de esas correcciones ya se conocen y están documentadas donde muerden: el separador decimal (4.1) y los booleanos con -1 (4.2).