API REST — eIDAS

L'API di firma elettronica per gli sviluppatori

Integra la firma elettronica eIDAS nella tua applicazione in poche ore. REST, webhook affidabili, SDK Node/Python/Ruby, sandbox gratuito illimitato.

Crea un account sviluppatore Documentazione API

Sandbox gratuito · 99,95 % uptime · Hosting sovrano UE

REST + OpenAPI 3.1

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

Webhook affidabili

Retry automatico con backoff esponenziale, firma HMAC SHA-256, registro eventi consultabile. Niente polling da codificare.

Conformità eIDAS nativa

Firme AES, AES-Q e QES disponibili tramite flag API. Traccia di audit qualificata inclusa, certificati TSP qualificati UE.

Latenza < 200 ms

API ospitata a Strasburgo (UE), p95 < 200 ms dall'Europa. SLA 99,95 % uptime, stato pubblico tempo reale.

Avvio in 5 minuti

Crea la tua prima busta con una singola richiesta HTTP.

cURL — Creazione di una busta

curl https://api.certyneo.com/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrat de prestation",
    "documents": [{"file_url": "https://your.app/contract.pdf"}],
    "recipients": [{"email": "client@example.com", "name": "Jane Doe"}],
    "webhook_url": "https://your.app/webhooks/sign"
  }'

Una singola richiesta POST è sufficiente per creare una busta, aggiungere un documento, un firmatario e l'URL del webhook. L'API restituisce un sign_url pronto da condividere.

SDK Node.js ufficiale

import Certyneo from '@certyneo/sdk';

const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY });

const envelope = await client.envelopes.create({
  title: 'Contrat de prestation',
  documents: [{ file_url: 'https://your.app/contract.pdf' }],
  recipients: [{ email: 'client@example.com', name: 'Jane Doe' }],
});

console.log(envelope.sign_url); // ready to share with the signer

L'SDK Node TypeScript fornisce la tipizzazione completa, la gestione automatica degli errori con retry e un builder di busta fluido. Disponibile anche in Python e Ruby.

Webhook — reagisci in tempo reale

Sei eventi (envelope.sent, viewed, signed, completed, declined, expired) con firma HMAC verificabile e retry automatico.

envelope.completed

{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}

Firma HMAC SHA-256 di ogni payload — verifica l'autenticità lato server.
Retry automatico in caso di errore: 5 tentativi in 24 ore con backoff esponenziale.
Registro degli eventi consultabile dal dashboard: visualizza ogni tentativo, lo stato HTTP restituito e il body.
URL del webhook configurabile per busta (override) o globale nel progetto.

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 moderne: pagination cursor-based, idempotency keys, versioning per URL, OpenAPI 3.1 per generare automaticamente i tuoi client. Niente SOAP, niente XML, niente sorprese.

Conformità eIDAS spiegata per gli sviluppatori

Il regolamento eIDAS definisce tre livelli di firma: semplice (SES), avanzata (AES) e qualificata (QES). L'API Certyneo consente di scegliere il livello per busta tramite il campo `signature_level`. Il valore predefinito è AES (sufficiente per il 95% dei casi B2B). La QES è disponibile per gli atti che richiedono un'equivalenza legale ristretta con la firma manuale manuscritta (atti notarili, appalti pubblici).

Dal punto di vista tecnico, AES richiede una forte autenticazione del firmatario (OTP via SMS per impostazione predefinita, KYC video opzionale) e una pista di audit con timestamp. La QES aggiunge un certificato qualificato emesso da un TSP qualificato UE. Tutto questo è gestito dall'API — chiami l'endpoint e ci occupiamo del resto.

Architettura d'integrazione consigliata

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

Il tuo backend chiama POST /v1/envelopes per creare la busta e riceve un sign_url da presentare all'utente.
Reindizzi l'utente verso il sign_url o lo incorpori in un iframe (con il tuo branding tramite il piano Pro).
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.).

Sandbox gratuito illimitato

