Käytämme evästeitä

Käytämme evästeitä parantaaksemme kokemustasi ja analysoidaksemme sivuston liikennettä. Voit valita mitkä evästeet hyväksyt. Tietosuojaseloste

Bink Developer Platform
Developer Platform

Rakenna sähköisen allekirjoituksen integraatio

Bink API tarjoaa kehittäjille tehokkaat työkalut dokumenttien hallintaan ja sähköiseen allekirjoitukseen – suoraan omasta sovelluksestasi.

Luo tili ja aloita Swagger-dokumentaatio ↗

Miksi Bink API?

Yksi rajapinta – kaikki mitä tarvitset sähköiseen allekirjoitukseen ja dokumenttien hallintaan.

📄

Dokumenttien hallinta

Luo, hae ja hallitse 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.

1

Luo tili

Rekisteröidy osoitteessa app.bink.fi ja vahvista sähköpostiosoitteesi. Tilin luominen on ilmaista.

2

Luo API-avain

Siirry asetuksiin kohdasta Settings → API ja klikkaa Create API Key. Kopioi avain talteen – sitä ei voi nähdä enää myöhemmin.

3

Tutustu Swagger-dokumentaatioon

Interaktiivinen API-dokumentaatio on vapaasti saatavilla osoitteessa sandbox-api.bink.fi/docs – ei vaadi kirjautumista.

4

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.

5

Siirry tuotantoon

Kun integraatio on testattu sandboxissa, vaihda API-osoitteeksi api.bink.fi ja aloita tuotantokäyttö. Tuotannon API-osoite: https://api.bink.fi

⚠️

Suojaa API-avaimesi. Älä koskaan tallenna avainta suoraan lähdekoodiin. Käytä ympäristömuuttujia. Jos epäilet avaimesi vuotaneen, peruuta se välittömästi ja luo uusi.

🧪

Sandbox-ympäristö: Käytä sandbox-ympäristöä kehityksen ja testauksen aikana. Sandbox API: sandbox-api.bink.fi · Sandbox UI: sandbox.bink.fi · Swagger: sandbox-api.bink.fi/docs

Esimerkkipyyntö

Luo dokumentti ja liitä allekirjoittajat yhdellä kutsulla.

cURL · Sandbox
# 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 '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
Vastaus · JSON
{
  "message": "Document created successfully",
  "document": {
    "id": "doc_abc123",
    "name": "Yhteistyösopimus",
    "status": "pending",
    "downloadUrl": "https://...",
    "emailLanguage": "fi"
  },
  "signees": [
    { "email": "matti@esimerkki.fi", "name": "Matti Meikäläinen" },
    { "email": "maija@esimerkki.fi", "name": "Maija Meikäläinen" }
  ],
  "contentType": "application/pdf"
}

API-referenssi

Kaikki käytettävissä olevat endpointit yhdellä silmäyksellä. Täydellinen interaktiivinen dokumentaatio: sandbox-api.bink.fi/docs ↗

Dokumentit documents
POST /api/documents/quick-create Pikaluonti allekirjoittajilla

Luo dokumentin lataamalla tiedoston multipart-muodossa ja liittää allekirjoittajat yhdellä kutsulla.

Request body · multipart/form-data

KenttäTyyppiKuvaus
file*binaryLadattava tiedosto
titlestringValinnainen. Oletuksena tiedoston nimi.
tenantId*stringOrganisaation tunniste
folderIdstringValinnainen. Jos vastaa olemassa olevaa kansiota samassa tenantissa, dokumentti luodaan sinne. Muutoin dokumentti luodaan ilman kansiota.
signingMethodstringValinnainen. Allekirjoitustapa: "email" (sähköpostivarmenne, oletusarvo) tai "strong" (vahva tunnistautuminen).
signingMessagestringValinnainen. Henkilökohtainen viesti allekirjoitussähköpostissa. Esim. "Tarkista ja allekirjoita perjantaihin mennessä."
emailLanguagestringValinnainen. Allekirjoitussähköpostien kieli tälle dokumentille. Oletuksena tenantin sähköpostikieli.
signingOrderEnabledbooleanValinnainen. Kun true, allekirjoittajat allekirjoittavat järjestyksessä (sequential signing).
signees*JSON stringJSON-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ä.

Vastaukset

200 400 403 500
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "message": "string",
  "document": {
    "downloadUrl": "string",
    "emailLanguage": "fi"
  },
  "signees": [ { /* signee objects */ } ],
  "contentType": "string"
}
GET /api/documents Listaa dokumentit

Palauttaa kirjautuneen käyttäjän dokumentit valitussa tenantissa.

Query-parametrit

KenttäTyyppiKuvaus
tenantId*stringOrganisaation tunniste
folderIdstring | nullValinnainen. Kansion tunniste.

Vastaukset

200 400 403
200 Vastauksen rakenne · application/json
Esimerkki array
[
  {
    "id": "string",
    "tenantId": "string",
    "folderId": "string",
    "name": "string",
    "status": "signed",
    "pinned": true,
    "emailLanguage": "fi",
    "createdAt": "2026-02-17T11:57:11.607Z",
    "updatedAt": "2026-02-17T11:57:11.607Z"
  }
]
400 403 Virherakenne
Esimerkki object
{
  "error": "string"
}
GET /api/documents/{documentId} Hae dokumentti

Palauttaa yksittäisen dokumentin tiedot tunnisteen perusteella.

Polkuparametrit

KenttäTyyppiKuvaus
documentId*stringDokumentin tunniste

Vastaukset

