API REST — eIDAS

L'API di firma elettronica per gli sviluppatori

Integra la firma elettronica eIDAS nella tua applicazione: API REST, webhook firmati HMAC, firma integrata in iframe e chiavi di test gratuite già con l'account gratuito.

Crea un account sviluppatore Documentazione API

Chiavi di test gratuite · SLA 99,9 % (Business ed Enterprise) · Hosting nell'UE

API REST + OpenAPI

Endpoint prevedibili, JSON pulito, codici HTTP standard. Specifica OpenAPI scaricabile per generare i tuoi client.

Webhook affidabili

5 tentativi con intervalli crescenti, firma HMAC SHA-256, eventi falliti reinviabili dal dashboard. Nessun polling da scrivere.

Conformità eIDAS nativa

Firme semplice, avanzata (OTP via SMS) e qualificata, scelte per busta con il campo signatureLevel. Audit trail con marca temporale allegato a ogni documento firmato.

Ospitata nell'UE

Server in Germania, Francia e Spagna. Limiti di frequenza pubblicati per piano e header X-RateLimit in ogni risposta. SLA 99,9 % su Business ed Enterprise.

Avvio in tre chiamate

Carica il PDF, crea la busta, inviala: bastano tre richieste HTTP.

cURL — caricare, creare, inviare

# 1. Upload the PDF
curl https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -F "file=@contrat.pdf"
# → { "id": "cm8doc...", "status": "READY", ... }

# 2. Create the envelope (draft)
curl https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cm8doc..."],
    "recipients": [{ "email": "client@example.com", "name": "Jane Doe" }]
  }'
# → { "id": "cm8env...", "status": "DRAFT", ... }

# 3. Send the invitations
curl -X POST https://certyneo.com/api/v1/envelopes/cm8env.../send \
  -H "Authorization: Bearer $CERTYNEO_API_KEY"

POST /documents restituisce l'identificativo del PDF, POST /envelopes crea una bozza con i firmatari, poi POST /envelopes/:id/send invia gli inviti. L'avanzamento arriva poi via webhook.

Node.js — fetch nativo, senza dipendenze

// Node 18+ — native fetch, no dependency
import { readFile } from "node:fs/promises";

const API = "https://certyneo.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF
const form = new FormData();
const pdf = new Blob([await readFile("contrat.pdf")], { type: "application/pdf" });
form.append("file", pdf, "contrat.pdf");
const doc = await (await fetch(`${API}/documents`, { method: "POST", headers: auth, body: form })).json();

// 2. Create the envelope (draft)
const envelope = await (await fetch(`${API}/envelopes`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    subject: "Contrat de prestation",
    documentIds: [doc.id],
    recipients: [{ email: "client@example.com", name: "Jane Doe" }],
  }),
})).json();

// 3. Send the invitations
await fetch(`${API}/envelopes/${envelope.id}/send`, { method: "POST", headers: auth });

Nessun SDK necessario: l'API si usa con il fetch nativo di Node 18 o con qualsiasi client HTTP. La specifica OpenAPI permette anche di generare un client tipizzato nel tuo linguaggio.

Webhook — reagisci in tempo reale

Gli eventi di busta e destinatario, firma HMAC verificabile e rilancio automatico.

envelope.completed

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "subject": "Contrat de prestation",
    "status": "COMPLETED",
    "completedAt": "2026-09-26T08:42:13.000Z",
    "recipientCount": 1,
    "recipients": [
      { "email": "client@example.com", "name": "Jane Doe", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/...pdf?X-Amz-Expires=604800&..."
  },
  "timestamp": "2026-09-26T08:42:13.521Z"
}

Firma HMAC SHA-256 di ogni payload — verifica l'autenticità lato server.
Retry automatico in caso di errore temporaneo: 5 tentativi in circa 1 h 20 con backoff esponenziale.
Gli eventi falliti sono elencati nel dashboard e si possono reinviare con un clic. Dopo 5 errori consecutivi, l'endpoint viene sospeso e ricevi un avviso.
Fino a 5 endpoint in Standard, 15 in Business e 50 in Business Pro, ognuno iscritto agli eventi che scegli.

