Per sviluppatori e partner

API HTTP

Il motore di attestazione espone un'API REST pubblica, documentata in formato aperto OpenAPI 3.0 — la stessa che usa questo sito.

La Swagger UI include "Try it out": puoi chiamare gli endpoint direttamente dal browser, senza scrivere codice, per esplorare richieste e risposte.

Da terminale e da CI

Lo stesso pacchetto npm porta anche sg-attest, una riga di comando: attesta e verifica senza aprire il browser. L'impronta è calcolata leggendo il file a flusso dal disco — il file non lascia la tua macchina — e qui non c'è alcun tetto di dimensione: il limite di 1 GB del sito è imposto dal browser, non dal servizio.

npx -y -p @spazio-genesi/attest-mcp sg-attest authorize
npx -y -p @spazio-genesi/attest-mcp sg-attest attest opera.zip --pdf certificato.pdf

Con authorize autorizzi una volta dal browser (24 ore, 20 attestazioni); se hai una chiave API, basta la variabile d'ambiente IMGAUTH_API_KEY e l'autorizzazione non serve. Ogni comando accetta --json per un output leggibile da uno script, e restituisce 0 se è andata bene, 1 in caso di errore, 2 quando una verifica dà esito negativo.

attest senza --pdf calcola solo l'impronta e la firma (nulla viene archiviato: nessuna pagina pubblica di verifica); aggiungi --pdf <file> per generare anche il certificato firmato — solo allora l'opera è archiviata e la sua pagina /c/<impronta> esiste davvero.

Niente Node.js sulla macchina o sul runner? C'è anche un eseguibile standalone per Linux, macOS e Windows — stessi comandi, nessuna installazione.

In integrazione continua c'è un'azione GitHub pronta, che attesta gli artefatti di build: l'artefatto non lascia il runner, ne viaggia solo l'impronta.

- uses: SPAZIO-GENESI/attest-action@v1
  with:
    files: dist/release.zip
    api-key: ${{ secrets.SG_API_KEY }}

Ogni file attestato riceve un certificato firmato e archiviato, e la sua pagina permanente /c/<impronta> resta verificabile molto dopo che il log del job è sparito.

Server MCP

Per assistenti e agenti AI (Claude, e in generale ogni client che parla il Model Context Protocol) c'è un server MCP pronto all'uso: attesta e verifica un file restando in locale, calcolando l'impronta sul tuo dispositivo — il file non transita comunque sui nostri server.

Installazione in un client MCP (es. Claude Desktop, Claude Code):

npx -y @spazio-genesi/attest-mcp

Sette strumenti: autorizzazione, attestazione file, download certificato PDF, verifica file, verifica certificato, controllo ancoraggio Bitcoin, stato del servizio.

MCP remoto — zero installazione

Per chi preferisce non installare nulla: lo stesso servizio, raggiungibile aggiungendo un URL come connettore (claude.ai, Claude Code, o qualunque client MCP che parli HTTP Streamable). Nessun upload — l'agente calcola l'impronta SHA-256 eseguendo codice in locale (sha256sum/certutil/shasum) e passa solo quella: il file non transita né dal client né dai nostri server, un livello di privacy superiore anche al bot Telegram.

Nessuna autenticazione richiesta per aggiungere il connettore: strumenti pubblici (stato del servizio, controllo ancoraggio, verifica) subito disponibili; per attestare, l'agente stesso ti guida in un'autorizzazione al volo (link + controllo anti-bot, come sul sito).

Otto strumenti: quattro pubblici (stato del servizio, controllo ancoraggio Bitcoin, verifica attestazione, ricerca certificato) e quattro con credenziale (autorizzazione, completamento autorizzazione, attestazione per impronta, download certificato PDF).

Quale credenziale funziona su quale client

Il protocollo MCP non è uniforme sui client remoti: alcuni permettono di aggiungere header personalizzati, altri no. Questo determina se la tua chiave API (quota Sviluppatore o pool di Convenzione) è utilizzabile o se resta solo l'autorizzazione temporanea in sessione — meglio saperlo prima di scegliere il client, non scoprirlo a metà integrazione.

In breve: se hai una chiave e vuoi che le tue attestazioni contino sulla tua quota o convenzione, usa Claude Code (o un client con header) oppure il pacchetto locale @spazio-genesi/attest-mcp. Su claude.ai l'attestazione funziona, ma sempre con un'autorizzazione temporanea indipendente — il ponte chiave↔claude.ai (OAuth sul server MCP) è un possibile sviluppo futuro, non ancora costruito.

Come si ottiene l'accesso

Le richieste automatiche (API o MCP) passano dallo stesso motore del sito, con due modalità di accesso:

• Autorizzazione al volo (per provare subito). Il server MCP — o una tua integrazione — apre un link che confermi tu stesso con un rapido controllo anti-bot: da quel momento hai un accesso valido 24 ore, fino a 20 attestazioni. Nessuna registrazione, nessuna password permanente.
• Chiave API self-service (per integrazioni continuative). Confermi la tua email con Google, Microsoft o LinkedIn e ricevi subito una chiave con 50 attestazioni al mese, revocabile in qualsiasi momento. Nessuna password nostra, nessuna attesa.
  Ottieni una chiave API
• Produzione e quote più alte. Oltre le 50 attestazioni al mese la strada self-service è la fascia Professionale (200 attestazioni al mese, stessa identità email, anche via API). Per convenzioni e accordi di partenariato scrivici a [email protected] descrivendo il caso d'uso previsto.

La tua app in produzione: due modelli

Se costruisci un'applicazione che integra l'attestazione, in produzione hai due strade — non si escludono, dipende da chi possiede l'identità che finisce sul certificato.

Hai costruito un'integrazione (modello A o B)? Candidala alla vetrina pubblica Integrazioni dal tuo profilo — la pubblicazione è verificata a mano dal gestore prima di andare online.