Resumen
Migrar de la V1 a la V2
Ayuda para llevar una integración de la API V1 a la API V2. Esta página cubre lo que cambia en todos los comandos; las secciones siguientes van comando a comando: qué hacía, qué endpoint de V2 lo sustituye, el mapeo campo a campo y un ejemplo antes/después que funciona.
1. Qué cambia, de un vistazo
Sección titulada «1. Qué cambia, de un vistazo»| API V1 | API V2 | |
|---|---|---|
| Host | Uno por región: euapi, mxapi, brapi, usapi, clapi o rcapi + .flowww.net | Un único host para todos: https://api.flowww.net/v2 |
| Endpoint | Siempre /v1/fwa_external_get.asp, y la operación va en ?cmd=NN | REST: una ruta por recurso, y el verbo HTTP indica la intención |
| Autenticación | doctor, pass, key y country en cada petición, en el query string | Authorization: Bearer YOUR_API_KEY. La key se pide una sola vez a POST /getapikey |
| Cuerpo | application/x-www-form-urlencoded, con claves numeradas repetidas (ShoppingCart_1_Id…) | application/json |
| Respuesta | XML, siempre HTTP 200, y el éxito en <Result>1</Result> | JSON, con códigos HTTP reales (200/201/400/401/403/404/409/429/5xx) |
| Errores | <ResultError>100018</ResultError> | {"message":"…","errorCode":"…"} con el código HTTP que corresponda |
| Clínica | ClinicID en el query string, con nombre distinto según el comando | ?clinicID=, siempre igual, y opcional en la mayoría de endpoints |
| Permisos | Solo login y contraseña | Cada endpoint exige además el permiso de aplicación correspondiente en el usuario dueño de la key |
| Webhooks | No soportados: los cambios solo se detectan haciendo polling | POST /webhooks (suscripción Ultimate) |
2. Paso 0 — el usuario de API y la API key
Sección titulada «2. Paso 0 — el usuario de API y la API key»2.1 Prepara un usuario de API dedicado
Sección titulada «2.1 Prepara un usuario de API dedicado»En V1 cada petición llevaba el login y la contraseña de un usuario. En V2 la key va ligada a un usuario, y todo lo que haga la integración se ejecuta como ese usuario: sus permisos, sus restricciones de visibilidad y su nombre en la auditoría. Antes de pedir la key, prepara un usuario solo para la integración:
- No lo compartas con una persona ni con otra integración. Si el sistema solo permite una sesión abierta por usuario, cuando la integración entre desconectará a quien esté usando esa cuenta, y varios procesos en paralelo con el mismo usuario compiten entre sí (429).
- Dale los permisos de todos los endpoints que vayas a llamar en el perfil de permisos de su centro de trabajo por defecto. Ese perfil se aplica mandes el
clinicIDque mandes. Cada endpoint de la referencia de la API V2 indica qué permiso necesita. - Desactiva la verificación en dos pasos (OTP) para ese usuario, o
/getapikeylo rechazará. - Añade tus servidores a la lista blanca de IPs del usuario, si la tiene, con su IPv4 pública — solo se acepta una IPv4 válida, y la dirección que lee la gateway es la pública desde la que salen tus peticiones, no la privada de la máquina. Si no, tanto
/getapikeycomo todas las llamadas se rechazan con 403. Tómatela como una comodidad, no como una frontera de seguridad. - Exclúyelo de la caducidad de contraseña. Cuando la contraseña cambia o caduca, todas las llamadas devuelven 401 (ver 4.4) hasta que vuelvas a pedir la key.
- Revisa su visibilidad en la agenda: un usuario restringido a sus propias citas tampoco verá las demás a través de la API.
2.2 Pide la key una sola vez
Sección titulada «2.2 Pide la key una sola vez»Pide la key una vez y guárdala como secreto (una variable de entorno o un gestor de secretos). /getapikey no consume cuota.
curl --location 'https://api.flowww.net/v2/getapikey' \--header 'Content-Type: application/json' \--data '{ "login": "integracion@tuempresa.com", "password": "********", "systemkey": "8762574"}'{ "api_key": "u_6J_zxOZaYpgaxqFn2u27_q_CbQIIMORnJnpzhsYxA" }A partir de ahí, todas las llamadas llevan la cabecera Authorization: Bearer YOUR_API_KEY.
Volver a llamar a /getapikey mientras la key está activa no genera una nueva: responde 409 “An active API key already exists…”. Para reemplazarla (por ejemplo si se ha filtrado), envía "regenerate": true: se emite una key nueva y la anterior se revoca de inmediato.
| Respuesta de /getapikey | Qué significa | Qué hacer |
|---|---|---|
| 200 | Key emitida. | Guárdala. |
| 409 | Este usuario ya tiene una key activa. | Sigue usando esa, o envía "regenerate": true. |
| 403 | “Invalid credentials…” | Login o contraseña incorrectos. Revísalos. Los fallos repetidos pueden bloquear el usuario. |
| 403 | “Invalid systemkey…” | La system key no coincide. Revísala. |
| 403 | Menciona el plan. | El sistema no tiene suscripción Legend ni Ultimate. Contacta con flowww. |
| 403 | Menciona el OTP. | El usuario tiene activada la verificación en dos pasos. Ver 2.1. Desactívala para ese usuario. |
| 403 | “Access denied from this IP address…” | La IP de tu servidor no está en la lista blanca de IPs del usuario. Ver 2.1. Añade a ella la IPv4 pública de ese servidor. |
| 502 | Problema temporal al alcanzar el sistema. | Reintenta más tarde. |