PharmaX API

API

API PharmaX complete: connessione chiara, endpoint completi, esempi pronti

In questa pagina trovi il catalogo aggiornato delle API realmente esposte dal runtime: route protette /v1/*, route pubbliche /public/*, API SaaS di calcolo e route admin operative. Con una sola integrazione porti in applicazione ricerca farmaci, dettaglio normalizzato, calcoli terapeutici e controllo scorte a unità dosabile. Il runtime attuale è allineato a NursingBrain v2.4 con import build-based e search build dedicato.

Dataset attivo -- release dati servita oggi via API
Schema JSON -- contratto dettaglio/calc in produzione
Record API -- righe disponibili sul build attivo
Search index -- righe indicizzate per il runtime corrente

Indice API

Base e auth SaaS calc Output calc Policy dati AIFA Catalogo /v1 Catalogo /v1/admin Catalogo /public Delta sync Campi sync Esempi codice Errori e limiti

Base URL, autenticazione e headers

Base URL produzione https://pharmax.aipersonal.it
Specifica OpenAPI /v1/openapi.json
Header auth X-API-Key: <YOUR_KEY>
Health check /health e /ready
  • Tutte le route /v1/* richiedono API key valida.
  • Route admin scrittura: ruolo admin necessario.
  • Header runtime: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
  • Header quota (se configurata): X-Quota-Daily, X-Quota-Used, X-Quota-Remaining.

SaaS calcolo (attivo)

  • GET /v1/calc/version: versioni engine e regole.
  • POST /v1/calc/derive: calcolo singolo con aic_code o payload normalizzato.
  • POST /v1/calc/derive/batch: calcolo batch (max 200 item) con esito per-item.
Parametri utili: drops_per_ml, allow_percentage_volume=1, allow_unit_conversion=1.

Output SaaS calc: campi chiave

I risultati di /v1/calc/derive sono pensati per uso operativo: disponibilità confezione, unità suggerita, totali attivo e riepilogo volume/peso. 

{
  "derived_calc": {
    "calc_status": "ok",
    "suggested_operational_unit": "COMPRESSA",
    "package_units_total": 120,
    "package_units_label": "COMPRESSA",
    "package_units_source": "runtime_multiplier_policy",
    "runtime_contracts": {
      "unit_choice": { "requires_runtime_choice": true },
      "pack": { "requires_runtime_operation": true }
    },
    "active_total": [{ "component_name": "X", "value": 150, "unit": "MG" }],
    "totals_summary": {
      "total_volume_ml": null,
      "total_weight_g": null,
      "active_total_by_unit": [{ "unit": "MG", "value": 150 }],
      "active_total_mass_mg": 150,
      "active_total_mass_g": 0.15,
      "active_total_concentration_mg_per_ml": null
    },
    "review_reasons": []
  }
}
Regola pratica: usa active_total_concentration_mg_per_ml solo quando total_volume_ml e una base reale o derivata con evidenza sufficiente.

Segnali v2.4 da consumare senza reinferenze locali

record_version unit_posologica_ranked multiplier_signal alternative_quantitative_systems interop.pharmax.* runtime_contracts

Policy distribuzione dati e obblighi licenza

Gli endpoint PharmaX espongono dati derivati da fonti Open Data AIFA. In produzione, ogni client che redistribuisce i risultati deve rispettare la licenza CC BY 4.0 e la policy di riuso AIFA.

  • Mostrare attribuzione fonte AIFA in UI, export e report.
  • Allegare link alla licenza CC BY 4.0.
  • Indicare se i dati sono stati normalizzati o ricalcolati dal client.
  • Mantenere separata la responsabilita tra dato sorgente e output derivato applicativo.
Riferimenti: Open Data AIFA · CC BY 4.0

Catalogo route protette /v1 (business)

Metodo Endpoint Descrizione
GET/v1/searchRicerca farmaci con filtri e ordinamento.
GET/v1/drugs/{aic_code}Dettaglio farmaco completo.
GET/v1/drugs/{aic_code}/posologyPayload orientato al calcolo posologico.
GET/v1/drugsBulk detail per lista AIC via query ids.
GET/v1/registry/fasceCatalogo fasce regolatorie.
GET/v1/atc/{code}Dettaglio classificazione ATC.
GET/v1/equivalents/{code}Equivalenze per codice.
GET/v1/datasetVersione e stato dataset runtime.
GET/v1/calc/versionVersioni del motore SaaS calc.
POST/v1/calc/deriveCalcolo derivato singolo.
POST/v1/calc/derive/batchCalcolo derivato batch.

Catalogo route protette /v1/admin

Metodo Endpoint Descrizione
GET/v1/admin/statusStato runtime e servizi.
GET/v1/admin/go-live/readinessCheck bloccanti pre go-live.
GET/v1/admin/auth/schemaStato schema auth admin.
POST/v1/admin/auth/schema/repairRiparazione schema auth.
GET/v1/admin/clientsLista client API.
POST/v1/admin/clientsCreazione client API.
GET/v1/admin/keysLista API key.
POST/v1/admin/keysCreazione API key.
GET/v1/admin/keys/{id}/usageConsumi chiave.
PATCH/v1/admin/keys/{id}Aggiornamento chiave esistente.
POST/v1/admin/keys/{id}/revokeRevoca chiave.
DELETE/v1/admin/keys/{id}Eliminazione chiave.
POST/v1/admin/rebuild-indexRebuild indice ricerca.
POST/v1/admin/cache/clearPulizia cache.
GET/v1/admin/deploy/ftp/statusStato configurazione deploy FTP.
POST/v1/admin/deploy/ftp/runEsecuzione deploy FTP.
POST/v1/admin/datasetAggiornamento metadata dataset.
POST/v1/admin/dataset/manifestApplicazione manifest dataset.
POST/v1/admin/verify-importVerifica import dati.
GET/v1/admin/nursingbrain/validateValidazione integrazione NB.
GET/v1/admin/nursingbrain/coverageCopertura integrazione NB.
GET/v1/admin/nursingbrain/samplesCampioni record NB.
GET/v1/admin/calc/validateAudit calcolo su campione.
GET/v1/admin/warehouse/itemsAnagrafica magazzino.
GET/v1/admin/warehouse/movementsMovimenti magazzino.
POST/v1/admin/warehouse/loadCarico magazzino.
POST/v1/admin/warehouse/unloadScarico magazzino.
POST/v1/admin/warehouse/unload-fefoScarico FEFO.

Catalogo route pubbliche /public (senza API key)

Metodo Endpoint Descrizione
GET/public/metricsMetriche pubbliche runtime.
GET/public/insightsInsight sintetici pubblici.
GET/public/demo-configConfigurazione demo API.
GET/public/drug-searchRicerca farmaci base.
GET/public/changesDelta sync AIC aggiornati con cursore since_updated_at/since_aic.
GET/public/drug/{aic_code}Dettaglio farmaco per AIC.
GET/public/advanced-search/filtersFiltri disponibili ricerca avanzata.
GET/public/advanced-searchRicerca avanzata filtri multipli.
GET/public/posologia/searchRicerca per demo posologica.
GET/public/posologia/drugs/{aic_code}Dettaglio posologico pubblico.
POST/public/posologia/calc/deriveDerive pubblico via proxy/local fallback.
GET/public/equivalents/by-aic/{aic_code}Equivalenti con fascia/prezzo.
GET/public/formats/by-aic/{aic_code}Confronto formati stesso principio.

Delta sync consigliato per client esterni

Per mantenere allineato un DB locale (magazzino, prescrizioni, ERP), usa il cursore incrementale su /public/changes e aggiorna solo gli AIC cambiati. 

GET /public/changes?since_updated_at=2026-03-29T00:00:00.000Z&since_aic=025333016&limit=200

{
  "ok": true,
  "next_cursor": {
    "since_updated_at": "2026-03-29T09:14:25.000Z",
    "since_aic": "042407128"
  },
  "items": [
    {
      "aic_code": "042407128",
      "source_updated_at": "2026-03-29T09:14:25.000Z",
      "dataset_version": "2026-03-29",
      "schema_version": "2.4",
      "record_version": "042407128:2026-03-29T09:14:25.000Z:2026-03-29:2.4"
    }
  ]
}
Dopo il delta, richiama /public/drug/{aic_code} (o /v1/drugs/{aic_code}) e fai upsert locale della sola anagrafica farmaco.

Campi sync da leggere nei payload

Campo Dove Uso consigliato
record_versionsyncConfronto versione riga locale vs API.
source_updated_atsyncOrdinamento aggiornamenti e audit temporale.
dataset_versionsync/datasetAllineamento release dati pubblicata.
schema_versionsync/datasetCompatibilita parser del client.
next_cursor/public/changesRipresa sync incrementale dal punto corretto.

Esempi di integrazione

cURL: ricerca + dettaglio

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

curl -H "X-API-Key: <CLIENT_KEY>" "https://pharmax.aipersonal.it/v1/drugs/025333016"

JavaScript (Node/Browser): SaaS derive

const res = await fetch("https://pharmax.aipersonal.it/v1/calc/derive?drops_per_ml=20&allow_percentage_volume=1", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.PHARMAX_API_KEY
  },
  body: JSON.stringify({ aic_code: "025333016" })
});
const data = await res.json();
console.log(data.derived_calc?.calc_status);

Python (requests): dataset status

import requests

url = "https://pharmax.aipersonal.it/v1/dataset"
headers = {"X-API-Key": "YOUR_KEY"}
res = requests.get(url, headers=headers, timeout=15)
print(res.status_code, res.json())

PHP (cURL): endpoint pubblico senza key

$ch = curl_init("https://pharmax.aipersonal.it/public/advanced-search?q=paracetamolo&limit=5&offset=0");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
print_r($data);

Errori standard e gestione

  • 400 INVALID_PAYLOAD: input/formato non valido.
  • 401 UNAUTHORIZED: API key assente o non valida.
  • 403 FORBIDDEN: ruolo non autorizzato.
  • 404 NOT_FOUND: record/endpoint non trovato.
  • 429 RATE_LIMIT o 429 QUOTA_EXCEEDED: limiti superati.

Payload errore standard:

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Rate limit exceeded",
          "request_id": "req_..."
  }
}

Governance API

  • Compatibilita: endpoint /v1/* stabili per evoluzioni non-breaking.
  • Deprecazioni: preavviso minimo 90 giorni su endpoint o parametri critici.
  • Observability: usa sempre request_id per correlare log applicativi e supporto.
  • Resilienza client: implementa retry progressivo + fallback su errori 429/5xx.