ExistBefore

Guida all'attestazione bulk

Hai già gli hash. Salta il browser.

Se la tua pipeline produce ogni giorno una cohort di hash SHA-256 pre-calcolati — ricevute, contratti, archivi di log, artefatti di build, dati scientifici — incollarli uno alla volta su existbefore.com è lo strumento sbagliato. Il flusso web è ottimizzato per un singolo utente che attesta un singolo artefatto. Per i lotti, gli strumenti giusti sono l'SDK CertiSigma (Python, JavaScript, Go, PHP) e il Census CLI — stessa firma T0 ECDSA, stesso timestamp qualificato eIDAS T1, stesso anchor Bitcoin T2, senza browser nel mezzo.

Leggi la documentazione SDK Parla con sales per un contratto enterprise

Una chiave sviluppatore basta per iniziare. Un contratto enterprise serve per volume con SLA, chiavi dedicate e webhook.

Perché non il flusso web?

SDK CertiSigma (Python).

Itera sul tuo lotto, attesta ciascun hash, persisti gli ID di attestazione restituiti. L'SDK gestisce connection pooling, retry con backoff esponenziale e tipi di errore strutturati.

import os
from certisigma import CertiSigmaClient, CertiSigmaError

# Best practice: leggi la API key dall'ambiente, mai hard-coded.
client = CertiSigmaClient(api_key=os.environ["CERTISIGMA_API_KEY"])

# `batch` è il tuo input: un iterable di coppie (logical_id, sha256_hex).
# In produzione di solito è una query DB, un lettore CSV, o l'output
# di una pipeline di build.
batch = [
    ("ricevuta_2026-04-22_001", "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"),
    ("ricevuta_2026-04-22_002", "b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1"),
    # ... migliaia in più ...
]

results = []
for logical_id, hash_hex in batch:
    try:
        att = client.attest_hash(hash_hex)
        results.append((logical_id, att.attestation_id, att.registered_at))
    except CertiSigmaError as exc:
        # Mantieni la riga, marca come fallita; riconcilia dopo. NON
        # interrompere l'intero batch su un singolo errore.
        results.append((logical_id, None, str(exc)))

# Persisti `results` così un job downstream può fare polling su T1/T2 —
# oppure configura un webhook sulla tua chiave enterprise e salta il polling.

SDK CertiSigma (JavaScript / Node).

Stessa forma, con concorrenza Promise nativa. Calibra il limite di concorrenza al rate limit del tuo contratto — l'SDK applica backpressure invece di scartare richieste.

import { CertiSigmaClient } from '@certisigma/sdk';

// Best practice: leggi la API key dall'ambiente, mai hard-coded.
const client = new CertiSigmaClient({
  apiKey: process.env.CERTISIGMA_API_KEY,
  // Calibra al burst limit del tuo contratto. Default conservativi sotto.
  maxConcurrent: 8,
});

const batch = [
  ['ricevuta_2026-04-22_001', 'a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90'],
  ['ricevuta_2026-04-22_002', 'b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1'],
  // ... migliaia in più ...
];

const results = await Promise.allSettled(batch.map(async ([logicalId, hashHex]) => {
  const att = await client.attestHash(hashHex);
  return { logicalId, attestationId: att.attestationId, registeredAt: att.registeredAt };
}));

// `results` è un array di { status: 'fulfilled'|'rejected', value|reason }.
// Persisti i successi, riprova i rejection con backoff esponenziale.

Census CLI (senza API key, rate limit pubblici).

Per batch occasionali fino a qualche centinaio di hash, il Census CLI è la via più veloce. Usa gli stessi endpoint pubblici di ExistBefore (nessuna API key, rate limit pubblici per IP) e legge gli hash da stdin o da file.

# Pipea una lista di hash SHA-256 (uno per riga) direttamente in census attest.
# Si applicano i rate limit pubblici — ok per batch ad-hoc, non per cohort notturne.
cat hashes.txt | census attest --json > attestations.json

# attestations.json è un array JSON di { hash_hex, attestation_id, registered_at }.
# Per batch più grandi con SLA, passa all'SDK con una chiave enterprise.

Installazione: pip install certisigma-census oppure npm install -g @certisigma/census.

Callback di stato (webhook).

Per i contratti enterprise puoi registrare un URL webhook una volta sola. Ogni volta che un'attestazione attraversa un confine di tier (T0 → T1, T1 → T2), CertiSigma fa POST di un payload firmato al tuo endpoint. Il tuo database di tracking riceve l'aggiornamento senza polling.

# Registra un webhook (setup una tantum, dal portale sviluppatori o dall'API).
curl -X POST https://api.certisigma.ch/webhooks \
  -H "Authorization: Bearer $CERTISIGMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://il-tuo-sistema.example.com/certisigma-webhook",
    "events": ["attestation.t1_confirmed", "attestation.t2_confirmed"]
  }'

# CertiSigma fa POST al tuo URL con un payload firmato:
# {
#   "event": "attestation.t1_confirmed",
#   "attestation_id": "att_...",
#   "hash_hex": "...",
#   "t1": { "timestamp_token": "...", "tsa": "...", "registered_at": "..." }
# }
# Verifica la firma con la chiave pubblica da /keys/{webhook_signing_key_id}.

Prossimi passi.

Apri la documentazione SDK Contratto enterprise

FAQ

Posso usare la stessa chiave API per l'SDK e per il flusso web? No. Il flusso web usa una chiave proxy server-side gestita da ExistBefore. La tua chiave SDK è solo tua — emessa per la tua organizzazione, scopata su attest e con rate limit secondo il tuo contratto.

L'SDK conserva gli hash da qualche parte? No. L'SDK inoltra solo gli hash all'API. La persistenza (quali hash hai attestato, con quali ID logici) è tua responsabilità — tipicamente una colonna del database accanto al record originale.

Cosa succede se la rete cade a metà batch? L'SDK riprova con backoff esponenziale. Esaurito il budget di retry, la chiamata solleva un errore strutturato che puoi catturare e riconciliare dopo. Idempotenza: ri-attestare lo stesso hash restituisce lo stesso ID di attestazione — mai un duplicato.

Posso attestare 1 milione di hash al giorno? Sì — ma non sul rate limit gratuito pubblico. Un contratto enterprise dimensiona rate limit e SLA al tuo carico di picco.