Ir al contenido

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.

API V1API V2
HostUno por región: euapi, mxapi, brapi, usapi, clapi o rcapi + .flowww.netUn único host para todos: https://api.flowww.net/v2
EndpointSiempre /v1/fwa_external_get.asp, y la operación va en ?cmd=NNREST: una ruta por recurso, y el verbo HTTP indica la intención
Autenticacióndoctor, pass, key y country en cada petición, en el query stringAuthorization: Bearer YOUR_API_KEY. La key se pide una sola vez a POST /getapikey
Cuerpoapplication/x-www-form-urlencoded, con claves numeradas repetidas (ShoppingCart_1_Id…)application/json
RespuestaXML, 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ínicaClinicID en el query string, con nombre distinto según el comando?clinicID=, siempre igual, y opcional en la mayoría de endpoints
PermisosSolo login y contraseñaCada endpoint exige además el permiso de aplicación correspondiente en el usuario dueño de la key
WebhooksNo soportados: los cambios solo se detectan haciendo pollingPOST /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»

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 clinicID que 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 /getapikey lo 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 /getapikey como 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.

Pide la key una vez y guárdala como secreto (una variable de entorno o un gestor de secretos). /getapikey no consume cuota.

Petición
curl --location 'https://api.flowww.net/v2/getapikey' \
--header 'Content-Type: application/json' \
--data '{
"login": "integracion@tuempresa.com",
"password": "********",
"systemkey": "8762574"
}'
Respuesta
{ "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 /getapikeyQué significaQué hacer
200Key emitida.Guárdala.
409Este 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.
403Menciona el plan.El sistema no tiene suscripción Legend ni Ultimate. Contacta con flowww.
403Menciona 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.
502Problema temporal al alcanzar el sistema.Reintenta más tarde.