PharmaX API

Doc

Documentazione PharmaX completa per integrazione API

Questa documentazione copre connessione tecnica, endpoint API protetti /v1/*, endpoint pubblici /public/*, componente SaaS di calcolo, esempi pronti e checklist operativa per trasformare il prontuario AIFA in decisioni rapide su prescrizione, disponibilita e logistica.

Unità operative coperte: mg, ml, gocce, fiale, UI, litri di O2, pack complessi e segnali runtime v2.4 per unità consigliata, moltiplicatori e alternative quantitative. Il runtime corrente usa dataset build-based e search build allineato.

Dataset attivo -- release dati attualmente pubblicata
Schema JSON -- contratto dati servito dal runtime
Record disponibili -- righe dettaglio esposte dal build attivo
Import runtime -- ultimo import completato nel portale

Indice rapido

Onboarding Connessione API Catalogo endpoint SaaS calcolo Endpoint pubblici Delta sync Campi sync JSON Blocchi runtime v2.4 Policy dati AIFA Esempi codice Errori e limiti SLA e supporto Versioning Changelog FAQ sync Security posture Checklist go-live

Onboarding in 10 minuti

  1. Apri /api e identifica gli endpoint del tuo caso d'uso.
  2. Ottieni una API key e usa header X-API-Key per tutte le route /v1/*.
  3. Verifica con GET /health, GET /ready e GET /v1/dataset.
  4. Integra prima /v1/search e /v1/drugs/{aic_code}, poi aggiungi i moduli avanzati.
Nota: per demo e prototipi UI puoi usare anche le route /public/* senza API key.

Connessione API e sicurezza

Base URL

https://pharmax.aipersonal.it

OpenAPI machine-readable: /v1/openapi.json.

Header obbligatorio

X-API-Key: <YOUR_KEY>

Valido per tutte le route protette /v1/*.

Ruoli chiave

client: endpoint business read-only + calc.

admin: endpoint amministrativi runtime.

Rate limit e quota

Header disponibili: X-RateLimit-*, X-Quota-* (se quota configurata).

SaaS calcolo PharmaX

  • Canale attuale ufficiale: SaaS API dentro PharmaX.
  • Input tipico: { "aic_code": "#########" } o payload normalizzato.
  • Output: derived_calc con stato calcolo (ok, partial, not_computable), unità suggerita e riepilogo runtime.
  • Il runtime v2.4 valorizza meglio multiplier_signal, unit_posologica_ranked e alternative_quantitative_systems quando presenti nel payload.

Endpoint pubblici senza API key

  • GET /public/metrics, GET /public/insights, GET /public/demo-config
  • GET /public/drug-search, GET /public/changes, GET /public/drug/:aic_code
  • GET /public/advanced-search/filters, GET /public/advanced-search
  • GET /public/posologia/search, GET /public/posologia/drugs/:aic_code, POST /public/posologia/calc/derive
  • GET /public/equivalents/by-aic/:aic_code, GET /public/formats/by-aic/:aic_code
Uso consigliato: per integrazioni di produzione usa preferibilmente /v1/* con API key.

Sincronizzazione incrementale (scalabile)

Se il tuo software salva localmente i JSON PharmaX, evita full refresh: usa il cursore di delta sync con /public/changes e aggiorna solo gli AIC modificati.

  1. Salva localmente il cursore: since_updated_at + since_aic.
  2. Chiama /public/changes?since_updated_at=...&since_aic=...&limit=200.
  3. Per ogni AIC ricevuto, ricarica dettaglio e fai upsert nel tuo DB.
  4. Memorizza next_cursor per il ciclo successivo.
Il campo record_version aiuta a capire rapidamente se una riga locale e obsoleta.

Campi JSON da usare per update automatici

Per aggiornare una riga farmaco in modo affidabile, i software client devono leggere e salvare questi campi.

  • sync.record_version: fingerprint della riga farmaco (chiave confronto update).
  • sync.source_updated_at: timestamp sorgente record.
  • sync.dataset_version: versione dataset che ha prodotto il record.
  • sync.schema_version: versione schema payload.
  • dataset.imported_at: data import runtime utile per audit.
Regola semplice: se record_version cambia, aggiorna la riga locale; se e uguale, non ricaricare.

Blocchi runtime v2.4 da usare lato client

Contratto dati

Usa normalized, normalized_core e interop come superfici primarie, non solo i campi piatti legacy.

Calcolo SaaS

Nel risultato di derive privilegia suggested_operational_unit, runtime_contracts e package_units_source.

Sync incrementale

Per i client che mantengono un DB locale, il flusso corretto resta: /public/changes -> ricarico dettaglio -> upsert per record_version.

Conformita Open Data AIFA e licenza

PharmaX usa i dataset farmaco pubblici secondo la policy Open Data AIFA e la licenza CC BY 4.0. Le integrazioni client devono mantenere la catena di attribuzione anche dopo normalizzazioni e calcoli derivati.

  • Attribuzione obbligatoria della fonte AIFA.
  • Link esplicito alla licenza CC BY 4.0.
  • Indicazione delle modifiche applicate ai dati (normalizzazione, arricchimento, calcoli).
  • Nessuna rappresentazione che implichi endorsement AIFA del software cliente.
  • Riuso di eventuali dati personali solo nei limiti della normativa vigente.
Riferimenti ufficiali: Open Data AIFA · CC BY 4.0

Esempi veloci

Ricerca farmaci (API protetta)

curl -H "X-API-Key: <CLIENT_KEY>" "https://pharmax.aipersonal.it/v1/search?query=paracetamolo&limit=5&page=1"

Calcolo SaaS (derive)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <CLIENT_KEY>" \
  "https://pharmax.aipersonal.it/v1/calc/derive?drops_per_ml=20&allow_percentage_volume=1" \
  -d '{"aic_code":"025333016"}'

Endpoint pubblico demo

curl "https://pharmax.aipersonal.it/public/advanced-search?q=paracetamolo&limit=10&offset=0"

Error model e troubleshooting

  • 400: input non valido (es. AIC non a 9 cifre).
  • 401: API key mancante/non valida.
  • 403: permessi insufficienti (route admin).
  • 404: risorsa non trovata.
  • 429: rate limit o quota giornaliera superata.

Formato standard errore: {"error":{"code":"...","message":"...","request_id":"..."}}.

SLA e modello supporto

  • Disponibilita target SaaS: 99.5% mensile (finestra di manutenzione esclusa).
  • Presa in carico incidente critico: entro 4 ore lavorative.
  • Presa in carico incidente alto: entro 1 giorno lavorativo.
  • Canale supporto: pagina contatti ufficiale con tracciamento ticket.
Nota operativa: per workflow clinici critici mantieni sempre fallback applicativo lato client in caso di timeout/retry.

Versioning e deprecazione

  • Versione API corrente: v1 (backward compatibility per cambi non-breaking).
  • Versioni dati esposte via /v1/dataset con dataset_version e schema_version.
  • Deprecazioni annunciate con anticipo minimo 90 giorni per endpoint/parametri critici.
  • Per ogni release: aggiornamento OpenAPI + verifica smoke runtime/UI/go-live.

Changelog pubblico (ultimi aggiornamenti)

  • 2026-03-29: attivazione runtime build-based con dataset v2.4 e search build allineato.
  • 2026-03-29: allineamento dataset runtime a dataset_version=2026-03-29, schema_version=2.4.
  • 2026-03-20: introdotto endpoint /public/changes per sync incrementale a cursore.

Questa sezione riassume solo novita funzionali lato client e integrazione.

FAQ aggiornamento automatico

  • Come capisco se un farmaco e cambiato? Confronta record_version locale vs API.
  • Ogni quanto sincronizzare? 6-12 ore per uso standard, 1-2 ore per alta rotazione.
  • Serve riscaricare tutto il catalogo? No, dopo bootstrap usa solo delta sync.
  • Se il delta fallisce? Riprendi dall'ultimo next_cursor valido salvato.

Security posture

  • API key per /v1/*, RBAC admin, sessioni web protette e CSRF su scrittura.
  • Rate limiting su canali protetti e pubblici con header espliciti in risposta.
  • Hardening server-side: blocco path sensibili, noindex aree admin/API, header sicurezza.
  • Canale disclosure: /.well-known/security.txt.

Checklist go-live

  1. Chiavi separate per test e produzione.
  2. Monitoraggio su /health, /ready, /v1/dataset.
  3. Gestione esplicita errori 401/403/429 lato client.
  4. Fallback UI per timeout/retry e log request_id.
  5. Validazione finale con casi reali su ricerca, dettaglio e calcolo.

Supporto

Per supporto tecnico o commerciale usa la pagina contatti ufficiale.

Vai alla pagina contatti