Premessa

Le REST API v.1 sono compatibili con qualsiasi client per API RESTful.

Endpoint

Endpoint di test:

https://sistema-ts-api.it/api/v1/test

Endpoint di produzione:

https://sistema-ts-api.it/api/v1/prod

Gestione degli errori

Tutte le risposte API contengono una stringa JSON.
Se non ci sono errori, il codice HTTP sarà 200 (pagina trovata e gestita senza errori).
In caso di errore, il codice potrà essere 400, 401 o 404, e il corpo conterrà un campo error:

{
  "error": "messaggio di errore"
}

Paginazione

Tutte le chiamate GET hanno un limite massimo di 1000 risultati trasmessi dal server. Per le opzioni di paginazione, vedere gli approfondimenti

Autenticazione

È possibile autenticare ogni chiamata API mediante Basic Authentication, inviando negli Header della richiesta HTTP la seguente riga:

Authorization: Basic [basic-auth-string]

dove [basic-auth-string] si ottiene concatenando username, il carattere ":" e la password ed eseguendo una codifica "base64" sulla stringa ottenuta.
In alternativa, è possibile autenticare le chiamate API mediante autenticazione "Bearer". Per maggiori informazioni, vedere gli approfondimenti.

Invio di un Documento di Spesa

È possibile inviare un documento di spesa specificando solo i dati strettamente necessari, in formato JSON.

Richiesta

POST [endpoint]/documenti-spesa

Corpo della richiesta (esempio):

{
    "partitaIvaErogatore": "00000000000", -- soggetto già censito nell"anagrafica
    "tipoDocumento": "F", -- F = Fattura, D = Documento commerciale
    "numeroDocumento": "2",
    "dataDocumento": "2026-01-30",
    "codiceFiscaleCittadino": "AAABBB00A00H501A",
    "vociSpesa": [
        {
            "tipoSpesa": "SP", -- vedere tabella codici tipo spesa più sotto
            "importo": 100.00,
            "naturaIVA": "N2.2" -- vedere apprfondimenti su IVA più sotto
        }
    ]
}

Risposta (esempio):

{
    "id":            [identificativo univoco numerico sistema-tessera-sanitaria-api],
    "statoSts":      [INVI|PREN|ERRO], -- INVI=Inviato, PREN=Prenotato, ERRO=Errore
    "protocolloSts": [numero di protocollo rilasciato dal STS, numerico, oppure null in caso di errore],
    "messaggioSts":  [eventuale messaggio di errore]
}

nota: la risposta contiene anche la rappresentazione json completa dell"oggetto inviato, come visibile di seguito

Lettura

È possibile accedere alle informazioni sui documenti inviati

Richiesta:

GET [endpoint]/documenti-spesa

È possibile aggiungere i seguenti parametri opzionali nella querystring in GET, per filtrare i risultati desiderati:

date_from         -- data di invio iniziale, formato "yyyy-mm-dd hh:mm:ss" oppure "yyyy-mm-dd"
date_to             -- data di invio finale, formato "yyyy-mm-dd hh:mm:ss" oppure "yyyy-mm-dd"
id_from             -- ID iniziale
id_to               -- ID finale
sts_protocollo_from -- identificativo SDI iniziale
sts_protocollo_to   -- identificativo SDI finale
sts_protocollo_id   -- identificativo SDI
partita_iva         -- filtra per partita iva del soggetto erogatore
numero_documento    -- numero documento esatto es: "123"
anno_documento      -- Es: "2024"
tipo_documento      -- Es: "F", "D", ...

Risposta (esempio):

[
    {
        "id": [identificativo univoco numerico sistema-ts-api],
        "partitaIvaErogatore": "00000000000",
        "tipoDocumento": "F",
        "numeroDocumento": "2",
        "dataDocumento": "2026-01-13",
        "dispositivo": "1",
        "dataPagamento": "2026-01-13",
        "flagOpposizione": "0",
        "vociSpesa": [
            {
                "tipoSpesa": "SP",
                "importo": "100.00",
                "aliquotaIVA": null,
                "naturaIVA": "N2.2"
            }
        ],
        "statoSts": "INVI",
        "protocolloSts": 1234567890,
        "messaggioSts": "",
        "origine": "A",
        "dataInserimento": "2026-01-13 12:00:00"
    },
    ...
]

Legenda stati: "INVI"=Inviato, "PREN"=Prenotato (documento preso in carico ma ancora non trasmessa al STS), "ERRO"=Errore (vedere messaggio)

Nota: il campo codiceFiscaleCittadino non viene ritornato perché viene codificato sul server

È possibile leggere i dati aggiornamenti di una singola spedizione.

Richiesta

GET [endpoint]/documento-spesa/[ID]

Risposta

{
    "id": "1",
    ... seguono gli stessi campi dell"oggetto json come sopra
}

Gestione anagrafica Erogatori

È possibile gestire l"anagrafica dei soggetti erogatori via API

Creazione di un Erogatore

