Rakenna sähköisen allekirjoituksen integraatio
Bink API tarjoaa kehittäjille tehokkaat työkalut dokumenttien hallintaan ja sähköiseen allekirjoitukseen – suoraan omasta sovelluksestasi.
Miksi Bink API?
Yksi rajapinta – kaikki mitä tarvitset sähköiseen allekirjoitukseen ja dokumenttien hallintaan.
Dokumenttien hallinta
Luo, hae, listaa ja poista dokumentteja ohjelmallisesti. Tuki useille tiedostomuodoille ja kansiorakenteelle.
Sähköinen allekirjoitus
Lähetä dokumentit allekirjoitettavaksi yhdellä API-kutsulla. Tukee sekä sähköposti- että vahvaa tunnistautumista.
Webhook-ilmoitukset
Vastaanota reaaliaikaiset tilamuutosilmoitukset dokumenteille. Ei tarvetta pollingille – Bink lähettää HTTP POST -kutsun automaattisesti.
Turvallinen ja luotettava
API-avainpohjainen tunnistautuminen, HMAC-SHA256-allekirjoitetut webhookit ja EU-alueen mukainen tietosuoja.
Nopea integraatio
RESTful JSON API, selkeä dokumentaatio ja yksinkertaiset endpointit – integraatio valmiina minuuteissa.
Monen tiimin tuki
Tenant-pohjainen arkkitehtuuri mahdollistaa useiden organisaatioiden ja tiimien hallinnan yhdellä API-avaimella.
Sandbox-ympäristö
Testaa integraatiota riskittömästi sandbox-ympäristössä ennen tuotantoon siirtymistä. Telia- ja maksupalvelutarjoajamme-demot käytettävissä.
Näin pääset alkuun
Viisi yksinkertaista vaihetta Bink API:n käyttöönottoon.
Luo tili
Rekisteröidy osoitteessa app.bink.fi ja vahvista sähköpostiosoitteesi. Tilin luominen on ilmaista.
Luo API-avain
Siirry asetuksiin kohdasta Settings → API ja klikkaa Create API Key. Kopioi avain talteen – sitä ei voi nähdä enää myöhemmin.
Tutustu Swagger-dokumentaatioon
Interaktiivinen API-dokumentaatio on vapaasti saatavilla osoitteessa sandbox-api.bink.fi/docs – ei vaadi kirjautumista.
Testaa sandbox-ympäristössä
Kokeile API-kutsuja sandbox-ympäristössä osoitteessa sandbox.bink.fi. Käytössä on Telia- ja maksupalvelutarjoajamme demoversiot, joilla voit testata kaikki ominaisuudet riskittömästi.
Siirry tuotantoon
Kun integraatio on testattu sandboxissa, vaihda API-osoitteeksi api.bink.fi ja aloita tuotantokäyttö. Tuotannon API-osoite: https://api.bink.fi
Esimerkkipyyntö
Luo dokumentti ja liitä allekirjoittajat yhdellä kutsulla.
# Sandbox-ympäristö (testaus) curl -X POST https://sandbox-api.bink.fi/api/documents/quick-create \ -H "x-api-key: YOUR_API_KEY" \ -F "file=@sopimus.pdf" \ -F "title=Yhteistyösopimus" \ -F "tenantId=your-tenant-id" \ -F "signingMethod=email" \ -F "signingMessage=Tarkista ja allekirjoita perjantaihin mennessä." \ -F "signingOrderEnabled=true" \ -F 'signees=[ {"email":"matti@esimerkki.fi","name":"Matti Meikäläinen"}, {"email":"maija@esimerkki.fi","name":"Maija Meikäläinen","pic":"010101-123X"} ]' # Tuotanto: vaihda URL → https://api.bink.fi/api/documents/quick-create
{ "message": "Document created successfully", "document": { "id": "cfc80de9-1e3f-4c72-b490-73381c1702da", "name": "Yhteistyösopimus", "status": "draft", "downloadUrl": "https://...", "emailLanguage": "fi" }, "signees": [ { "id": "…", "email": "matti@esimerkki.fi", "name": "Matti Meikäläinen", "status": "pending" }, { "id": "…", "email": "maija@esimerkki.fi", "name": "Maija Meikäläinen", "status": "pending" } ], "contentType": "application/pdf" }
API-referenssi
Kaikki käytettävissä olevat endpointit yhdellä silmäyksellä. Täydellinen interaktiivinen dokumentaatio: sandbox-api.bink.fi/docs ↗
Luo dokumentin lataamalla tiedoston multipart-muodossa ja liittää allekirjoittajat yhdellä kutsulla.
Request body · multipart/form-data
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| file* | binary | Ladattava tiedosto |
| title | string | Valinnainen. Jos puuttuu tai on tyhjä, käytetään ladatun tiedoston nimeä. |
| tenantId* | string | Organisaation tunniste |
| folderId | string | Valinnainen. Jos vastaa olemassa olevaa kansiota samassa tenantissa, dokumentti luodaan sinne. Muutoin dokumentti luodaan ilman kansiota. |
| signingMethod | string | Valinnainen. Allekirjoitustapa: "email" (sähköpostivarmenne, oletusarvo) tai "strong" (vahva tunnistautuminen). |
| signingMessage | string | Valinnainen. Henkilökohtainen viesti allekirjoitussähköpostissa. Esim. "Tarkista ja allekirjoita perjantaihin mennessä." |
| emailLanguage | string | Valinnainen. Allekirjoitussähköpostien kieli tälle dokumentille. Oletuksena tenantin sähköpostikieli. |
| signingOrderEnabled | boolean | Valinnainen. Kun true, allekirjoittajat allekirjoittavat järjestyksessä (sequential signing). |
| signees* | JSON string | JSON-taulukko allekirjoittajista: [{"email":"…","name":"…"}]. Vahvaa tunnistautumista varten voidaan lisätä pic-kenttä (henkilötunnus): {"email":"…","name":"…","pic":"010101-123X"}. Jos signingOrderEnabled on true, allekirjoitusjärjestys noudattaa taulukon järjestystä (ensimmäinen allekirjoittaa ensin). |
Vastaukset
{ "message": "string", "document": { "downloadUrl": "string", "emailLanguage": "fi" }, "signees": [ { "id": "string", "documentId": "string", "email": "string", "name": "string", "status": "pending" } ], "contentType": "string" }
errorCode-kentän{ "error": "string", "errorCode": "string" }
{ "error": "string" }
Palauttaa kirjautuneen käyttäjän dokumentit valitussa tenantissa.
Query-parametrit
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| tenantId* | string | Organisaation tunniste |
| folderId | string | null | Valinnainen. Kansion tunniste. |
Vastaukset
[ { "id": "string", "tenantId": "string", "folderId": "string", "name": "string", "status": "signed", "pinned": true, "emailLanguage": "fi", "createdAt": "2026-08-17T08:36:13.009Z", "updatedAt": "2026-08-17T08:36:13.009Z" } ]
{ "error": "string" }
Palauttaa yksittäisen dokumentin tiedot tunnisteen perusteella. Vastaus sisältää myös allekirjoittajat ja heidän allekirjoituslinkkinsä.
Polkuparametrit
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| documentId* | string | Dokumentin tunniste |
Vastaukset
{ "id": "string", "tenantId": "string", "folderId": "string", "name": "string", "status": "signed", "pinned": true, "emailLanguage": "fi", "downloadUrl": "string", "signees": [ { "id": "string", "documentId": "string", "email": "string", "name": "string", "status": "pending", "signingUrl": "string" } ], "createdAt": "2026-08-17T08:36:13.023Z", "updatedAt": "2026-08-17T08:36:13.023Z" }
{ "error": "string" }
Poistaa pysyvästi luonnos-, käsittelyssä olevan tai allekirjoitetun dokumentin sekä sen tallennetun PDF-tiedoston.
Polkuparametrit
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| documentId* | string | Dokumentin tunniste |
Vastaukset
{ "message": "string" }
{ "error": "string" }
curl -X DELETE https://sandbox-api.bink.fi/api/documents/DOCUMENT_ID \ -H "x-api-key: YOUR_API_KEY"
Lähettää allekirjoituskutsut kaikille dokumentin allekirjoittajille.
Polkuparametrit
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| documentId* | string | Dokumentin tunniste |
Endpoint ei ota vastaan request bodya. Sähköpostien kieli määräytyy dokumentin emailLanguage-arvon mukaan, joka asetetaan dokumenttia luotaessa tai peritään tenantin asetuksista.
Vastaukset
{ "message": "string", "result": [ { "email": "string", "status": "string", "data": {}, "error": {}, "signeeId": "string", "signingUrl": "string" } ], "credit": { "tenantId": "string", "email": 0, "strong": 0 } }
{ "error": "string" }
{ "error": "string", "reminderCooldownUntil": "2026-08-17T08:36:13.072Z" }
Palauttaa kirjautuneen käyttäjän organisaatiot (tenantit). Ei parametreja. Vastaus sisältää myös organisaation sähköposti-ilmoitusten asetukset.
Vastaukset
[ { "id": "string", "name": "string", "logo": "string", "emailLanguage": "fi", "signingRequestEmailEnabled": true, "signingReminderEmailEnabled": true, "creatorCompletionEmailEnabled": true, "participantSignedEmailEnabled": true, "participantCompletionEmailEnabled": true, "createdAt": "2026-08-17T08:36:13.081Z", "updatedAt": "2026-08-17T08:36:13.081Z" } ]
Sähköposti-ilmoitusten asetukset
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| signingRequestEmailEnabled | boolean | Lähetetäänkö allekirjoituspyyntö sähköpostitse allekirjoittajille |
| signingReminderEmailEnabled | boolean | Lähetetäänkö muistutusviestit allekirjoittamattomille |
| creatorCompletionEmailEnabled | boolean | Saako dokumentin luoja ilmoituksen, kun kaikki ovat allekirjoittaneet |
| participantSignedEmailEnabled | boolean | Saako allekirjoittaja vahvistuksen omasta allekirjoituksestaan |
| participantCompletionEmailEnabled | boolean | Saavatko allekirjoittajat ilmoituksen valmiista dokumentista |
{ "error": "string" }
Palauttaa kirjautuneen käyttäjän jäsenyystiedot valitussa organisaatiossa.
Polkuparametrit
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| tenantId* | string | Organisaation tunniste |
Vastaukset
{ "userId": "string", "tenantId": "string", "role": "owner", "createdAt": "2026-08-17T08:36:13.095Z", "updatedAt": "2026-08-17T08:36:13.095Z" }
{ "error": "string" }
Bink lähettää HTTP POST -kutsun palveluusi aina kun dokumentin tila muuttuu. Tätä ei kutsuta itse – konfiguroit endpointtisi Bink-hallintapaneelissa ja Bink kutsuu sitä automaattisesti.
Dokumentin elinkaari
Saapuvat headerit
x-bink-signature– HMAC-allekirjoitus (t=...,v1=...)x-bink-webhook-id– Uniikin toimituksen tunnistex-bink-webhook-event– Tapahtuman tyyppix-bink-webhook-attempt– Toimitusyrityksen numero
Retry-käyttäytyminen
- Enintään 3 toimitusyritystä
- 5 sekunnin aikakatkaisu per yritys
- Vaadi 2xx-vastaus 5 sekunnissa
- Kolmannen epäonnistumisen jälkeen ei uusia yrityksiä
Tärkeät huomiot
- Käytä raw bodyä (ei parsittua JSON:ia)
- Validoi timestamp
tuusimisen hyökkäyssuojan vuoksi - Älä käytä uudelleenohjausta (3xx = epäonnistuminen)
- Idempotenssi: tunnista duplikaatit
x-bink-webhook-id:n avulla
Payload-rakenne
{ "id": "60a10d68-e4f7-4380-af3a-e92d6f0599c6", // vastaa x-bink-webhook-id "type": "document.status_changed", "occurredAt": "2026-04-22T20:03:57.134Z", "tenantId": "3e02f5b5-162a-4ff1-b343-03bbf032d4a1", "data": { "documentId": "cfc80de9-1e3f-4c72-b490-73381c1702da", "oldStatus": "draft", "newStatus": "in_process", "changedAt": "2026-04-22T20:03:57.134Z" } }
Payload-kentät
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| id | string (uuid) | Uniikin webhook-tapahtuman tunniste – vastaa x-bink-webhook-id:tä |
| type | string | Tapahtuman tyyppi: "document.status_changed" |
| occurredAt | string (ISO 8601) | Tapahtuman aikaleima |
| tenantId | string (uuid) | Organisaation tunniste |
| data.documentId | string (uuid) | Dokumentin tunniste |
| data.oldStatus | string | Edellinen tila: "draft" tai "in_process" |
| data.newStatus | string | Uusi tila: "in_process" tai "signed" |
| data.changedAt | string (ISO 8601) | Tilanmuutoksen aikaleima |
Allekirjoituksen varmennus (HMAC-SHA256)
const crypto = require("crypto"); const secret = process.env.BINK_WEBHOOK_SECRET; function verifyBinkSignature(req, webhookSecret) { // 1. Lue x-bink-signature -headeri const raw = req.headers["x-bink-signature"]; const header = Object.fromEntries( raw.split(",").map((p) => p.split("=")) ); // 2. Rakenna allekirjoitettu payload: t.rawBody const payload = req.rawBody; const signedPayload = `${header.t}.${payload}`; // 3. Laske HMAC-SHA256 ja vertaa constant-time -metodilla const expected = crypto .createHmac("sha256", webhookSecret) .update(signedPayload) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(header.v1), Buffer.from(expected) ); } // Käyttö: const ok = verifyBinkSignature(req, secret); if (!ok) return res.status(401).json({ error: "Invalid signature" });
Virhetilanteiden käsittely
| Tilanne | Suositeltu vastaus | Seuraus |
|---|---|---|
| Virheellinen allekirjoitus | 401 tai 400 | Ei uudelleenyritystä |
| Tuntematon tapahtuma | 400 | Ei uudelleenyritystä |
| Käsittelyvirhe palvelimella | Muu kuin 2xx | Uudelleenyritys (max 3) |
| Duplikaattitapahtuma | 200 – ohita hiljaisesti | Tunnista x-bink-webhook-id:llä |
Turvallisuustarkistuslista
x-bink-signature jokaisessa pyynnössät) uusimisen hyökkäyssuojan varmistamiseksi
Bink lähettää HTTP POST -kutsun palveluusi aina kun yksittäisen allekirjoittajan tila muuttuu – esimerkiksi kun yksi allekirjoittaja on allekirjoittanut, vaikka dokumentti olisi vielä kesken. Tämä täydentää dokumenttitason document.status_changed-tapahtumaa, joka laukeaa vasta kun koko dokumentin tila muuttuu.
Allekirjoittajan tila
Sama tila näkyy myös kentässä signees[].status, kun haet dokumentin kutsulla GET /api/documents/{documentId}.
Payload-rakenne
{ "id": "9f4c1b02-77ad-4c1e-9a55-1d0b7e3f8a41", // vastaa x-bink-webhook-id "type": "signee.status_changed", "occurredAt": "2026-04-22T20:11:04.882Z", "tenantId": "3e02f5b5-162a-4ff1-b343-03bbf032d4a1", "data": { "documentId": "cfc80de9-1e3f-4c72-b490-73381c1702da", "signeeId": "a1d9c774-5f28-4b6a-9c33-6f0e2b41c7de", "email": "matti@esimerkki.fi", "oldStatus": "pending", "newStatus": "signed", "changedAt": "2026-04-22T20:11:04.882Z" } }
Payload-kentät
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| id | string (uuid) | Uniikin webhook-tapahtuman tunniste – vastaa x-bink-webhook-id:tä |
| type | string | Tapahtuman tyyppi: "signee.status_changed" |
| occurredAt | string (ISO 8601) | Tapahtuman aikaleima |
| tenantId | string (uuid) | Organisaation tunniste |
| data.documentId | string (uuid) | Dokumentin tunniste |
| data.signeeId | string (uuid) | Allekirjoittajan tunniste – vastaa signees[].id:tä |
| data.email | string | Allekirjoittajan sähköpostiosoite |
| data.oldStatus | string | Edellinen tila, esim. "pending" |
| data.newStatus | string | Uusi tila, esim. "signed" |
| data.changedAt | string (ISO 8601) | Tilanmuutoksen aikaleima |
Headerit, HMAC-SHA256-varmennus, retry-käyttäytyminen ja idempotenssi toimivat täsmälleen samoin kuin document.status_changed-tapahtumassa. Erottele tapahtumat type-kentän tai x-bink-webhook-event-headerin perusteella.
switch (event.type) { case "signee.status_changed": // Yksi allekirjoittaja eteni – päivitä rivin tila updateSignee(event.data.signeeId, event.data.newStatus); break; case "document.status_changed": // Koko dokumentti eteni – esim. signed = kaikki valmista updateDocument(event.data.documentId, event.data.newStatus); break; default: return res.status(400).json({ error: "Unknown event" }); } res.status(200).end();
Valitse, mitkä tapahtumat Bink lähettää endpointtiisi. Asetukset tehdään hallintapaneelista – niitä ei muuteta API:n kautta.
| Asetus | Tapahtuma | Kuvaus |
|---|---|---|
| Dokumentin tilamuutokset | document.status_changed | Ilmoitus, kun dokumentin tila muuttuu: draft → in_process → signed |
| Yksittäisen allekirjoittajan tilamuutokset | signee.status_changed | Ilmoitus, kun yksittäisen allekirjoittajan tila muuttuu |
Mukauta valmiisiin asiakirjoihin lisättäviä allekirjoitus- ja tarkastusketjusivuja. Asetukset vaikuttavat luotuihin PDF-sivuihin, ja ne koskevat kaikkia organisaation dokumentteja – myös API:n kautta luotuja.
Kieli
Luoduilla PDF-sivuilla käytettävä kieli. Tämä on eri asetus kuin sähköpostien emailLanguage.
Päivämäärä ja aika
| Asetus | Tyyppi | Kuvaus |
|---|---|---|
| Käytä UTC-aikaa | boolean | Näytä kaikki allekirjoitus- ja tarkastusaikaleimat UTC-ajassa. Kun päällä, aikavyöhykevalinta ei vaikuta sivuille tulostettaviin aikaleimoihin. |
| Aikavyöhyke | string (IANA) | Aikaleimat noudattavat tämän aikavyöhykkeen kesäaikasääntöjä. |
Tietosuoja
| Asetus | Tyyppi | Kuvaus |
|---|---|---|
| Näytä IP-osoitteet | boolean | Sisällytä tallennetut IP-osoitteet tarkastusketjusivulle. IP-osoitteet tallennetaan joka tapauksessa; tämä asetus vaikuttaa vain siihen, näytetäänkö ne PDF-sivulla. |
Palvelun health check -endpoint. Palauttaa palvelun tilan.
Vastaukset
{ "message": "string" }
Kevyt prosessitason terveystarkistus. Sopii kuormantasaajan tai monitorointityökalun tarkistuspisteeksi.
Vastaukset
{ "status": "string" }
Valmiina rakentamaan?
Luo ilmainen tili, generoi API-avain ja testaa integraatiota sandbox-ympäristössä jo tänään.