200 404
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "id": "string",
  "tenantId": "string",
  "folderId": "string",
  "name": "string",
  "status": "signed",
  "pinned": true,
  "emailLanguage": "fi",
  "downloadUrl": "string",
  "createdAt": "2026-02-17T11:57:11.607Z",
  "updatedAt": "2026-02-17T11:57:11.607Z"
}
404 Virherakenne
Esimerkki object
{
  "error": "string"
}
POST /api/documents/{documentId}/send-for-signing Lähetä allekirjoitettavaksi

Lähettää allekirjoituskutsut kaikille dokumentin allekirjoittajille.

Polkuparametrit

KenttäTyyppiKuvaus
documentId*stringDokumentin tunniste

Request body · application/json

KenttäTyyppiKuvaus
emailLanguagestringValinnainen. Allekirjoitussähköpostien kieli. Esim. "fi", "en", "sv".

Vastaukset

200 400 404 429
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "message": "string",
  "result": [
    {
      "email": "string",
      "status": "string",
      "data": {},
      "error": {}
    }
  ],
  "credit": {
    "tenantId": "string",
    "email": 0,
    "strong": 0
  }
}
400 404 Virherakenne
Esimerkki object
{
  "error": "string"
}
429 Rate limit · liian monta pyyntöä
Esimerkki object
{
  "error": "string",
  "reminderCooldownUntil": "2026-02-17T11:57:11.637Z"
}
Organisaatiot tenants
GET /api/tenants Listaa organisaatiot

Palauttaa kirjautuneen käyttäjän organisaatiot (tenantit). Ei parametreja.

Vastaukset

200 401
200 Vastauksen rakenne · application/json
Esimerkki array
[
  {
    "id": "string",
    "name": "string",
    "logo": "string",
    "emailLanguage": "fi",
    "createdAt": "2026-02-17T11:57:11.621Z",
    "updatedAt": "2026-02-17T11:57:11.621Z"
  }
]
401 Virherakenne
Esimerkki object
{
  "error": "string"
}
GET /api/tenants/{tenantId} Hae jäsenyystiedot

Palauttaa kirjautuneen käyttäjän jäsenyystiedot valitussa organisaatiossa.

Polkuparametrit

KenttäTyyppiKuvaus
tenantId*stringOrganisaation tunniste

Vastaukset

200 401 403
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "userId": "string",
  "tenantId": "string",
  "role": "owner",
  "createdAt": "2026-02-17T11:57:11.621Z",
  "updatedAt": "2026-02-17T11:57:11.621Z"
}
401 403 Virherakenne
Esimerkki object
{
  "error": "string"
}
Webhookit webhooks
POST {your-endpoint-url} document.status_changed

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

draft
→
in_process
→
signed
Saapuvat headerit
  • x-bink-signature – HMAC-allekirjoitus (t=...,v1=...)
  • x-bink-webhook-id – Uniikin toimituksen tunniste
  • x-bink-webhook-event – Tapahtuman tyyppi
  • x-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 t uusimisen hyökkäyssuojan vuoksi
  • Älä käytä uudelleenohjausta (3xx = epäonnistuminen)
  • Idempotenssi: tunnista duplikaatit x-bink-webhook-id:n avulla

Payload-rakenne

Esimerkki · document.status_changed application/json
{
  "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äTyyppiKuvaus
idstring (uuid)Uniikin webhook-tapahtuman tunniste – vastaa x-bink-webhook-id:tä
typestringTapahtuman tyyppi: "document.status_changed"
occurredAtstring (ISO 8601)Tapahtuman aikaleima
tenantIdstring (uuid)Organisaation tunniste
data.documentIdstring (uuid)Dokumentin tunniste
data.oldStatusstringEdellinen tila: "draft" tai "in_process"
data.newStatusstringUusi tila: "in_process" tai "signed"
data.changedAtstring (ISO 8601)Tilanmuutoksen aikaleima

Allekirjoituksen varmennus (HMAC-SHA256)

Node.js
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

TilanneSuositeltu vastausSeuraus
Virheellinen allekirjoitus401 tai 400Ei uudelleenyritystä
Tuntematon tapahtuma400Ei uudelleenyritystä
Käsittelyvirhe palvelimellaMuu kuin 2xxUudelleenyritys (max 3)
Duplikaattitapahtuma200 – ohita hiljaisestiTunnista x-bink-webhook-id:llä

Turvallisuustarkistuslista

✓ Tallenna webhook-salaisuus turvallisesti ympäristömuuttujana
✓ Varmenna x-bink-signature jokaisessa pyynnössä
✓ Validoi timestamp (t) uusimisen hyökkäyssuojan varmistamiseksi
✓ Pakota HTTPS-yhteys endpointillesi
✓ Kirjaa webhook-id ja toimitusyritysten määrä lokiin
✓ Toteuta idempotentti käsittely duplikaattien varalta
✓ Kriittisille työnkuluille: harkitse polling-fallbackia varmuuden vuoksi
🧪

Nopea testaus: Käytä webhook.site-palvelua webhookien debuggaamiseen. Avaa sivusto, kopioi uniikki URL-osoitteesi, konfiguroi se Binkissä endpointtina ja tarkastele saapuvia pyyntöjä reaaliajassa – headereita, payloadeja ja uudelleenyrityksiä.

Palvelun tila meta
GET /api/status Tilatarkistus

Palvelun health check -endpoint. Palauttaa palvelun tilan.

Vastaukset

200
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "message": "string"
}
GET /api/health Kevyt terveystarkistus

Kevyt prosessitason terveystarkistus. Sopii kuormantasaajan tai monitorointityökalun tarkistuspisteeksi.

Vastaukset

200
200 Vastauksen rakenne · application/json
Esimerkki object
{
  "status": "string"
}

Valmiina rakentamaan?

Luo ilmainen tili, generoi API-avain ja testaa integraatiota sandbox-ympäristössä jo tänään.

Luo ilmainen tili Swagger-dokumentaatio ↗