API REST eIDAS

Kehittäjien sähköisen allekirjoituksen API

Integroi eIDAS-sähköinen allekirjoitus sovellukseesi: REST-API, HMAC-allekirjoitetut webhookit, iframeen upotettu allekirjoitus ja ilmaiset testiavaimet jo ilmaisella tilillä.

Luoda kehittäjätili API-asiakirjat

Ilmaiset testiavaimet · SLA 99,9 % (Business ja Enterprise) · Ylläpito EU:ssa

REST ja OpenAPI

Ennustettavat päätepisteet, siisti JSON, vakiomuotoiset HTTP-koodit. Ladattava OpenAPI-määrittely omien asiakaskirjastojen generointiin.

Luotettavat verkkosivut

5 yritystä kasvavin viivein, HMAC SHA-256 -allekirjoitus, epäonnistuneet tapahtumat voi toistaa hallintapaneelista. Ei pollausta koodattavaksi.

EIDAS-muotoinen vaatimustenmukaisuus

Yksinkertainen, kehittynyt (OTP tekstiviestillä) ja hyväksytty allekirjoitus, valitaan kirjekuorikohtaisesti kentällä signatureLevel. Aikaleimattu kirjausketju liitetään jokaiseen allekirjoitettuun asiakirjaan.

Ylläpito EU:ssa

Palvelimet Saksassa, Ranskassa ja Espanjassa. Julkaistut pakettikohtaiset pyyntörajat ja X-RateLimit-otsakkeet jokaisessa vastauksessa. SLA 99,9 % paketeissa Business ja Enterprise.

Käyntiin kolmella kutsulla

Lataa PDF, luo kirjekuori, lähetä se: kolme HTTP-pyyntöä riittää.

cURL — lataa, luo, lähetä

# 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 palauttaa PDF:n tunnisteen, POST /envelopes luo luonnoksen allekirjoittajineen, ja POST /envelopes/:id/send lähettää kutsut. Eteneminen saapuu sen jälkeen webhookilla.

Node.js — natiivi fetch, ei riippuvuuksia

// 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 });

SDK:ta ei tarvita: API:a käytetään Node 18:n natiivilla fetchillä tai millä tahansa HTTP-asiakkaalla. OpenAPI-määrittelyllä voit myös generoida tyypitetyn asiakkaan omalla kielelläsi.

Webhooks reaaliaikainen reagointi

Kirjekuoren ja vastaanottajan tapahtumat, verifioimattava HMAC-allekirjoitus ja automaattinen uudelleenyritys.

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"
}

HMAC SHA-256 - allekirjoitus jokaisesta hyödykkeet tarkista serverin puolella.
Automaattinen uudelleen yritys väliaikaisen virheen sattuessa: 5 yritystä noin 1 h 20 minuutissa eksponentiaalisella backoff-strategialla.
Epäonnistuneet tapahtumat näkyvät hallintapaneelissa, ja ne voi toistaa yhdellä napsautuksella. Kun 5 peräkkäistä yritystä epäonnistuu, päätepiste keskeytetään ja saat ilmoituksen.
Enintään 5 päätepistettä paketissa Standard, 15 paketissa Business ja 50 paketissa Business Pro, kukin tilattuna valitsemiisi tapahtumiin.

Miksi käytämme sähköistä allekirjoitusta varten API:tä?

Sähköisen allekirjoituksen integrointi tuotteeseesi on vaikeaa, sillä tarvitset laillista vaatimustenmukaisuutta (eIDAS), teknistä luotettavuutta (tosi-asiaiset webhooks) ja tietosuojakysymystä (Euroopan verkkosivusto Cloud Actin välttämiseksi).

Se on kehittäjien suunnittelema kehittäjille ja noudattaa REST-käytäntöjä: versio URL-osoitteessa (/api/v1), sivutus parametreilla page ja limit, JSON-virheet koneluettavalla koodilla, OpenAPI-määrittely asiakkaiden generointiin. Ei SOAPia, ei XML:ää, ei yllätyksiä.

EIDAS-vaatimustenmukaisuus selvitetty kehittäjille

eIDAS-asetus määrittelee kolme allekirjoitustasoa: yksinkertainen (SES), kehittynyt (AES) ja hyväksytty (QES). Certyneon API:ssa taso valitaan kullekin kirjekuorelle kentällä signatureLevel: SIMPLE (oletus), ADVANCED tai QUALIFIED. Yksinkertainen allekirjoitus riittää useimpiin tavallisiin kaupallisiin sopimuksiin; QES:ää käytetään, kun laki tai vastaanottaja edellyttää vastaavuutta käsin kirjoitetun allekirjoituksen kanssa.

