Para quien desarrolla: conectar la propia aplicación a Fibonacci
9 minutos de lecturaActualizado el 15 de noviembre de 2026
Esta guía es para las empresas que quieren conectar uno de sus programas (una centralita, una reserva en línea, una aplicación de contabilidad o de recordatorios) a las clínicas que usan Fibonacci. La clínica ve vuestra aplicación en Ajustes, Conexiones, pulsa Conectar, lee qué podrá hacer y confirma. A partir de ahí vuestra aplicación obtiene un token y llama a las API de la clínica, solo para lo que la clínica ha concedido. La clínica puede desconectarla cuando quiera, y desde ese momento vuestros tokens dejan de funcionar.
Usamos estándares, sin protocolos propios: OAuth 2.0 con el perfil SMART Backend Services (un JWT firmado con vuestra clave privada, RFC 7523) y las API FHIR R4. Ningún secreto compartido pasa entre nosotros y vosotros.
1. Registrar la aplicación
Por ahora las aplicaciones las registramos y las aprobamos nosotros, una por una. Escribidnos desde la página Partner o a info@fibonaccimedica.it con:
- el nombre de la aplicación y la razón social de la empresa, como los verá la clínica;
- el sitio y un contacto de soporte (un correo y, si la hay, una página): la clínica los lee en la pantalla de consentimiento;
- una descripción en dos líneas de lo que hace la aplicación para la clínica, en italiano (y en los demás idiomas, si los tenéis);
- una o más direcciones de retorno
https: adonde vuelve el navegador tras el consentimiento; - la dirección
httpspública de vuestras claves públicas (JWKS, RFC 7517); - los permisos que os hacen falta, entre los del punto 2, y por qué.
Cuando la aplicación está aprobada, la ponemos primero en una clínica de prueba con datos ficticios (punto 6), y solo después la ven las clínicas.
Las direcciones de retorno se comparan carácter por carácter: sin prefijos, sin parámetros de más. Una dirección distinta de las registradas hace fallar la conexión.
2. Los permisos
Son cinco y cerrados. La clínica los ve escritos en palabras sencillas antes de confirmar. Ningún dato clínico sale: anamnesis, visitas, tratamientos, fotos, consentimientos e informes se quedan dentro.
| Permiso | Qué podéis hacer | Qué no veis |
|---|---|---|
agenda-lettura | leer y buscar Schedule, Slot, Location; leer un Appointment por código | nombre, teléfono y correo del paciente, tratamiento, motivo, notas de la cita |
agenda-scrittura | crear un Appointment y cambiar su hora o estado, solo en los estados booked, pending, cancelled | como arriba; no se borra, no se busca |
richieste | crear un Appointment en estado pending: la clínica lo encuentra entre las solicitudes y decide | no se vuelve a leer, no se modifica |
recapiti | leer un Patient por código | todo menos nombre, teléfono y correo (ni fecha de nacimiento, ni código fiscal, ni dirección) |
fatture-lettura | leer y buscar Invoice | las líneas de la factura (dicen el tratamiento), las notas, las extensiones (código fiscal, pago), el médico |
Los campos ocultos no aparecen en las respuestas. Cuando modificáis una cita, Medplum vuelve a poner los campos ocultos como estaban: no los borréis enviando el recurso sin ellos.
3. La conexión, paso a paso
3.1 La clínica os conecta
El recorrido puede empezar en dos sitios.
-
Desde vuestro sitio. Mandad a quien administra la clínica a:
https://app.fibonaccimedica.it/impostazioni/collegamenti/app/<vostra-app>?redirect_uri=<indirizzo-di-ritorno>&state=<valore-casuale>statees un valor aleatorio vuestro, de como máximo 200 caracteres entre letras, cifras y-._~: os vuelve igual y sirve para reconocer la solicitud (contra la falsificación de solicitudes entre sitios). -
Desde Fibonacci. La clínica pulsa
Conectarjunto a vuestra aplicación. En este caso no haystate, y el retorno es la primera dirección registrada.
Si quien abre el enlace no ha entrado, Fibonacci le pide que entre y luego lo lleva de vuelta a la pantalla de consentimiento. Solo quien administra la clínica puede confirmar.
3.2 El retorno
Confirmado el consentimiento, el navegador vuelve a vuestra dirección de retorno con cuatro parámetros:
| Parámetro | Qué es |
|---|---|
client_id | el código de vuestra aplicación en esa clínica: cada clínica tiene el suyo |
iss | la base FHIR de la clínica, por ejemplo https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4 |
token_url | dónde pedir el token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token |
state | vuestro valor, si lo habíais enviado |
Comprobad state, luego guardad client_id, iss y token_url junto a la cuenta de la clínica en vuestro sistema. Ninguno de los tres es un secreto: sin vuestra clave privada no sirven a nadie.
3.3 El token
Firmad un JWT con vuestra clave privada (algoritmos ES256, ES384, ES512, RS256, RS384, RS512; recomendados ES256 o ES384), con kid en la cabecera igual a una clave de vuestro JWKS:
| Campo | Valor |
|---|---|
iss | el client_id de la clínica |
sub | el client_id de la clínica |
aud | el token_url de la clínica, exactamente como os ha llegado |
iat | ahora, en segundos Unix |
exp | como máximo 5 minutos después de iat |
jti | un valor único para cada JWT |
Después:
curl -X POST "$TOKEN_URL" \
-d grant_type=client_credentials \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion="$JWT"
La respuesta es un token Bearer que dura una hora. No hay token de renovación: cuando caduca se pide otro con un JWT nuevo. Un secreto compartido (client_secret) no se acepta.
Un ejemplo en Python, con la biblioteca PyJWT:
import time, uuid, jwt, httpx
def token(client_id: str, token_url: str, chiave_privata_pem: str, kid: str) -> str:
ora = int(time.time())
assertion = jwt.encode(
{"iss": client_id, "sub": client_id, "aud": token_url, "iat": ora, "exp": ora + 240, "jti": uuid.uuid4().hex},
chiave_privata_pem, algorithm="ES256", headers={"kid": kid},
)
r = httpx.post(token_url, data={
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": assertion,
})
r.raise_for_status()
return r.json()["access_token"]
3.4 Las llamadas
Con el token, llamáis a la base iss de la clínica:
curl -H "Authorization: Bearer $TOKEN" "$ISS/Slot?schedule=Schedule/<id>&start=ge2026-12-01"
curl -H "Authorization: Bearer $TOKEN" "$ISS/Appointment/<id>"
El token vale solo en las direcciones de esa clínica (.../projects/<studio>/...). Las llamadas permitidas son estas:
| Qué | Cómo |
|---|---|
| leer por código | GET <Tipo>/<id> para Schedule, Slot, Location, Appointment, Patient, Invoice |
| buscar | GET Schedule?, Slot?, Location?, Invoice? con los parámetros de la tabla de abajo |
| crear una cita | POST Appointment |
| modificar una cita | PUT Appointment/<id> (enviad el recurso que habéis leído, con los campos cambiados) |
| capacidades del servidor | GET metadata |
| Tipo | Parámetros de búsqueda admitidos |
|---|---|
Schedule | actor, active, date, _id, _count, _offset, _sort, _lastUpdated |
Slot | schedule, start, status, _id, _count, _offset, _sort, _lastUpdated |
Location | status, _id, _count, _offset |
Invoice | date, status, identifier, type, _id, _count, _offset, _sort, _lastUpdated |
_count va de 1 a 100. Las búsquedas encadenadas (patient.name=), los modificadores (:missing, :text), _include, _revinclude, _has, las operaciones $, _history y las solicitudes batch no se admiten: responden 403. En Appointment y Patient la búsqueda no existe a propósito: incluso sin mostrar un campo, una búsqueda sobre ese campo diría si está o no.
Para saber qué citas existen sin buscarlas, usad las notificaciones (punto 4).
4. Las notificaciones
Cuando una cita nace, cambia de hora o de estado, o se anula, Fibonacci puede mandar un mensaje firmado a una dirección https vuestra, con el tipo de evento (appuntamento.creato, appuntamento.modificato, appuntamento.annullato), los códigos y las fechas. El mensaje no contiene el nombre del paciente. La firma está en la cabecera X-Fibonacci-Firma (HMAC-SHA256 de la hora y del cuerpo exacto).
Hoy la dirección la añade la clínica, desde Ajustes, Personas y permisos, Accesos para programas externos, Notificaciones, y el secreto de la firma lo ve una sola vez. El formato y la verificación de la firma están en la guía técnica de los accesos externos, que os mandamos con el registro. Que las notificaciones se activen solas con la conexión de la aplicación es el paso siguiente, todavía sin hacer.
5. Los errores
| Respuesta | Qué significa |
|---|---|
400 del token, invalid_request | el JWT no vale: aud distinto de token_url, exp caducado o demasiado lejano, firma que no corresponde a vuestro JWKS, o la aplicación ya no está conectada |
400 del token, unsupported_grant_type | hace falta client_credentials con client_assertion; un client_secret no basta |
401 | token caducado: pedid uno nuevo |
400 con Authentication error | la clínica ha desconectado la aplicación: el token ya no vale y no se obtienen otros (Client not found en el token) |
403 con percorso-non-ammesso, tipo-non-ammesso, parametro-non-ammesso | la llamada no es de las del punto 3.4 |
403 sin código | la llamada está permitida pero el permiso no: la clínica no lo ha concedido |
405 con metodo-non-ammesso | verbo HTTP no previsto para ese tipo |
503 con registro-non-disponibile | no hemos podido escribir el acceso en el registro, y sin registro los datos no salen: volved a intentarlo en un momento |
Los errores FHIR llegan como OperationOutcome, con el código en issue[0].details.text.
6. La clínica de prueba
Antes de una clínica real, vuestra aplicación se conecta a una clínica de prueba con datos ficticios: la preparamos nosotros cuando registramos la aplicación, y ahí hacéis todo el recorrido (consentimiento, retorno, token, llamadas, desconexión). Ningún paciente real, ningún dato real.
7. Qué queda registrado
Cada token que vuestra aplicación obtiene y cada llamada que hace quedan en el registro de accesos de la clínica, a nombre de vuestra aplicación: qué, cuándo, con qué resultado y para qué paciente cuando lo hay. La clínica lo lee en su registro. También la conexión y la desconexión quedan registradas, con el nombre de quien las hizo.
8. Privacidad y contrato
La clínica es la responsable de los datos de sus pacientes; vuestra aplicación los trata por su cuenta. Antes de que una clínica real os conecte hace falta un acuerdo entre vosotros y la clínica sobre el tratamiento de datos (art. 28 del RGPD): la pantalla de consentimiento se lo recuerda a la clínica. Pedid y conservad solo los datos que os hacen falta.
9. Soporte
Para el registro, la clínica de prueba y cualquier duda técnica: info@fibonaccimedica.it. Indicad el nombre de la aplicación y, si el error afecta a una clínica, el client_id (nunca la clave privada ni un token).