Saltar al contenido
FibonacciEstéticaAccedePrueba gratis

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 https pú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.

PermisoQué podéis hacerQué no veis
agenda-letturaleer y buscar Schedule, Slot, Location; leer un Appointment por códigonombre, teléfono y correo del paciente, tratamiento, motivo, notas de la cita
agenda-scritturacrear un Appointment y cambiar su hora o estado, solo en los estados booked, pending, cancelledcomo arriba; no se borra, no se busca
richiestecrear un Appointment en estado pending: la clínica lo encuentra entre las solicitudes y decideno se vuelve a leer, no se modifica
recapitileer un Patient por códigotodo menos nombre, teléfono y correo (ni fecha de nacimiento, ni código fiscal, ni dirección)
fatture-letturaleer y buscar Invoicelas 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>
    

    state es 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 Conectar junto a vuestra aplicación. En este caso no hay state, 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ámetroQué es
client_idel código de vuestra aplicación en esa clínica: cada clínica tiene el suyo
issla base FHIR de la clínica, por ejemplo https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4
token_urldónde pedir el token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token
statevuestro 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:

CampoValor
issel client_id de la clínica
subel client_id de la clínica
audel token_url de la clínica, exactamente como os ha llegado
iatahora, en segundos Unix
expcomo máximo 5 minutos después de iat
jtiun 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ódigoGET <Tipo>/<id> para Schedule, Slot, Location, Appointment, Patient, Invoice
buscarGET Schedule?, Slot?, Location?, Invoice? con los parámetros de la tabla de abajo
crear una citaPOST Appointment
modificar una citaPUT Appointment/<id> (enviad el recurso que habéis leído, con los campos cambiados)
capacidades del servidorGET metadata
TipoParámetros de búsqueda admitidos
Scheduleactor, active, date, _id, _count, _offset, _sort, _lastUpdated
Slotschedule, start, status, _id, _count, _offset, _sort, _lastUpdated
Locationstatus, _id, _count, _offset
Invoicedate, 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

RespuestaQué significa
400 del token, invalid_requestel 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_typehace falta client_credentials con client_assertion; un client_secret no basta
401token caducado: pedid uno nuevo
400 con Authentication errorla 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-ammessola llamada no es de las del punto 3.4
403 sin códigola llamada está permitida pero el permiso no: la clínica no lo ha concedido
405 con metodo-non-ammessoverbo HTTP no previsto para ese tipo
503 con registro-non-disponibileno 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).