Documentazione API

v1 — pubblica

Accesso libero a tutte le carenze di medicinali in Svizzera. Senza chiave API, senza login. La preghiamo di un uso equo — max. ~300 richieste/giorno consigliate.

Più di 100 req/h? Chiavi Professional da CHF 39/mese — con Severity Scoring e 10'000 req/giorno.

Accesso API e prezzi →

Base URL

https://engpassradar.ch/api/v1

Tutte le risposte sono in JSON UTF-8. CORS è attivato (Access-Control-Allow-Origin: *).

Endpoint

GET/api/v1/shortagesElenco paginato di tutte le carenze

GET/api/v1/shortages/:gtinSingolo prodotto con breakdown del punteggio

GET/api/v1/statsIndicatori aggregati

GET/api/v1/timelineSerie temporale settimanale

GET/api/alternativesAlternative per un prodotto (GTIN)

POST/api/alternatives/batchAlternative in batch fino a 50 GTIN

GET/api/export/csvEsportazione CSV filtrata

GET/api/healthControllo dello stato del sistema

GET

/api/v1/shortages

Restituisce un elenco paginato e filtrabile di tutte le carenze segnalate.

Parametro	Tipo	Obbligatorio	Descrizione	Esempio
search	string	–	Ricerca full-text su denominazione, azienda, codice ATC	pregabalin
status	string	–	Codice/i di stato 1–5, separati da virgola	1,4
firma	string	–	Nome esatto dell'azienda	Sandoz
atc	string	–	Prefisso del codice ATC	C09
neu	integer	–	Solo carenze ≤ 7 giorni	1
page	integer	–	Numero di pagina (default: 1)	2
perPage	integer	–	Voci per pagina (max: 200)	100
sort	string	–	campo:asc o campo:desc	tageSeitMeldung:desc

curl "https://engpassradar.ch/api/v1/shortages?atc=C09&status=1,4&perPage=20"

{
  "data": [
    {
      "id": 4821,
      "gtin": "7680654320016",
      "bezeichnung": "Olmesartan Mepha Lactab 20 mg",
      "firma": "Mepha Pharma AG",
      "atcCode": "C09CA08",
      "statusCode": 1,
      "statusText": "Direkt gemeldet",
      "tageSeitMeldung": 183,
      "isActive": true,
      "datumLieferfahigkeit": "31.12.2026",
      ...
    }
  ],
  "total": 68,
  "page": 1,
  "perPage": 20,
  "meta": { "generatedAt": "2026-04-19T10:00:00Z", "source": "engpassradar.ch" }
}

GET

/api/v1/shortages/:gtin

Dettagli completi per un singolo prodotto inclusi Severity Score breakdown.

Parametro	Tipo	Obbligatorio	Descrizione	Esempio
gtin	string	sì	GTIN del prodotto (7–14 cifre), nel percorso URL	7680654320016

curl "https://engpassradar.ch/api/v1/shortages/7680654320016"

{
  "data": {
    "gtin": "7680654320016",
    "bezeichnung": "Olmesartan Mepha Lactab 20 mg",
    "firma": "Mepha Pharma AG",
    "atcCode": "C09CA08",
    "statusCode": 1,
    "tageSeitMeldung": 183,
    "isActive": true,
    "isBwl": true,
    "score": {
      "total": 57,
      "label": "Mittel",
      "breakdown": {
        "transparency": 5,
        "duration": 22,
        "noAlternatives": 15,
        "critical": 15
      }
    },
    "bemerkungen": "Engpass aufgrund erhöhter Nachfrage...",
    "voraussichtlicheDauer": "Q3 2026",
    ...
  }
}

GET

/api/v1/stats

Indicatori aggregati sulla situazione attuale dell'approvvigionamento. Utili per dashboard e monitoraggio.

curl "https://engpassradar.ch/api/v1/stats"