POST [endpoint]/erogatori

Nota: I campi obbligatori sono: partitaIva, codiceFiscale

I campi necessari per poter trasmettere documenti sono: usernameSts, passwordSts, pincode

Aggiornamento di un Erogatore

PUT [endpoint]/erogatori/[ID]

Nota: è possibile specificare nel json inviato solo i dati da aggiornare

Utile ad esempio per aggiornare solo il pincode quando è scaduto

Elenco Erogatori

GET [endpoint]/erogatori

Singolo Erogatore

GET [endpoint]/erogatori/[ID]

Eliminazione Erogatore

DELETE [endpoint]/erogatori/[ID]

In caso di successo, tutte le chiamate ritornano l"oggetto in formato JSON, ad eccezione di "GET [endpoint]/erogatori" che ritorna una lista di oggetti. Formato dell'oggetto (esempio):

{
    "id": "1",
    "denominazione": "Erogatore test",
    "partitaIva": "00000000000",
    "usernameSts": "123456",
    "passwordSts": "789012",
    "descrizione": "",
    "dataInserimento": null
}

Nota: i campi codiceFiscale e pincode vengono codificati sul server è quindi non possono essere ritornati nella risposta

Approfondimenti: Paginazione

Tutte le richieste di tipo GET che non abbiano un [ID] specificato, ritornano liste di risultati.

FatturaElettronicaAPI per default ritorna al massimo 100 risultati.

Per ottenere più risultati, è possibile inviare in querystring il parametro per_page. Esempio:

GET [endpoint]/[risorsa]?per_page=1000

dove 1000 è il massimo valore consentito.

Per ottenere le pagine successive alla prima, è possibile inviare in querystring il parametro page. Esempio:

GET [endpoint]/[risorsa]?per_page=1000&page=2

Se otteniamo una lista vuota, significa ovviamente che non ci sono altre pagine di risultati.

Un altro modo per sapere se è presente un"altra pagina di risultati è cercare negli Header della risposta http una riga di questo tipo:

Link: <https://...../?per_page=xxx&page=x> rel="next"

È possibile prelevare tale URL ed utilizzarlo per richiedere la pagina successiva

Approfondimenti: Autenticazione

Ogni chiamata API può essere autenticata tramite Basic-Authentication HTTP.

In alternativa, è possibile autenticare le chiamate API mediante autenticazione "Bearer", inviando negli Header della richiesta HTTP la seguente riga:

Authorization: Bearer [bearer-token]

dove [bearer-token] è una stringa ottenuta invocando l"API "/authentication" con Basic Authentication.

Richiesta

POST [endpoint]/authentication

includendo gli header di basic authentication.

Risposta (esempio)

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expires": "yyyy-mm-dd hh:mm:ss"
}

Nota: per ogni chiamata API con basic-authentication, viene ritornato negli header della risposta http anche il token per l"autenticazione Bearer e la scadenza del token, in questo formato:

X-auth-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-auth-expires: yyyy-mm-dd hh:mm:ss

Volendo, è dunque possibile effettuare la prima chiamata API con basic-authentication e le successive con bearer-authentication, estrapolando il token Bearer dalla risposta della prima chiamata e senza mai aver invocato esplicitamente l"API di autenticazione

Approfondimenti: Tipi di Spesa

Il campo tipoSpesa deve contenere uno tra i seguenti codici a due lettere.

{
    "TK": "Ticket",
    "FC": "Farmaco",
    "FV": "Farmaco Veterinario",
    "AD": "Acquisto/affitto dispositivo medico",
    "AS": "Spese sanitarie",
    "SR": "Prestazioni sanitarie specialistiche",
    "CT": "Cure termali",
    "PI": "Protesica e integrativa",
    "IC": "Chirurgia/medicina estetica",
    "SP": "Prestazioni sanitarie",
    "SV": "Spese veterinarie",
    "AA": "Altre spese"
}

Approfondimenti: Gestione dell'IVA

Ogni voce di spesa deve specificare il tipo di IVA applicata.

È necessario specificare o il campo aliquotaIVA (con un campo numerico) o il campo naturaIVA col codice indicato dal commercialista.

I valori tipici per aliquotaIVA sono:

10 : aliquota al 10% per Strutture sanitarie (ricovero)
22 : aliquota al 22% per alre attività non sanitarie

I valori tipici per naturaIVA sono:

N4 : Prestazione sanitaria alla persona Esente iva
N2.2 : Soggetto erogatore con regime Forfettario

Non possono essere specificati entrambi i campi aliquotaIVA e naturaIVA per una stessa voce di spesa.

Guida per l"utilizzo delle REST API v.1

Premessa

Endpoint

Gestione degli errori

Paginazione

Autenticazione

Invio di un Documento di Spesa

Lettura

Gestione anagrafica Erogatori

Approfondimenti: Paginazione

Approfondimenti: Autenticazione

Approfondimenti: Tipi di Spesa

Approfondimenti: Gestione dell'IVA

Pagine

Documentazione