Vai al contenuto

API di Verifica Certificati

L'API di verifica certificati permette di verificare l'autenticità di certificati, libretti formativi e attestati di corsi attraverso il loro codice univoco blockchain.

Endpoint

1
GET https://bc.formedil.it/api/verify/:code

Autenticazione

Richiede autenticazione tramite API token.

Parametri URL

Parametro Tipo Descrizione Obbligatorio
code string Codice di verifica nel formato TXID-TIPO-CODICEID Sì

Formato del codice di verifica

Il parametro code deve essere nel formato: TXID-TIPO-CODICEID dove:

  • TXID: Identificativo della transazione blockchain (40 caratteri esadecimali)
  • TIPO: Tipo di documento (libretto, libretto_formatori o persona_corso)
  • CODICEID: Identificativo SHA-1 univoco del documento (40 caratteri esadecimali)

Esempio: 7a89f023cbd4e7a59378ceba27f8654a12f8b987-libretto-5d41402abc4b2a76b9719d911017c592

Risposta

Proprietà della risposta

Campo Tipo Descrizione
code string Codice di verifica inviato nella richiesta
result object o null Risultato della verifica (vedi dettaglio sotto)
error object o null Dettagli dell'errore, se presente

Struttura dell'oggetto result

Campo Tipo Descrizione
verifyStatus string Stato della verifica: 'certified', 'different', 'none', 'bad_txID', 'error'
txID string Identificativo della transazione blockchain
digest string Digest SHA-1 del record
type string Tipo di documento (libretto, libretto_formatori, persona_corso)
sequence number Numero sequenziale del record
createdAt string Data di creazione del record
updatedAt string Data di ultimo aggiornamento del record

Valori possibili per verifyStatus

Valore Descrizione
certified Il documento è verificato e autentico
different Il documento esiste ma il contenuto è stato alterato
none Il documento non è certificato
bad_txID Il TXID fornito non corrisponde a quello registrato nel DB
error Si è verificato un errore durante la verifica

Esempi di risposta

Certificato valido

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "code": "7a89f023cbd4e7a59378ceba27f8654a12f8b987-libretto-5d41402abc4b2a76b9719d911017c592",
  "result": {
    "verifyStatus": "certified",
    "txID": "7a89f023cbd4e7a59378ceba27f8654a12f8b987",
    "digest": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "type": "libretto",
    "sequence": 1,
    "createdAt": "2024-05-15T10:30:00.000Z",
    "updatedAt": "2024-05-15T10:30:00.000Z"
  },
  "error": null
}

Certificato alterato

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "code": "7a89f023cbd4e7a59378ceba27f8654a12f8b987-libretto-5d41402abc4b2a76b9719d911017c592",
  "result": {
    "verifyStatus": "different",
    "txID": "7a89f023cbd4e7a59378ceba27f8654a12f8b987",
    "digest": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "type": "libretto",
    "sequence": 1,
    "createdAt": "2024-05-15T10:30:00.000Z", 
    "updatedAt": "2024-05-15T10:30:00.000Z"
  },
  "error": null
}

TXID non valido

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "code": "wrongtxid-libretto-5d41402abc4b2a76b9719d911017c592",
  "result": {
    "verifyStatus": "bad_txID",
    "txID": "wrongtxid",
    "digest": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "type": "libretto",
    "sequence": 0,
    "createdAt": null,
    "updatedAt": null
  },
  "error": null
}

Errore - Codice non valido

1
2
3
4
5
6
7
8
{
  "code": "invalid-code",
  "result": null,
  "error": {
    "statusCode": 400,
    "message": "Invalid check token format, expected 3 parts"
  }
}

Errore - Certificato non trovato

1
2
3
4
5
6
7
8
{
  "code": "7a89f023cbd4e7a59378ceba27f8654a12f8b987-libretto-nonexistent",
  "result": null,
  "error": {
    "statusCode": 404,
    "message": "Il soggetto nonexistent non è stato trovato"
  }
}

Codici di stato HTTP

Codice Descrizione
200 Richiesta completata con successo
400 Richiesta non valida (formato del codice errato)
401 Autenticazione fallita
404 Certificato non trovato
500 Errore del server

Implementazione di esempio

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
async function verificaCertificato(code) {
  const response = await fetch(`https://bc.formedil.it/api/verify/${code}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  return await response.json();
}

Per ulteriori esempi di implementazione, consultare la guida agli esempi.