Perché un'API dedicata alla firma elettronica?

Integrare la firma elettronica nel tuo prodotto non è banale. Hai bisogno di garanzie sulla conformità legale (eIDAS), l'affidabilità tecnica (webhook che arrivano davvero) e la sovranità dei dati (hosting europeo per evitare il Cloud Act). L'API Certyneo copre tutti e tre gli aspetti.

Progettata da e per sviluppatori, segue le convenzioni REST: versione nell'URL (/api/v1), paginazione con page e limit, errori JSON con un codice leggibile dalla macchina, specifica OpenAPI per generare i tuoi client. Niente SOAP, niente XML, nessuna sorpresa.

Conformità eIDAS spiegata per gli sviluppatori

Il regolamento eIDAS definisce tre livelli di firma: semplice (SES), avanzata (AES) e qualificata (QES). L'API Certyneo permette di scegliere il livello di ogni busta con il campo signatureLevel: SIMPLE (predefinito), ADVANCED o QUALIFIED. La firma semplice copre la maggior parte dei contratti commerciali correnti; la QES serve quando una norma o un destinatario richiede l'equivalenza con la firma autografa.

Sul piano tecnico, il livello avanzato attiva automaticamente l'OTP via SMS e richiede un numero di telefono per ogni firmatario. L'audit trail riceve una marca temporale secondo lo standard RFC 3161. La QES si basa su un certificato qualificato emesso da un prestatore di servizi fiduciari qualificato dell'UE. Tutto si gestisce tramite l'API.

Architettura d'integrazione consigliata

Il pattern d'integrazione più comune segue questo flusso:

Il tuo backend carica il PDF (POST /api/v1/documents), crea la busta in bozza (POST /api/v1/envelopes), poi la invia (POST /api/v1/envelopes/:id/send).
Il firmatario riceve l'invito via e-mail, oppure firma direttamente nella tua interfaccia grazie alla firma integrata in iframe (POST /api/v1/envelopes/:id/embed-url, dal piano Standard).
Una volta completata la firma, Certyneo chiama il tuo webhook con l'evento envelope.completed.
Aggiorni il database e notifichi l'utente (email, in-app, ecc.).

Chiavi di test gratuite

Le chiavi sk_test_ sono disponibili su tutti i piani, compreso Gratuito, e le buste di test non consumano la tua quota mensile. Sul piano Gratuito possono essere indirizzate solo al tuo indirizzo e-mail e sono limitate a 20 richieste all'ora; i piani a pagamento vanno da 200 a 1.000 richieste all'ora. I dati di test vengono cancellati dopo 30 giorni. La prima chiave di test di un account gratuito sblocca inoltre un mese di piano Standard in omaggio.

E se non vuoi scrivere codice

Tutto ciò che fa questa API può essere controllato anche senza scrivere una riga, da un flusso: creare una busta, inviarla, reagire a una firma, recuperare il PDF sigillato e la sua traccia di audit. La stessa base, con un progettista visivo al posto del client HTTP. Vedi l'integrazione Power Automate e Microsoft 365.

Migrazione da DocuSign o Yousign

Se hai già un'integrazione di firma con DocuSign o Yousign, il vocabolario è simile: envelopes → envelopes, recipients → recipients, webhook di stato → webhook. La guida alla migrazione da DocuSign e Yousign a Certyneo descrive i passaggi, dall'esportazione dei modelli al passaggio dei webhook.

State migrando da Adobe Acrobat Sign (precedentemente EchoSign, poi Adobe Sign)? Il mapping è altrettanto diretto — agreements → envelopes, participants → recipients, webhooks → webhooks. Confronta Certyneo e Adobe Acrobat Sign →

Prezzo di un'API di firma elettronica: dove acquistare un abbonamento?

Non servono preventivi né ordini di acquisto per sottoscrivere un abbonamento API di firma: le chiavi di test sono gratuite, la chiave API si genera dal dashboard e l'accesso all'API REST di produzione è incluso già nel piano Standard a 19 €/mese — webhook compresi, senza costi per firma semplice.