Teknisesti kehittynyt taso ottaa automaattisesti käyttöön tekstiviesti-OTP:n ja vaatii puhelinnumeron jokaiselta allekirjoittajalta. Kirjausketju aikaleimataan standardin RFC 3161 mukaisesti. QES perustuu hyväksyttyyn varmenteeseen, jonka myöntää EU:n hyväksytty luottamuspalvelun tarjoaja. Kaikkea ohjataan API:n kautta.

Suositeltu integrointirakenne

Yleisin integrointitapaus on seuraava:

Taustajärjestelmäsi lataa PDF:n (POST /api/v1/documents), luo kirjekuoren luonnoksena (POST /api/v1/envelopes) ja lähettää sen sitten (POST /api/v1/envelopes/:id/send).
Allekirjoittaja saa kutsunsa sähköpostitse tai allekirjoittaa suoraan käyttöliittymässäsi iframeen upotetun allekirjoituksen avulla (POST /api/v1/envelopes/:id/embed-url, Standard-paketista alkaen).
Kun allekirjoitus on tehty, Certyneo kutsuu webhookilleen enveloppi.completed-tapahtuman.
Päivität tietokannasi ja ilmoitat käyttäjälle (sähköposti, sovelluksessa jne.).

Ilmaiset testiavaimet

sk_test_-avaimet ovat saatavilla kaikissa paketeissa, myös Ilmainen-paketissa, eivätkä testikirjekuoret kuluta kuukausikiintiötäsi. Ilmainen-paketissa ne voi osoittaa vain omaan sähköpostiosoitteeseesi, ja ne on rajattu 20 pyyntöön tunnissa; maksulliset paketit nostavat rajan 200:sta 1 000 pyyntöön tunnissa. Testitiedot poistetaan 30 päivän kuluttua. Ilmaisen tilin ensimmäinen testiavain avaa lisäksi kuukauden maksuttoman Standard-paketin.

Entä jos et halua kirjoittaa koodia

Kaikki mitä tämä API tekee, voidaan myös ohjata ilman yhden rivin kirjoittamista työnkulusta: luo kirjekuori, lähetä se, reagoi allekirjoitukseen, hae sinetöity PDF ja sen tarkastusjälki. Sama perusta, visuaalisen suunnittelijan sijasta HTTP-asiakasohjelmaa. Katso Power Automate- ja Microsoft 365 -integraatio.

DocuSignistä tai Yousignista siirtyminen

Jos sinulla on jo DocuSign- tai Yousign-integraatio, sanasto on tuttu: envelopes → envelopes, recipients → recipients, tilawebhookit → webhookit. Siirtymäopas DocuSignista ja Yousignista Certyneoon kuvaa vaiheet mallien viennistä webhookien vaihtamiseen.

Siirryt Adobe Acrobat Signista (entinen EchoSign, sitten Adobe Sign)? Vastaaminen on yhtä suoraviivaista – agreements → envelopes, participants → recipients, webhooks → webhooks. Vertaile Certyneota ja Adobe Acrobat Signia →

Sähköisen allekirjoituksen API:n hinta: mistä ostaa tilaus?

API-allekirjoitustilauksen ostamiseen ei tarvita tarjousta eikä ostotilausta: testiavaimet ovat ilmaisia, API-avain luodaan hallintapaneelista, ja tuotanto-REST-API:n käyttö sisältyy jo Standard-pakettiin hintaan 19 €/kk — webhookit mukaan lukien, ilman maksua yksinkertaisesta allekirjoituksesta.

Standard — 19 €/kk: 100 kirjekuorta/kk, REST-API + webhookit, 10 käyttäjää
Business — 39 €/kk: 300 kirjekuorta/kk, joukkolähetys, verkkolomakkeet
Business Pro — 99 €/kk: 1 000 kirjekuorta/kk, korkean frekvenssin API (300 pyynnöt/min), rajoittamattomat käyttäjät

Hyväksytty allekirjoitus (QES) laskutetaan kappalekohtaisesti ja maksetaan lähetyksen yhteydessä: 9,90 € allekirjoitukselta tilauksen kanssa, veloitettuna tallennetulta kortilta, kun Business- ja Business Pro -pakettien sisältämät QES:t on käytetty, ja 14,90 € ilman tilausta.