{
  "data": {
    "active": 705,
    "uniqueAtcGroups": 148,
    "avgDaysSinceMeldung": 203,
    "lastUpdated": "2026-04-19T03:15:00Z",
    "duration": {
      "under2Weeks": 42,
      "weeks2to6": 89,
      "weeks6to26": 201,
      "months6to12": 178,
      "over1Year": 195
    },
    "regulatory": {
      "bwl": 87,
      "pflichtlager": 112,
      "kassenpflichtig": 534
    },
    "topAtcGroups": [
      { "atc": "N02", "bezeichnung": "Analgetika", "count": 54 },
      ...
    ]
  }
}

GET

/api/v1/timeline

Serie temporale settimanale: nuove carenze e stock attivo. Ideale per analisi di trend.

Parametro	Tipo	Obbligatorio	Descrizione	Esempio
weeks	integer	–	Numero di settimane indietro (4–260, default: 52)	104

curl "https://engpassradar.ch/api/v1/timeline?weeks=12"

{
  "data": [
    { "week": "2026-W14", "newShortages": 18, "activeShortages": 712 },
    { "week": "2026-W15", "newShortages": 22, "activeShortages": 705 },
    ...
  ],
  "meta": { "weeks": 12, "generatedAt": "2026-04-19T10:00:00Z" }
}

GET

/api/alternatives

Alternative con principio attivo equivalente per un prodotto, suddivise in stessa azienda, co-marketing e tutte le alternative. Le risposte vengono memorizzate nella cache per 24 ore.

Parametro	Tipo	Obbligatorio	Descrizione	Esempio
gtin	string	sì	GTIN del prodotto	7680654320016

curl "https://engpassradar.ch/api/alternatives?gtin=7680654320016"

{
  "gleicheFirma": [],
  "coMarketing": [
    { "bezeichnung": "Olmesartan Spirig HC Lactab 20 mg", "firma": "Spirig HealthCare", "gtin": "7680591620011" }
  ],
  "alleAlternativen": [
    { "bezeichnung": "Olmesartan Sandoz Filmtabl 20 mg", "firma": "Sandoz", "gtin": "7680630420018", "typ": "G" }
  ]
}

POST

/api/alternatives/batch

Ricerca di alternative per fino a 50 GTIN in un'unica richiesta. Notevolmente più efficiente di N chiamate singole.

curl -X POST "https://engpassradar.ch/api/alternatives/batch" \
  -H "Content-Type: application/json" \
  -d '{"gtins": ["7680654320016", "7680591620011"]}'

[
  { "gtin": "7680654320016", "data": { "alleAlternativen": [...], ... } },
  { "gtin": "7680591620011", "data": null }
]

data: null se non sono ancora presenti alternative in cache per un GTIN.

GET

/api/export/csv

Restituisce tutte le carenze (filtrate) come file CSV. Importabile direttamente in Excel o Python pandas.

Parametro	Tipo	Obbligatorio	Descrizione	Esempio
search	string	–	Ricerca full-text su denominazione, azienda, codice ATC	pregabalin
status	string	–	Codice/i di stato 1–5, separati da virgola	1,4
firma	string	–	Nome esatto dell'azienda	Novartis
atc	string	–	Prefisso del codice ATC	N06

# Alle Neuropharmaka-Engpässe als CSV herunterladen
curl "https://engpassradar.ch/api/export/csv?atc=N06" -o n06-engpaesse.csv

# In Python:
import pandas as pd
df = pd.read_csv("https://engpassradar.ch/api/export/csv?atc=N06")

Campi: denominazione, azienda, codice ATC, stato, fornibile dal, ultima modifica, giorni dalla segnalazione, GTIN, Pharmacode, prima osservazione

GET

/api/health

Controllo dello stato del sistema. Restituisce 200 se tutti i sistemi sono pronti, 503 in caso di problemi.

curl "https://engpassradar.ch/api/health"

{
  "status": "healthy",
  "timestamp": "2026-04-19T10:00:00Z",
  "database": { "healthy": true, "latencyMs": 12 },
  "cache": { "entries": 84, "utilizationPercent": "42.0" }
}

Codici di stato HTTP

200Successo

400Parametri non validi (p. es. GTIN errato)

404Prodotto non trovato

500Errore interno del server

