Kehittäjille
API-dokumentaatio
Signeurin REST-API antaa sovelluksesi luoda allekirjoituspyyntöjä, seurata niiden tilaa ja noutaa lukittuja PDF-tiedostoja. Tämä dokumentaatio kuvaa tällä hetkellä toteutetut päätepisteet.
https://signeur.euAutentikointi
Kaikki API-kutsut vaativat Bearer-tokenin Authorization-otsikossa. Avainparametrit hashataan SHA-256:lla ja verrataan tallennettuun hashiin — plain-textiä ei tallenneta missään.
Esimerkki:
Authorization: Bearer sgn_live_xxx...Hanki API-key palvelun ylläpitäjältä. Avainformaatti on sgn_live_<random>.
Virhevastaukset
Kaikki virheet palautetaan JSON-muodossa kentillä error ja message. HTTP-tilakoodit noudattavat standardia.
{
"error": "invalid_signer_email",
"message": "Field 'signer_email' is missing or not a valid email."
}| Koodi | Merkitys |
|---|---|
400 | Virheellinen pyyntö (validointi ei mene läpi) |
401 | Authorization-otsikko puuttuu tai Bearer-token on virheellinen |
404 | Resurssia ei löytynyt tai se kuuluu toiselle organisaatiolle |
409 | Konflikti: pyyntö on jo allekirjoitettu / ei vielä allekirjoitettu |
410 | Resurssi on vanhentunut (linkki yli 30 päivää vanha) |
429 | Liian monta pyyntöä — odota Retry-After-otsakkeen ilmoittama aika |
500 | Palvelinvirhe (tietokanta-, tallennus- tai sähköpostivirhe) |
Rate-limit
Rajat lasketaan API-avainkohtaisesti: 10 pyyntöä minuutissa ja 100 pyyntöä vuorokaudessa. Vastauksissa on X-RateLimit-Limit-, X-RateLimit-Remaining- ja X-RateLimit-Reset-otsakkeet minuutti-ikkunalle. Kun raja ylittyy, API palauttaa 429-vastauksen ja Retry-After-otsakkeen, joka kertoo odotusajan sekunteina. Ota yhteyttä, jos tarvitset korkeampia rajoja.
Idempotenssi
`POST /v1/signatures` hyväksyy valinnaisen `Idempotency-Key`-otsikon (mikä tahansa yksilöllinen merkkijono, tyypillisesti UUID). Kun toistat pyynnön samalla avaimella, Signeur palauttaa alkuperäisen vastauksen luomatta kopiota. Avaimet ovat API-avaimen omistajakohtaisia ja säilyvät 24 tuntia.
POST https://api.signeur.eu/v1/signatures
Authorization: Bearer sgn_live_...
Idempotency-Key: 0d8a2c41-7e3f-4b9d-bc59-2c5fd8a91f4d
Content-Type: application/json
{ … }Jos lähetät saman avaimen eri pyyntörungolla, Signeur palauttaa 409 idempotency_key_conflict; jos alkuperäinen pyyntö on vielä käsittelyssä, rinnakkainen uusinta saa 409 idempotency_key_in_progress ja Retry-After-otsikon. Toistetut vastaukset sisältävät `Idempotent-Replayed: true` -otsikon, josta ne voi tunnistaa.
Päätepisteet
Lataa PDF allekirjoituspyyntöä varten
Lataa PDF:n etukäteen ja palauttaa upload-id:n, joka annetaan POST /v1/signatures -pyynnön kentässä document.upload_id. Kaksi tilaa Content-Typen mukaan: lähetä PDF:n tavut suoraan (application/pdf, koko pyyntö enintään 4,5 MB) tai lähetä JSON-runko (application/json), jolloin saat valmiiksi allekirjoitetun upload-URL:n ja PUT:aat tiedoston sinne itse (enintään 10 MB, ei muita otsakkeita kuin Content-Type). Käyttämätön lataus poistetaan 24 tunnin kuluttua, ja yhtä latausta voi käyttää vain yhteen pyyntöön.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
size_bytes | number | ei | Valinnainen (tila B). Tiedoston odotettu koko tavuina; pyyntö hylätään heti, jos koko ylittää 10 MB. |
PDF-vaatimukset: tiedosto tarkistetaan vastaanotettaessa. Salatut tai salasanasuojatut PDF:t (pdf_encrypted), lukukelvottomat tiedostot (pdf_unreadable) ja PDF:t, joissa on jo digitaalinen allekirjoitus (pdf_already_signed), hylätään 400-vastauksella ennen veloitusta. Lomakekentät litistetään, jolloin kenttien arvot muuttuvat kiinteäksi sisällöksi; jos litistys epäonnistuu, pyyntö hylätään (pdf_form_flatten_failed). Näkymästä riippuva tai aktiivinen sisältö — valinnaiset sisältökerrokset, piilotetut tai vain tulostuvat merkinnät, JavaScript ja upotetut tiedostot — hylätään (pdf_unsupported_content), jotta allekirjoittaja näkee saman kuin sinetöity asiakirja näyttää.
Tila A — PDF:n tavut pyynnön rungossa (enintään 4,5 MB):
curl -X POST https://api.signeur.eu/v1/documents \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/pdf" \
--data-binary @contract.pdfVastaus
{
"id": "3f0e1c2a-8b1d-4f7e-9c21-5a6b7c8d9e0f",
"size_bytes": 1834021,
"expires_at": "2026-09-20T08:00:00.000Z"
}Tila B — valmiiksi allekirjoitettu upload-URL (tiedostot 10 MB asti):
curl -X POST https://api.signeur.eu/v1/documents \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{ "size_bytes": 8123456 }'Vastaus
{
"id": "3f0e1c2a-8b1d-4f7e-9c21-5a6b7c8d9e0f",
"upload_url": "https://…/storage/v1/object/upload/sign/…?token=…",
"upload_method": "PUT",
"upload_headers": { "Content-Type": "application/pdf" },
"upload_url_expires_at": "2026-09-19T10:00:00.000Z",
"expires_at": "2026-09-20T08:00:00.000Z",
"max_size_bytes": 10485760
}PUT:aa sitten tiedosto upload_url-osoitteeseen (voimassa 2 tuntia):
curl -X PUT "<upload_url>" \
-H "Content-Type: application/pdf" \
--data-binary @contract.pdfLuo lopuksi pyyntö kentällä document.upload_id:
curl -X POST https://api.signeur.eu/v1/signatures \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{
"title": "Order Agreement #1234",
"signers": [{ "email": "buyer@example.com", "name": "Anna Buyer" }],
"document": {
"filename": "contract.pdf",
"upload_id": "3f0e1c2a-8b1d-4f7e-9c21-5a6b7c8d9e0f"
}
}'Luo allekirjoituspyyntö
Luo uusi allekirjoituspyyntö (1–20 allekirjoittajaa), tallentaa PDF:n Storageen ja lähettää kutsu-emailit kaikille allekirjoittajille.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
title | string | kyllä | Allekirjoituspyynnön otsikko (näkyy kutsu-emailissa). |
message | string | ei | Valinnainen viesti, joka näytetään jokaiselle allekirjoittajalle. |
signers[] | array | kyllä | Lista 1–20 signer-objektista. Vähintään yksi vaaditaan. |
signers[].email | string | kyllä | Allekirjoittajan sähköpostiosoite. |
signers[].name | string | ei | Allekirjoittajan nimi (näkyy audit-sivulla). |
signers[].locale | string | ei | Per-signer email-kieli: 'en' | 'fi' | 'fr' | 'de'. Fallback ensin top-level locale:en, sitten 'en'. |
locale | string | ei | Default-locale niille signereille jotka eivät määritä omaa. Sallitut arvot: 'en' | 'fi' | 'fr' | 'de'. Puuttuessa käytetään organisaation asetuksissa määritettyä kutsujen oletuskieltä; jos sitäkään ei ole, 'en'. |
reply_to | string | ei | Valinnainen. Kutsuviestien Reply-To-osoite: allekirjoittajan vastaus ohjautuu tähän osoitteeseen. Puuttuessa käytetään organisaation asetuksissa määritettyä osoitetta; jos sitäkään ei ole, Reply-To-headeria ei lisätä. |
document.filename | string | ei | Valinnainen. PDF:n alkuperäinen tiedostonimi. |
document.content_base64 | string | ei | PDF:n sisältö base64-koodattuna merkkijonona (enintään 10 MB purettuna). Koko HTTP-pyyntö on rajattu 4,5 MB:iin, joten base64 toimii noin 3 MB:n PDF:iin asti — lataa isommat tiedostot ensin POST /v1/documents -endpointilla ja anna document.upload_id. |
document.upload_id | string | ei | POST /v1/documents -vastauksen id. Käytä content_base64:n sijaan yli noin 3 MB:n PDF:ille. Anna joko upload_id tai content_base64, ei molempia. |
metadata | object | ei | Vapaamuotoinen avain-arvopari-tietue, joka tallennetaan sellaisenaan. |
Yhteensopivuus: vanhempi single-signer-body { "signer_email", "signer_name" } toimii edelleen ja muunnetaan sisäisesti yhden alkion signers-arrayksi. Uudet integraatiot kannattaa kuitenkin tehdä signers[]-formaatilla.
PDF-vaatimukset: tiedosto tarkistetaan vastaanotettaessa. Salatut tai salasanasuojatut PDF:t (pdf_encrypted), lukukelvottomat tiedostot (pdf_unreadable) ja PDF:t, joissa on jo digitaalinen allekirjoitus (pdf_already_signed), hylätään 400-vastauksella ennen veloitusta. Lomakekentät litistetään, jolloin kenttien arvot muuttuvat kiinteäksi sisällöksi; jos litistys epäonnistuu, pyyntö hylätään (pdf_form_flatten_failed). Näkymästä riippuva tai aktiivinen sisältö — valinnaiset sisältökerrokset, piilotetut tai vain tulostuvat merkinnät, JavaScript ja upotetut tiedostot — hylätään (pdf_unsupported_content), jotta allekirjoittaja näkee saman kuin sinetöity asiakirja näyttää.
Pyynnön body
curl -X POST https://api.signeur.eu/v1/signatures \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{
"title": "Order Agreement #1234",
"message": "Please review and sign.",
"locale": "en",
"reply_to": "sales@example.com",
"signers": [
{ "email": "buyer@example.com", "name": "Anna Buyer" },
{ "email": "seller@example.com", "name": "Bob Seller", "locale": "fi" }
],
"document": {
"filename": "contract.pdf",
"content_base64": "JVBERi0xLjQK..."
},
"metadata": { "deal_id": "D-42" }
}'Vastaus
{
"id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"status": "sent",
"expires_at": "2026-06-13T10:51:51.813+00:00",
"signers": [
{
"id": "9c0aa5ec-…",
"email": "buyer@example.com",
"name": "Anna Buyer",
"access_token": "29ErQSUr8Ov…",
"sign_url": "https://signeur.eu/sign/29ErQSUr8Ov…",
"email_sent": true,
"email_error": null,
"locale": "en"
},
{
"id": "f12d8b3c-…",
"email": "seller@example.com",
"name": "Bob Seller",
"access_token": "kpqDAuVy9-…",
"sign_url": "https://signeur.eu/sign/kpqDAuVy9-…",
"email_sent": true,
"email_error": null,
"locale": "fi"
}
]
}Hae allekirjoituspyynnön tila
Palauttaa pyynnön nykyisen tilan, koko signers-arrayn ja audit-trailin. Käytetään statuksen seurantaan.
Pyynnön body
curl https://api.signeur.eu/v1/signatures/<id> \
-H "Authorization: Bearer sgn_live_..."Vastaus
{
"id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"status": "signed",
"title": "Order Agreement #1234",
"created_at": "2026-05-14T10:51:51.813Z",
"sent_at": "2026-05-14T10:51:52.012Z",
"signed_at": "2026-05-14T10:52:24.374Z",
"cancelled_at": null,
"expires_at": "2026-06-13T10:51:51.813Z",
"is_expired": false,
"signers": [
{
"id": "9c0aa5ec-…",
"email": "buyer@example.com",
"name": "Anna Buyer",
"access_token": "29ErQSUr8Ov…",
"sign_url": "https://signeur.eu/sign/29ErQSUr8Ov…",
"status": "signed",
"sent_at": "2026-05-14T10:51:52.012Z",
"opened_at": "2026-05-14T10:52:00.481Z",
"signed_at": "2026-05-14T10:52:24.374Z",
"declined_at": null,
"decline_reason": null,
"locale": "en"
}
],
"document_hash": "e5132c2fe36dfa219ec600b009d16ef38d20bf0849f7b01ba5ca6e22fec63b56",
"audit_trail": { "events": [ … ] },
"metadata": { "deal_id": "D-42" }
}Lataa allekirjoitettu PDF
Palauttaa lukitun PDF:n binaryna. Palauttaa 409, jos pyyntöä ei ole vielä allekirjoitettu.
Pyynnön body
curl https://api.signeur.eu/v1/signatures/<id>/document \
-H "Authorization: Bearer sgn_live_..." \
-o signed.pdfContent-Type: application/pdf
Listaa allekirjoituspyynnöt
Palauttaa organisaation pyyntöjen paginoidun listan suodattimilla.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
status | query | ei | Suodata statuksella: pending | sent | opened | signed | cancelled | declined | expired | awaiting_stamp | stamp_failed. |
created_from | query | ei | Palauta vain pyynnöt, joiden created_at on tämä ISO-8601 aikaleima tai sen jälkeen. |
created_to | query | ei | Palauta vain pyynnöt, joiden created_at on ennen tätä ISO-8601 aikaleimaa. |
limit | query | ei | Sivun koko, 1–100. Oletus 25. |
cursor | query | ei | Opaakki cursor, joka saatiin edellisen vastauksen next_cursor-arvosta. Älä rakenna itse. |
Pyynnön body
curl "https://api.signeur.eu/v1/signatures?status=sent&limit=10" \
-H "Authorization: Bearer sgn_live_..."Vastaus
{
"data": [
{
"id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"status": "sent",
"title": "Order Agreement #1234",
"signer_count": 2,
"created_at": "2026-05-14T10:51:51.813Z",
"sent_at": "2026-05-14T10:51:52.012Z",
"signed_at": null,
"cancelled_at": null,
"expires_at": "2026-06-13T10:51:51.813Z",
"is_expired": false
}
],
"has_more": true,
"next_cursor": "eyJjIjoiMjAyNi0wNS0xNFQxMDo1MTo1MS44MTNaIiwiaSI6IjZkYzE4OTExLi4uIn0"
}Peruuta allekirjoituspyyntö
Peruuttaa avoimen pyynnön, invalidoi kaikki vielä aktiiviset signer-linkit ja lähettää signature_request.cancelled-webhookin.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
reason | string | ei | Valinnainen peruste, tallennetaan audit-trailiin (max 500 merkkiä). |
Pyynnön body
curl -X POST https://api.signeur.eu/v1/signatures/<id>/cancel \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{ "reason": "Sent to wrong recipient" }'Vastaus
{
"id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"status": "cancelled",
"cancelled_at": "2026-05-17T08:14:02.913Z"
}Vaikutus: status muuttuu 'cancelled'-tilaan, kaikki allekirjoittamattomat signer-linkit invalidoidaan ja signature_request.cancelled-webhook lähetetään. Alkuperäinen PDF säilyy DB:ssä, mutta sitä ei voi enää ladata /document-reitin kautta.
Listaa pyynnön allekirjoittajat
Palauttaa kaikki signer-rivit yhden pyynnön sisällä per-signer-tiloineen, aikaleimineen ja audit-traileineen. Käytetään multi-signer-edistymisen näyttöön.
Pyynnön body
curl "https://api.signeur.eu/v1/signatures/<id>/signers" \
-H "Authorization: Bearer sgn_live_..."Vastaus
{
"data": [
{
"id": "9c0aa5ec-…",
"email": "buyer@example.com",
"name": "Anna Buyer",
"name_as_invited": "Anna Buyer",
"name_as_signed": "Anna H. Buyer",
"access_token": "29ErQSUr8Ov…",
"sign_url": "https://signeur.eu/sign/29ErQSUr8Ov…",
"status": "signed",
"position": 0,
"sent_at": "2026-05-14T10:51:52.012Z",
"opened_at": "2026-05-14T10:52:00.481Z",
"signed_at": "2026-05-14T10:52:24.374Z",
"declined_at": null,
"decline_reason": null,
"invalidated_at": null,
"ip_address": "87.92.91.57",
"user_agent": "Mozilla/5.0 (Macintosh; …) Safari/605.1.15",
"ip_country": "FI",
"ip_city": "Helsinki",
"locale": "en",
"representing_as_invited": null,
"representing_as_signed": null,
"representing_role": null,
"representing_entity_id": null,
"audit_trail": { "events": [ … ] }
},
{
"id": "f12d8b3c-…",
"email": "seller@example.com",
"status": "pending",
"position": 1,
"...": "..."
}
]
}Lähetä kutsu uudelleen
Lähettää kutsu-emailin yhdelle signerille uudestaan tuoreella access-koodilla. Vanha koodi lakkaa toimimasta heti.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
locale | string | ei | Valinnainen. Korvaa signerin email-localen tällä lähetyksellä ja tallenna muutos signer-riville. Sallitut: 'en' | 'fi' | 'fr' | 'de'. |
Pyynnön body
curl -X POST https://api.signeur.eu/v1/signatures/<id>/signers/<signer_id>/resend \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{ "locale": "fi" }'Vastaus
{
"ok": true,
"signer_id": "9c0aa5ec-…",
"email_sent": true,
"email_error": null,
"access_code_rotated_at": "2026-05-17T10:14:33.872Z"
}Vaikutus: uusi 6-numeroinen access-koodi generoidaan, tallennetaan bcrypt-hashattuna ja lähetetään signerille emailissa. Aiemmin lähetetty koodi ei enää tunnista access-code-portilla. Yritys-laskuri ja mahdolliset väliaikaiset lukot resetoidaan.
Lataa audit-trail-PDF
Palauttaa erillisen PDF:n joka sisältää koko auditkirjauksen: pyynnön metatiedot, signereiden tiedot IP-osoitteineen ja user-agent-tietoineen, kronologisen event-aikajanan sekä PAdES-allekirjoituksen tiedot kun pyyntö on sinetöity. Tämä PDF on informatiivinen eikä ole kryptografisesti allekirjoitettu — sinetöity itse asiakirja on juridinen todiste.
Pyynnön body
curl https://api.signeur.eu/v1/signatures/<id>/audit-trail.pdf \
-H "Authorization: Bearer sgn_live_..." \
-o audit-trail.pdfContent-Type: application/pdf · PDF generoidaan pyynnön nykyisestä tilasta ja audit-trailista. Saatavilla riippumatta pyynnön statuksesta.
Listaa webhook-endpointit
Palauttaa organisaation kaikki webhook-endpointit. Secret-arvot eivät tule listauksessa — ne näytetään vain luonnin yhteydessä yhden kerran.
Pyynnön body
curl https://api.signeur.eu/v1/webhook-endpoints \
-H "Authorization: Bearer sgn_live_..."Vastaus
{
"data": [
{
"id": "ep_a1b2c3d4-…",
"url": "https://example.com/hooks/signeur",
"event_types": ["signature_request.completed", "signer.signed"],
"description": "Production sync",
"disabled_at": null,
"created_at": "2026-05-17T10:00:00.000Z",
"updated_at": "2026-05-17T10:00:00.000Z"
}
]
}Luo webhook-endpoint
Rekisteröi uuden URL:n vastaanottamaan webhook-eventejä. Vastaus sisältää tuoreen `secret`-arvon joka näytetään vain tämän kerran ja jota käytetään HMAC-allekirjoitusten verifiointiin saapuvissa webhookeissa.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
url | string | kyllä | Toimituskohteen URL (pakko olla https:// tuotannossa, http://localhost on sallittu kehityksessä). |
event_types | string[] | ei | Lista event-tyypeistä joita vastaanotetaan. Tyhjä lista (tai pois jätetty) = vastaanotetaan kaikki eventit. |
description | string | ei | Valinnainen lyhyt seliteteksti endpointille (max 200 merkkiä). |
Pyynnön body
curl -X POST https://api.signeur.eu/v1/webhook-endpoints \
-H "Authorization: Bearer sgn_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/signeur",
"event_types": ["signature_request.completed", "signer.signed"],
"description": "Production sync"
}'Vastaus
{
"id": "ep_a1b2c3d4-…",
"url": "https://example.com/hooks/signeur",
"secret": "whsec_7f3a9c…",
"event_types": ["signature_request.completed", "signer.signed"],
"description": "Production sync",
"disabled_at": null,
"created_at": "2026-05-17T10:00:00.000Z",
"updated_at": "2026-05-17T10:00:00.000Z"
}Tärkeää: secret näkyy VAIN tässä vastauksessa. Signeur ei säilytä plain-text-versiota. Jos hukkaat sen, poista tämä endpoint ja luo uusi.
Päivitä webhook-endpoint
Päivittää endpointin url, event_types, description tai disabled-tila. Kaikki body-kentät ovat valinnaisia — vain annetut muuttuvat.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
url | string | ei | Toimituskohteen URL (pakko olla https:// tuotannossa, http://localhost on sallittu kehityksessä). |
event_types | string[] | ei | Lista event-tyypeistä joita vastaanotetaan. Tyhjä lista (tai pois jätetty) = vastaanotetaan kaikki eventit. |
description | string | ei | Valinnainen lyhyt seliteteksti endpointille (max 200 merkkiä). |
disabled | boolean | ei | true = pysäytä toimitus poistamatta endpointia, false = jatka. |
Poista webhook-endpoint
Poistaa endpointin pysyvästi. Eventien toimitus loppuu välittömästi. Secret on palautumaton poiston jälkeen.
curl -X DELETE https://api.signeur.eu/v1/webhook-endpoints/<id> \
-H "Authorization: Bearer sgn_live_..."Webhookit
Signeur lähettää tapahtumaviestit (events) reaaliaikaisesti yhteen tai useampaan organisaatiolle määritettyyn URL-osoitteeseen, kun allekirjoituspyynnön tila muuttuu. Jokainen event allekirjoitetaan HMAC-SHA256:lla ja toimitetaan rinnakkain kaikkiin sopiviin endpointteihin. Tämä on tehokkaampi vaihtoehto kuin GET-endpointin pollaaminen.
Tuetut tapahtumat
signature_request.created | Uusi allekirjoituspyyntö luotu. Fires kerran per pyyntö, sisältää koko signers-listan. |
signature_request.sent | Kutsu-email-batch yritetty kaikille signereille. Sisältää per-signer email_sent-statuksen. |
signature_request.opened | Allekirjoittaja avasi linkin ensimmäistä kertaa. Fires kerran per pyyntö kun ensimmäinen signer avaa sen. |
signer.signed | Yksittäinen signer suoritti OTP-vahvistuksen ja allekirjoitti. Fires N kertaa N-signerin pyynnössä. |
signature_request.completed | Kaikki signereistä ovat allekirjoittaneet ja dokumentti on sinetöity. Sisältää document_hashin ja download_url:n. |
signature_request.signed | Deprecated — sama hetki kuin signature_request.completed. Uusissa integraatioissa käytä signature_request.completed. |
signature_request.declined | Joku signereistä kieltäytyi; pyyntö siirtyi 'declined'-tilaan ja jäljellä olevat signerit invalidoitiin. |
signature_request.cancelled | Pyyntö peruttiin dashboardin tai POST /signatures/{id}/cancel-endpointin kautta. |
signature_request.expired | Pyyntö saavutti expires_at-ajan ilman että kaikki allekirjoittajat ehtivät. Lähetetään kerran per pyyntö kun expire-cron siirtää statuksen 'expired'-tilaan (max ~24 h viive Vercel Hobby -tilauksella). |
Payload-muoto
// signer.signed — fires once per signer that finishes signing
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "signer.signed",
"created_at": "2026-05-14T10:52:24.374Z",
"data": {
"signature_request_id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"signer_id": "9c0aa5ec-…",
"signer_email": "buyer@example.com",
"signer_name": "Anna Buyer",
"signed_at": "2026-05-14T10:52:24.374Z",
"remaining_pending_signers": 1
}
}
// signature_request.completed — fires once when all signers are done
// and the PDF is sealed. signature_request.signed is a deprecated alias
// that fires at the same moment with the same payload.
{
"id": "evt_b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "signature_request.completed",
"created_at": "2026-05-14T10:55:11.812Z",
"data": {
"signature_request_id": "6dc18911-f66b-43d6-9810-8de0b07bab04",
"status": "signed",
"signed_at": "2026-05-14T10:55:11.812Z",
"document_hash": "e5132c2fe36dfa…",
"download_url": "https://api.signeur.eu/v1/signatures/6dc18911-…/document"
}
}Allekirjoituksen verifiointi
Jokaiseen webhookiin liitetään HMAC-SHA256-allekirjoitus headerissa X-Signeur-Signature. Verifioi se varmistaaksesi että pyyntö tuli aidosti Signeurilta. Hylkää toimitus, jos sen aikaleima on yli 5 minuuttia vanha, ja vertaa tiivisteitä vakioaikaisesti (esim. timingSafeEqual) — näin torjut uudelleenlähetys- ja ajoitushyökkäykset.
Header-muoto:
X-Signeur-Signature: t=1747212744,v1=abc123def456...Allekirjoitettu data:
<timestamp>.<raw json body>Esimerkki verifioinnista (Node.js):
import { createHmac, timingSafeEqual } from "crypto";
// 1. Parse the header: t=<unix seconds>,v1=<hex digest>
const sig = req.headers["x-signeur-signature"];
const [t, v1] = sig.split(",").map(s => s.split("=")[1]);
// 2. Reject stale deliveries (replay protection, 5 min tolerance)
const ageSeconds = Math.abs(Date.now() / 1000 - Number(t));
if (!Number.isFinite(ageSeconds) || ageSeconds > 300) throw new Error("Stale webhook");
// 3. Recompute the digest over `${t}.${rawBody}` (raw bytes, not re-serialised JSON)
const expected = createHmac("sha256", YOUR_WEBHOOK_SECRET)
.update(`${t}.${rawBody}`).digest("hex");
// 4. Constant-time comparison (never `v1 !== expected`)
const a = Buffer.from(v1 ?? "", "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) throw new Error("Invalid signature");Konfigurointi
Endpointteja voi konfiguroida kahdella tavalla: (a) Dashboard → Webhookit tarjoaa UI:n endpointtien lisäämiseen, muokkaamiseen, pausettamiseen ja poistamiseen sekä event-tyyppien valintaan per endpoint. (b) REST API /v1/webhook-endpoints sallii ohjelmallisen hallinnan. Jokainen endpoint saa oman HMAC-secretin joka näytetään vain luonnin yhteydessä — tallenna se turvallisesti. Legacy yhden URL:n webhook organisaation tasolla toimii edelleen fallbackina, jos uudessa taulussa ei ole rivejä.
Toimitus
Kun event ampuu, Signeur etsii kaikki aktiiviset endpointit jotka tilaavat event-tyyppiä ja toimittaa payloadin rinnakkain (5 sekunnin timeout per endpoint). Jokainen yritys tallennetaan erikseen signature_requestin audit-trailiin endpoint-id:n, HTTP-statuksen ja mahdollisen virheen kanssa. Retry-queue on roadmapilla.
MCP-palvelin
Signeur tarjoaa saman rajapinnan tekoälyagenteille MCP-palvelimena (Model Context Protocol, Streamable HTTP, tilaton). Jokainen työkalukutsu kulkee yllä kuvatun REST APIn läpi, joten tunnistus, rajat, idempotenssi, laskutus ja audit-loki toimivat täsmälleen kuten suorissa HTTP-kutsuissa. Sopii Claude Desktopiin, Claude Codeen, Cursoriin ja muihin MCP-asiakkaisiin, jotka voivat lähettää Authorization-otsakkeen.
Yhdistäminen
Osoite: https://api.signeur.eu/mcp. Tunnistaudu dashboardista luodulla API-avaimella Authorization-otsakkeessa; OAuth-kirjautumista ei ole. Esimerkki asiakasohjelman asetuksesta:
{
"mcpServers": {
"signeur": {
"url": "https://api.signeur.eu/mcp",
"headers": { "Authorization": "Bearer sgn_live_YOUR_KEY" }
}
}
}Avaimen omistaja (henkilökohtainen tai organisaation konteksti) ratkaisee, mitkä pyynnöt näkyvät ja kenen tilausta laskutetaan. Avaimen peruutus dashboardissa katkaisee myös MCP-yhteydet heti. Pelkkää OAuth-kirjautumista tukevat asiakkaat (esimerkiksi hostatut liittimet) eivät vielä pysty yhdistämään.
Työkalut
Seuranta (maksuton)
list_signature_requests | Listaa allekirjoituspyynnöt tila- ja aikasuodattimilla sekä sivutuksella. |
get_signature_request | Yhden pyynnön tila, allekirjoittajat, aikaleimat, dokumentin tiiviste ja PDF:n säilytysaika. |
list_signers | Pyynnön kaikki allekirjoittajat ja heidän tilansa. |
get_document_links | API-linkit allekirjoitetun pyynnön sinetöityyn PDF:ään ja audit-trail-PDF:ään (haetaan samalla avaimella). |
Lähettäminen
create_upload_url | Esiallekirjoitettu upload-osoite yli noin 3 MB:n PDF:lle; pienemmät voi antaa suoraan base64-muodossa. |
prepare_signature_request | Tarkistaa allekirjoittajat ja PDF:n ja palauttaa kokonaishinnan luomatta mitään. |
create_signature_request | Luo pyynnön ja lähettää kutsut. Maksullinen; vaatii confirm=true sen jälkeen, kun käyttäjä on hyväksynyt esikatselun. |
cancel_signature_request | Peruu vireillä olevan pyynnön. |
resend_invitation | Lähettää kutsun uudelleen yhdelle allekirjoittajalle. |
Webhookit
list_webhook_endpoints | Määritetyt päätepisteet ilman salaisuuksia. |
create_webhook_endpoint | Rekisteröi webhook-osoitteen; HMAC-salaisuus palautetaan kerran. |
rotate_webhook_secret | Vaihtaa päätepisteen HMAC-salaisuuden. |
Laskutus ja rajat
Vain create_signature_request maksaa: 0,89 € sis. alv per allekirjoittaja, veloitetaan avaimen omistajan aktiivisesta API-tilauksesta (ilman tilausta vastaus on 402). Työkalu on tarkoituksella kaksivaiheinen: prepare_signature_request palauttaa yhteenvedon ja hinnan ilman sivuvaikutuksia, ja create_signature_request etenee vain arvolla confirm=true. Jokainen luonti saa automaattisen Idempotency-Keyn, joten samojen tietojen uusintakutsu ei luo tuplapyyntöä. APIn rajat, 10 kutsua minuutissa ja 100 päivässä per avain, koskevat myös työkalukutsuja.
Resurssit ja kehotteet
Palvelin tarjoaa resursseina myös llms.txt:n, OpenAPI-kuvauksen ja auth.md:n sekä kaksi kehotetta: ohjatun lähetyksen ja webhook-allekirjoituksen varmennuksen.
Koneluettava palvelinkortti on osoitteessa /.well-known/mcp/server-card.json.
Tulossa pian
Seuraavat ominaisuudet ovat suunnitteilla:
- → Automaattinen vanhentumistarkkailu joka ampuu signature_request.expired-eventin (nyt status pysyy 'sent'/'opened' vaikka expires_at olisi mennyt)
- → Webhook retry-queue — nyt jokainen toimitus on yksi yritys; epäonnistuneet eventit eivät yritä uudelleen
- → Idempotency-Key-tuki cancel- ja resend-endpointeille (nyt vain POST /signatures)
- → Webhook delivery -historianäkymä dashboardiin