L'ambiente sandbox è gratuito e illimitato. Tutte le funzionalità di produzione sono disponibili, tranne che le firme non hanno valore legale (il PDF è marcato SANDBOX). Utile per test automatizzati, demo cliente, sviluppo locale. Le chiavi sandbox sono distinte dalle chiavi prod, isolamento totale tra i due.

Migrazione da DocuSign o Yousign

Se dispone già di un'integrazione DocuSign o Yousign, il mapping API è diretto: envelopes → envelopes, recipients → recipients, status webhooks → status webhooks. La nostra guida di migrazione documenta le equivalenze endpoint per endpoint. Conteggi 1-3 giorni per una migrazione completa, molto meno se utilizza un wrapper interno.

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 è necessario un preventivo o un ordine per acquistare un abbonamento API di firma: la sandbox è gratuita e illimitata, la chiave API si genera dal dashboard, e l'accesso all'API REST di produzione è incluso già nel piano Standard a 19 €/mese — webhook e SDK compresi, senza costi per firma.

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) è un prodotto distinto, fatturato per atto: 9,90 € per firma, disponibile su tutti i piani, incluso Gratuito.

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.

Domande frequenti — API

Qual è il rate limit dell'API?

1.000 richieste al minuto per impostazione predefinita, aumentabile su richiesta per usi elevati (factory, piattaforme multi-tenant). L'header X-RateLimit-Remaining su ogni risposta indica la quota rimanente. In caso di superamento, l'API restituisce 429 con un Retry-After.

Quanto costa l'API?

La sandbox (chiavi sk_test_) è gratuita e illimitata. 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) è un prodotto distinto, fatturato per atto 9,90 € per firma. Per volumi superiori o un SLA rafforzato, il piano Enterprise si sottoscrive presso il team commerciale.

C'è un SLA?

99,95% uptime sui piani Business e Enterprise (downtime massimo di 4 ore all'anno). Pagina di stato pubblica con cronologia degli incidenti: status.certyneo.com. Il piano Enterprise include un credito automatico in caso di mancato rispetto dell'SLA.

Quale autenticazione utilizzate?

Bearer token (chiave API) nell'header Authorization. Le chiavi sono ruotabili dal dashboard, con revoca immediata. Per le integrazioni OAuth (piattaforma multi-tenant), proponiamo un OAuth 2.0 Client Credentials sul piano Enterprise.

Come verificare la firma HMAC di un webhook?

Ogni webhook include un header X-Certyneo-Signature contenente un HMAC SHA-256 del payload, firmato con il vostro webhook secret. Sul lato server, ricalcolate l'HMAC e confrontate in tempo costante (timing-safe comparison). L'SDK ufficiale lo fa automaticamente tramite webhook.verify(payload, signature, secret).

Gli SDK sono open source?

Sì. Gli SDK Node, Python e Ruby sono su GitHub con licenza MIT. Potete fare un fork, contribuire o semplicemente esaminarli. I binari sono pubblicati su npm, PyPI e RubyGems sotto il namespace @certyneo / certyneo.

Posso testare senza registrazione?

Sì, tramite gli esempi interattivi della documentazione API: /developers/playground. Le richieste vi girano contro un'istanza sandbox condivisa, senza chiave richiesta. Per un uso serio, create un account sviluppatore gratuito (sandbox illimitata).

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

EchoSign è stato acquisito da Adobe nel 2011, rinominato Adobe Sign poi Adobe Acrobat Sign: l'API esiste ancora, ma il suo prezzo non è pubblico e passa attraverso un preventivo aziendale presso il team commerciale di Adobe, generalmente per tranches di transazioni annuali. Al contrario, Certyneo mostra i suoi prezzi: l'accesso API di produzione è incluso già nel piano Standard a 19 €/mese, sottoscritto online senza preventivo, con una sandbox gratuita illimitata per valutare l'API prima di pagare.

Pronto per integrare la firma elettronica?

Sandbox gratuito illimitato, documentazione completa, SDK ufficiali. Inizia ora.

Leggi la documentazione Parla con uno sviluppatore Certyneo