Standard — 19 €/mese: 100 buste/mese, API REST + webhook, 10 utenti
Business — 39 €/mese: 300 buste/mese, invio in gruppo, moduli web
Business Pro — 99 €/mese: 1.000 buste/mese, API ad alta frequenza (300 req/min), utenti illimitati

La firma qualificata (QES) è fatturata a consumo e pagata all'invio: 9,90 € per firma con un abbonamento, addebitati sulla carta registrata una volta esaurite le QES incluse in Business e Business Pro, e 14,90 € senza abbonamento.

Per volumi importanti o un'esigenza di impegno contrattuale (SLA, DPA dedicato, fatturazione annuale), il piano Enterprise si sottoscrive presso l'équipe commerciale. In tutti i casi, i prezzi sono pubblici — confrontali prima di impegnarti.

Per approfondire

Domande frequenti — API

Qual è il rate limit dell'API?

Il limite si applica a ogni chiave, al minuto, in base al piano: 60 richieste in Standard, 120 in Business, 300 in Business Pro e 1.000 in Enterprise. Ogni risposta contiene gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; oltre il limite, l'API restituisce 429 con un header Retry-After.

Quanto costa l'API?

Le chiavi di test (sk_test_) sono gratuite su tutti i piani. L'accesso all'API REST di produzione è incluso già nel piano Standard a 19 €/mese (100 buste/mese), poi Business a 39 €/mese e Business Pro a 99 €/mese con quote crescenti; la firma qualificata (QES) è fatturata a consumo, 9,90 € con un abbonamento. Per volumi superiori, il piano Enterprise si sottoscrive presso il team commerciale.

C'è un SLA?

Sì: 99,9 % di disponibilità mensile sui piani Business ed Enterprise, con un credito in fattura dal 10 al 50 % secondo lo scostamento rilevato. Lo stato del servizio è pubblicato in tempo reale sulla pagina di stato di Certyneo.

Quale autenticazione utilizzate?

Una chiave API nell'header Authorization (Bearer sk_live_… o sk_test_…). Le chiavi si creano e si revocano dal dashboard, con effetto immediato. Per un'applicazione di terze parti che agisce per conto dei tuoi utenti, è disponibile OAuth 2.0 con il flusso authorization code e PKCE.

Come verificare la firma HMAC di un webhook?

Ogni webhook porta la sua firma nell'header X-Certyneo-Signature: l'HMAC SHA-256, in esadecimale, del corpo grezzo della richiesta, calcolato con il secret del tuo endpoint. Ricalcolalo lato server sul corpo non modificato e confronta in tempo costante (crypto.timingSafeEqual in Node, hmac.compare_digest in Python).

Esiste un SDK ufficiale?

Non ancora pubblicato. L'API si chiama direttamente via HTTP da qualsiasi linguaggio, e la specifica OpenAPI permette di generare un client tipizzato con openapi-generator o uno strumento equivalente. Senza codice, Certyneo è disponibile anche su Make, n8n, Postman e RapidAPI.

Posso testare senza pagare?

Sì: crea un account gratuito e genera una chiave sk_test_ dal dashboard. La prima chiave di test di un account gratuito sblocca anche un mese di piano Standard in omaggio. La collection Postman permette di concatenare le prime chiamate senza scrivere codice.

Quanto costa l'API EchoSign (diventata Adobe Acrobat Sign)?

EchoSign è stata acquisita da Adobe nel 2011 e rinominata Adobe Sign, poi Adobe Acrobat Sign: l'API esiste ancora, ma il suo prezzo non è pubblico e passa da un preventivo aziendale del team commerciale di Adobe, di solito per fasce di transazioni annue. Certyneo, al contrario, pubblica i suoi prezzi: l'accesso all'API di firma in produzione è incluso già nel piano Standard a 19 €/mese, sottoscritto online senza preventivo, con chiavi di test gratuite per valutare l'API prima di pagare.

Pronto per integrare la firma elettronica?

Chiavi di test gratuite, specifica OpenAPI, webhook firmati. Inizia ora.

Leggi la documentazione Parla con uno sviluppatore Certyneo