Vai al contenuto principale
Certyneo
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.

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 è gratuita e illimitata. La produzione funziona con pagamento per firma (a partire da 0,40 € la firma AES con deggressione per volume), senza abbonamento minimo. Il piano Enterprise include un SLA rafforzato, IP whitelisting e un account tecnico dedicato.

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).

Pronto per integrare la firma elettronica?

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

Leggi la documentazione Parla con uno sviluppatore Certyneo