503Sistema degradato (solo su /api/health)

Caching

/api/v1/shortagess-maxage: 5 minstale: 1 h

/api/v1/shortages/:gtins-maxage: 5 minstale: 1 h

/api/v1/statss-maxage: 5 minstale: 1 h

/api/v1/timelines-maxage: 1 hstale: 24 h

/api/alternativess-maxage: 1 hstale: 24 h

Rate limit e accesso API

L'API è gratuita per ricerca e piccoli team. Per integrazioni commerciali la preghiamo di scegliere un piano che sostenga l'esercizio.

Free100 req/oraNessuna chiave necessariaCHF 0

Research2'000 req/giornoGratuito, conferma via e-mailCHF 0

Engpassradar Pro10'000 req/giornoChiave API tramite StripeCHF 39/mese

Klinik-System100'000 req/giornoChiave API, endpoint batch, webhookCHF 199/mese

Data LicenseIllimitatoBulk-Dump, white-label, SLAda CHF 499/mese

Richiedere chiave API →Accesso research (gratuito)

401Chiave API non valida o inattiva

429Rate limit superato — X-RateLimit-Reset contiene il timestamp di reset

# Mit API-Key (Professional/Institutional)
curl -H "Authorization: Bearer <ihr-api-key>" \
  "https://engpassradar.ch/api/v1/shortages?atc=C09"

# Response-Header
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1746057600
X-Api-Tier: professional

Webhook

I webhook inviano una richiesta HTTP POST al Suo URL non appena una nuova carenza viene segnalata o una esistente risolta — senza polling, in tempo reale.

shortage.createdNuova carenza nella lista Swissmedic

shortage.resolvedCarenza marcata come risolta

shortage.updatedModifica a una carenza esistente (data, stato)

I webhook sono disponibili nel Klinik-System

Engpassradar Pro riceve i dati tramite API polling. Il Klinik-System (CHF 199/mese) invia eventi push direttamente alla Sua infrastruttura.

Richiedere il Klinik-System →

Feed RSS

/rss.xmlTutte le carenze attuali

/wirkstoff/{atc}/feed.xmlCarenze per gruppo ATC (p. es. /wirkstoff/C09/feed.xml)

Server MCP (Claude / Copilot / Cursor)

Il server MCP fornisce i dati engpassradar come strumenti di agente nativi — senza scraping, direttamente nel workflow di Claude Desktop, GitHub Copilot o Cursor. Domande come «Inhibace non è disponibile — quali alternative esistono per C09AA?» diventano una chiamata diretta al database.

search_shortagesRicerca full-text per prodotto, principio attivo o azienda

get_shortageSingolo prodotto per GTIN — incl. punteggio, prezzo, stato BWL

find_alternativesAlternative per un prodotto in carenza — con il loro stato di carenza

check_atc_groupQuanti prodotti in una classe ATC sono interessati? (C09, C09AA, …)

list_active_shortagesElenco bulk delle carenze attive con filtri

get_company_statusProfilo azienda: carenze attive + punteggio di trasparenza

get_shortage_timelineLinea di tendenza settimanale del numero di carenze

get_weekly_summarySnapshot KPI: totale attivo, critico, interessato BWL

Installazione tramite Smithery (consigliato)

Nessun download, nessun build. Il server gira ospitato su mcp.engpassradar.ch — Smithery collega il Suo client IA direttamente.

Installare tramite Smithery →

Configurazione manuale (Claude Desktop / Cursor)

Per la connessione HTTP diretta senza Smithery — inserire in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "engpassradar": {
      "type": "http",
      "url": "https://mcp.engpassradar.ch"
    }
  }
}

Con chiave API Pro (10'000 req/giorno):

{
  "mcpServers": {
    "engpassradar": {
      "type": "http",
      "url": "https://mcp.engpassradar.ch?ENGPASS_API_KEY=ihr-api-key"
    }
  }
}

Free Tier (100 req/h) senza chiave. Chiave Pro (10'000 req/giorno) tramite API Keys. Codice sorgente: github.com/…/mcp