Suurille volyymeille tai sopimussitoumuksen tarpeeseen (SLA, omistautunut DPA, vuosittainen laskutus), Enterprise-suunnitelma otetaan käyttöön myyntitiiminä. Joka tapauksessa hinnat ovat julkisia — vertaile niitä ennen sitoumukseen ryhtymistä.

Syvennä osaamistasi

Kysymysten torstai API

Mikä on API:n rajoitus?

Raja koskee kutakin avainta minuuttikohtaisesti paketin mukaan: 60 pyyntöä paketissa Standard, 120 paketissa Business, 300 paketissa Business Pro ja 1 000 paketissa Enterprise. Jokaisessa vastauksessa on otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset; rajan ylittyessä API palauttaa 429 ja otsakkeen Retry-After.

Paljonko API maksaa?

Testiavaimet (sk_test_) ovat ilmaisia kaikissa paketeissa. Tuotanto-REST-API:n käyttö sisältyy jo Standard-pakettiin 19 €/kk (100 kirjekuorta/kk), sitten Business 39 €/kk ja Business Pro 99 €/kk kasvavin kiintiöin; hyväksytty allekirjoitus (QES) laskutetaan kappalekohtaisesti, 9,90 € tilauksen kanssa. Suuremmille volyymeille Enterprise-paketti tilataan myyntitiimin kautta.

Onko ALS?

Kyllä: 99,9 % kuukausittainen käytettävyys Business- ja Enterprise-paketeissa, ja laskulle hyvitys 10–50 % todetun poikkeaman mukaan. Palvelun tila julkaistaan jatkuvasti Certyneon tilasivulla.

Mitä tunnistusmenetelmää käytät?

API-avain Authorization-otsakkeessa (Bearer sk_live_… tai sk_test_…). Avaimet luodaan ja peruutetaan hallintapaneelista välittömästi. Kolmannen osapuolen sovellukselle, joka toimii käyttäjiesi puolesta, on tarjolla OAuth 2.0 authorization code -kululla ja PKCE:llä.

Miten tarkistaa HMAC-signaali verkkouukon?

Jokaisessa webhookissa on allekirjoitusotsake X-Certyneo-Signature: pyynnön raa'an rungon HMAC SHA-256 heksadesimaalimuodossa, laskettuna päätepisteesi salaisuudella. Laske se uudelleen palvelimella muuttamattomasta rungosta ja vertaa vakioajassa (crypto.timingSafeEqual Nodessa, hmac.compare_digest Pythonissa).

Onko virallista SDK:ta?

Ei vielä julkaistu. API:a kutsutaan suoraan HTTP:llä millä tahansa kielellä, ja OpenAPI-määrittelyllä voi generoida tyypitetyn asiakkaan openapi-generatorilla tai vastaavalla työkalulla. Ilman koodia Certyneo on saatavilla myös Makessa, n8n:ssä, Postmanissa ja RapidAPI:ssa.

Voinko testata maksamatta?

Kyllä: luo ilmainen tili ja generoi sk_test_-avain hallintapaneelista. Ilmaisen tilin ensimmäinen testiavain avaa myös kuukauden maksuttoman Standard-paketin. Postman-kokoelmalla voit ketjuttaa ensimmäiset kutsut kirjoittamatta koodia.

Kuinka paljon EchoSign-API (nyt Adobe Acrobat Sign) maksaa?

Adobe osti EchoSignin vuonna 2011, ja se nimettiin ensin Adobe Signiksi ja sitten Adobe Acrobat Signiksi: API on yhä olemassa, mutta sen hinta ei ole julkinen, vaan se edellyttää yritystarjousta Adoben myyntitiimiltä, yleensä vuosittaisten transaktioiden portaina. Certyneo sen sijaan näyttää hintansa: tuotanto-API:n käyttö sisältyy jo Standard-pakettiin hintaan 19 €/kk, tilattavissa verkossa ilman tarjousta, ja ilmaisilla testiavaimilla voit arvioida API:n ennen maksamista.

Oletko valmis ottamaan sähköisen allekirjoituksen käyttöön?

Ilmaiset testiavaimet, OpenAPI-määrittely, allekirjoitetut webhookit. Aloita nyt.

Lue asiakirjat Keskustelu Certyneon kehittäjän kanssa