eSinetti API

REST-API allekirjoituskierrosten hallintaan. Autentikointi: Authorization: Bearer sk_live_… Kaikki vastaukset JSON, virheet muodossa { error: { code, message } }. Pyyntöraja: 60 pyyntöä minuutissa API-avainta kohden. Ylityksestä vastaus 429 ja Retry-After-otsake (sekunteja ikkunan nollautumiseen); odota se ja toista sama pyyntö. Webhookit: kun tenantille on asetettu webhook_url (Asetukset-sivulla), tapahtumat round.sent, signer.opened, signer.identified, signer.signed, signer.declined, round.completed, round.cancelled ja round.expired lähetetään POST-pyyntönä osoitteeseen HTTP-otsikolla X-eSinetti-Signature: t=<unix>,v1=<hmac_sha256(webhook_secret, t + "." + body)>. Uudelleenyritys epäonnistuneelle toimitukselle: 1min, 5min, 30min, 2h, 12h, 24h, sitten merkitään pysyvästi epäonnistuneeksi. Avaimella voi olla oma webhook_url ja webhook_secret (API-avaimet-sivulla): silloin sillä avaimella luodun kierroksen tapahtumat lähetetään avaimen osoitteeseen avaimen salaisuudella allekirjoitettuna, muuten organisaation osoitteeseen. Erillisen tunnistuksen tapahtumat identification.completed ja identification.failed lähetetään vain sen avaimen omaan webhook-osoitteeseen, jolla tunnistuspyyntö luotiin (ei organisaation yhteiseen osoitteeseen); ilman sitä tulos haetaan GET /identifications/{id} -kutsulla. Payload ei koskaan sisällä henkilötunnusta eikä syntymäaikaa.

Lataa OpenAPI-spesifikaatio (JSON)

post/rounds

Luo uuden allekirjoituskierroksen

Pyynnön runko

  • company_idstring (uuid)
  • titlepakollinenstring
  • sequentialboolean
  • expires_in_daysinteger
  • external_refstring
  • documentspakollinenobject[]
  • signerspakollinenobject[]
  • sendboolean
  • requested_byobject

    Kuka pyytää allekirjoitusta. Näkyy viesteissä muodossa "Nimi (Organisaatio) kutsui sinut allekirjoittamaan". Organisaation oletus on tilin lähettäjänimi.

    • namestring
    • organizationstring

Vastaukset

  • 201Kierros luotu
  • 400Validointivirhe
  • 401Virheellinen API-avain
  • 422standing_signer_id ei viittaa tämän organisaation vakioallekirjoittajaan
get/rounds

Listaa kierrokset

Parametrit

statusquery
external_refquery

Vastaukset

  • 200Lista kierroksia
get/rounds/{id}

Hakee kierroksen tilan, asiakirjat ja allekirjoittajat

Parametrit

id*path

Vastaukset

  • 200Kierros
  • 404Ei löytynyt
post/rounds/{id}/send

Lähettää luonnostilassa olevan kierroksen (ensimmäiset kutsut)

Parametrit

id*path

Vastaukset

  • 200Lähetetty
  • 409Kierros ei ole luonnostilassa
post/rounds/{id}/cancel

Peruuttaa kierroksen

Parametrit

id*path

Vastaukset

  • 200Peruutettu
  • 409Kierrosta ei voi enää peruuttaa
post/rounds/{id}/remind

Lähettää muistutuksen vielä allekirjoittamattomille

Parametrit

id*path

Vastaukset

  • 200Muistutukset lähetetty
  • 429Kierrokselle lähetettiin muistutus alle kaksi minuuttia sitten, eikä uutta lähetetä. Retry-After kertoo odotusajan sekunteina. Mitään ei lähetetty; toista pyyntö odotuksen jälkeen.
post/rounds/{id}/signers/{signerId}/signing-link

Antaa allekirjoittajalle lyhytikäisen upotuslinkin

Sovelluksesi kirjautunut käyttäjä, joka on myös kierroksen allekirjoittaja, voi allekirjoittaa heti ilman sähköpostia. Avaa palautettu url ponnahdusikkunaan (window.open, ei iframe: pankkitunnistus ei toimi iframessa). Kun allekirjoitus on valmis, ikkuna lähettää avaajalle postMessage-viestin { type: 'esinetti:completed', roundId } vain, jos sivusi origin on eSinetin asetuksissa kohdassa Sallitut domainit (upotus). Tarkista viestin origin omalla puolellasi. Linkki on voimassa 30 minuuttia ja vain tälle allekirjoittajalle. Uusi kutsu antaa uuden linkin ja mitätöi edellisen upotuslinkin; sähköpostilla lähetetty linkki pysyy voimassa. Linkki on avain allekirjoittajan paikalle: älä tallenna sitä, lokita sitä tai anna sitä muulle kuin allekirjoittajalle itselleen. Enintään 10 linkkiä 10 minuutissa allekirjoittajaa kohden.

Parametrit

id*path
signerId*path

Vastaukset

  • 200Upotuslinkki
  • 401Virheellinen API-avain
  • 404Kierrosta tai allekirjoittajaa ei löytynyt (tai se kuuluu toiselle organisaatiolle)
  • 409Allekirjoittaja on jo allekirjoittanut tai kieltäytynyt, kierros ei ole avoinna, tai peräkkäisessä kierroksessa allekirjoittajan vuoro ei ole vielä tullut
  • 429Liikaa pyyntöjä. API-avaimen rajan (60 / min) ylittyessä Retry-After kertoo odotusajan sekunteina.
get/rounds/{id}/documents/{docId}/download

Ohjaa lyhytikäiseen (max 24h) latauslinkkiin

Parametrit

id*path
docId*path
originalquerytrue = alkuperäinen PDF, muuten sinetöity (vaatii completed-kierroksen)

Vastaukset

  • 302Ohjaus signed URL:iin
  • 404Ei löytynyt
  • 409Sinetöityä versiota ei vielä ole
get/standing-signers

Listaa organisaation vakioallekirjoittajat

Integraatio tarkistaa tällä standing_signer_id:nsä. Vakioallekirjoittajat luodaan ja niitä muokataan vain eSinetin Asetukset-sivulla, koska henkilötunnus annetaan siellä. Vastaus ei sisällä henkilötunnusta, sen tiivistettä eikä sähköpostia.

Vastaukset

  • 200Lista vakioallekirjoittajista
  • 401Virheellinen API-avain
post/companies

Luo tai päivittää yhtiön (upsert business_id:llä)

Pyynnön runko

  • namepakollinenstring
  • business_idstring
  • external_refstring

Vastaukset

  • 201Yhtiö luotu/päivitetty
get/companies

Listaa tenantin yhtiöt

Vastaukset

  • 200Lista yhtiöitä
get/companies/lookup

Hakee yhtiön perustiedot PRH:n avoimesta YTJ-rajapinnasta

Esitäyttöä varten: nimi, yhtiömuoto (`company_form`, tuntematon muoto → `muu`), osoite, rekisteröintipäivä ja kaupparekisterin tila. Ei tallenna mitään. Y-tunnuksen tarkistenumero tarkistetaan. Kotipaikka ja henkilöt eivät sisälly avoimeen dataan. Lähde: PRH ja Verohallinto, YTJ-avoin data (CC BY 4.0).

Parametrit

business_id*query

Vastaukset

  • 200Yhtiön tiedot
  • 400Virheellinen Y-tunnus
  • 404Y-tunnusta ei löytynyt PRH:sta
  • 503PRH:n rajapinta ei vastannut
post/companies/{id}/persons

Synkronoi yhtiön henkilöt (hallitus, toimitusjohtaja, tilintarkastaja)

Oletus `mode: upsert` päivittää täsmäävät ja lisää uudet mutta EI POISTA ketään — keskeytynyt vienti ei saa tyhjentää hallitusta. `replace` poistaa ne, joita listassa ei ole. Täsmäys tehdään nimellä (kirjainkoko, diakriitit ja sanajärjestys normalisoidaan). Rooli ei ole osa täsmäystä, joten roolin muutos päivittyy oikein. `expected_hetu` otetaan vastaan selväkielisenä, muunnetaan HMAC:ksi heti ja hävitetään. **Jos kenttää ei anneta, olemassa oleva tiiviste säilyy** — sitä ei voi laskea uudelleen, koska selväkielistä henkilötunnusta ei tallenneta.

Parametrit

id*path

Pyynnön runko

  • modeenum: upsert | replace
  • personspakollinenobject[]

Vastaukset

  • 200Synkronoitu. Vastaus kertoo muutosten määrät ja henkilöt ilman tiivisteitä; `has_expected_identity` kertoo onko ennakkotarkistus voimassa.
  • 404Yhtiötä ei löytynyt
get/companies/{id}/persons

Listaa yhtiön henkilöt

Parametrit

id*path

Vastaukset

  • 200Lista henkilöitä
post/companies/{id}/fiscal-years

Luo tai päivittää tilikauden (upsert end_date:lla)

`figures` YHDISTETÄÄN olemassa oleviin lukuihin, ei korvata: lähetä vain ne luvut jotka tiedät, niin käyttöliittymässä täydennetyt eivät katoa. Tyhjä merkkijono tai `null` poistaa avaimen tietoisesti; nolla on merkitsevä luku eikä poista mitään.

Parametrit

id*path

Pyynnön runko

  • start_datepakollinenstring (date)
  • end_datepakollinenstring (date)
  • statusenum: open | closing | signed | filed
  • figuresobject

    Vapaa avainjoukko, esim. result_eur, balance_total_eur, dividend_eur.

Vastaukset

  • 200Tilikausi päivitetty
  • 201Tilikausi luotu
  • 404Yhtiötä ei löytynyt
get/companies/{id}/fiscal-years

Listaa yhtiön tilikaudet

Parametrit

id*path

Vastaukset

  • 200Lista tilikausia
post/fiscal-years/{id}/generate

Luo tilikauden asiakirjat ja allekirjoituskierroksen

Pöytäkirjat ja tilinpäätöksen allekirjoitussivu syntyvät yhtiön tallennetuista tiedoista (hallitus, tilikausi, luvut) ja lähtevät hallitukselle allekirjoitettavaksi. Ilman `template_keys`-kenttää käytetään yhtiömuodon oletuspohjia. Vain JULKAISTUT pohjat kelpaavat. Allekirjoittajat ovat kokouspäivänä toimessa olleet hallituksen jäsenet, joilla on sähköposti; ilman sähköpostia jääneet palautetaan `signers_missing_email`-kentässä. Henkilötunnusta ei oteta vastaan: ennakkotarkistus tulee yhtiön henkilöiden tallennetuista tiivisteistä.

Parametrit

id*path

Pyynnön runko

  • template_keysstring[]

    Esim. hallituksen_kokous_tilinpaatos, tilinpaatoksen_allekirjoitussivu, varsinainen_yhtiokokous.

  • dataobject

    Pohjien kenttien arvot litteänä objektina (esim. meeting_date, meeting_place). Validoidaan valittujen pohjien yhdistettyä kenttämäärittelyä vasten.

  • sendboolean

    Lähetetäänkö allekirjoituskutsut heti.

Vastaukset

  • 201Asiakirjat ja kierros luotu
  • 400Kenttävirheitä (`error.fields`) tai pohja ei sovi yhtiömuodolle
  • 404Tilikautta tai pohjaa ei löytynyt
  • 503Renderöintipalvelu ei vastaa — yritä uudelleen
post/documents/render

Renderöi asiakirja pohjasta PDF:ksi (ei tallenna mitään)

Tilaton: pohja + arvot → PDF. Mitään ei tallenneta. Kuvat annetaan base64:na, koska renderöijä ei hae ulkoisia resursseja. Anna `today`, jos haluat että sama syöte tuottaa aina saman PDF:n.

Pyynnön runko

  • template_idpakollinenstring (uuid)
  • entity_namepakollinenstring
  • entity_identifierstring
  • entity_domicilestring
  • dataobject
  • itemsobject[]
  • todaystring (date)
  • assetsobject[]

Vastaukset

  • 200PDF renderöity
  • 400Virheellinen syöte tai julkaisematon pohja
  • 404Pohjaa ei löytynyt
post/documents/seal

Sinetöi PDF ilman allekirjoittajia

Asiakirja, jolla ei ole allekirjoittajia mutta jonka aitous on voitava todentaa myöhemmin (esim. todistus tai vuosilaskelma). Löytyy tämän jälkeen `GET /verify?sha256=…`-reitiltä. `metadata` upotetaan PDF:n audit-liitteeksi ja on PYSYVÄ — älä koskaan lähetä siinä henkilötunnusta; pyyntö hylätään, jos siltä näyttävä arvo havaitaan.

Pyynnön runko

  • namepakollinenstring
  • content_base64string
  • upload_idstring (uuid)
  • reasonstring
  • metadataobject
  • retain_yearsinteger

    Säilytysaika vuosina, jonka jälkeen sinetöity tiedosto poistetaan. Puuttuva = ei automaattista poistoa. Ohitetaan, jos organisaatio on kytkenyt arkiston säilytysajan pois.

Vastaukset

  • 201Asiakirja sinetöity
  • 400Virheellinen PDF, tuntematon upload_id tai henkilötunnus metatiedoissa
get/templates

Listaa käytettävissä olevat asiakirjapohjat

Palauttaa järjestelmäpohjat ja kutsujan omat pohjat, myös julkaisua odottavat. `usable` kertoo, voiko pohjaa käyttää `POST /documents/render` -kutsussa juuri nyt. Pohjan HTML:ää ei palauteta: sen lähde on integroijan omassa repossa.

Vastaukset

  • 200Pohjat
put/templates

Vie oma asiakirjapohja

Luo tai päivittää kutsujan oman pohjan. Idempotentti avaimen ja version suhteen. **Pohja ei julkaistu tämän kutsun jälkeen**: julkaisu tehdään erikseen juridisen sisällön tarkistuksen jälkeen, joten uusi pohja ei ole heti käytettävissä renderöinnissä. Jo julkaistua versiota ei ylikirjoiteta — vastauksen `action` on silloin `skipped_published`, ja muutos on tehtävä uutena versiona.

Pyynnön runko

  • keypakollinenstring
  • namepakollinenstring
  • versionpakollineninteger
  • htmlpakollinenstring
  • schemaobject
  • legal_basisstring

Vastaukset

  • 200Pohja päivitetty tai ohitettu julkaistuna
  • 201Pohja luotu
  • 400Virheellinen syöte
post/uploads

Luo signed upload URL:n suurelle PDF:lle

Pyynnön runko

  • filenamepakollinenstring
  • size_bytespakollineninteger

Vastaukset

  • 201Latauslinkki luotu
get/usage

Käyttökooste ja laskutuksen erittely kuukaudelta

Palauttaa kuukauden käyttötapahtumat koosteena (`summary`) sekä laskutuksen erittelyn (`billing`) organisaation laskutusmallin mukaan. Tilitoimistolle hinta perustuu aktiivisten asiakasyhtiöiden määrään marginaaliportaittain (`billing.model = "per_company"`, `billing.subscription` sisältää porrastuksen); muille organisaatioille kappalehintaan (`billing.model = "per_signature"`, `billing.subscription = null`). Tilitoimistomallissa kuukausihintaan sisältyvät pöytäkirjat ja tilinpäätökset — muut asiakirjat laskutetaan kappalehinnalla, ja jako näkyy kentissä `included_signatures` ja `billable_signatures`. Summat ovat kuukauden arvio; lopullinen laskun peruste otetaan kuukauden vaihtuessa.

Parametrit

monthqueryVVVV-KK, Europe/Helsinki-vyöhykkeellä. Oletus: kuluva kuukausi.

Vastaukset

  • 200Kooste
  • 400Virheellinen kuukausi
post/identifications

Luo vahvan tunnistuksen pyynnön ilman allekirjoitusta

Käytä, kun tarvitset vain varmistuksen siitä, kuka käyttäjä on, esimerkiksi ennen keskustelun avaamista. Vastauksen url avataan käyttäjän selaimessa (täysi sivunavaus, ei iframe). Käyttäjä tunnistautuu pankkitunnuksilla tai mobiilivarmenteella ja palaa return_url-osoitteeseen, johon eSinetti lisää parametrit identification_id, status (completed, failed tai cancelled) ja oman state-arvosi. Paluuosoite ei kerro tunnistetun henkilön tietoja: hae tulos GET /identifications/{id} -kutsulla tai ota se vastaan webhookina (identification.completed). Paluuosoitteen domain pitää olla organisaation Asetuksissa kohdassa Sallitut domainit (upotus); muuten pyyntö hylätään koodilla 422. Linkki on kertakäyttöinen ja voimassa oletuksena 60 minuuttia (expires_in_minutes 5–1440). Linkki on avain tunnistukseen: älä lokita sitä äläkä anna sitä muulle kuin tunnistautuvalle käyttäjälle. Laskutus: onnistunut tunnistus kirjataan yhtenä vahvana tunnistuksena (sama kappalehinta ja kuukausikatto kuin vahvalla allekirjoituksella). Epäonnistuneesta tai perutusta ei veloiteta.

Pyynnön runko

  • return_urlpakollinenstring (uri)

    https-osoite sallitulla domainilla.

  • external_refstring

    Oma viitteesi, palautuu tuloksessa.

  • statestring

    Oma tilasi (esim. CSRF-suoja). Palautuu paluuosoitteessa sellaisenaan.

  • expires_in_minutesinteger

Vastaukset

  • 201Tunnistuspyyntö luotu
  • 400Validointivirhe
  • 401Virheellinen API-avain
  • 403Organisaation kuukausittainen tunnistuskatto on täynnä
  • 422Paluuosoitteen domain ei ole sallittujen domainien listalla (tai lista on tyhjä)
  • 503Toiminto ei ole vielä käytössä tässä ympäristössä
get/identifications/{id}

Hakee tunnistuspyynnön tilan ja tuloksen

Parametrit

id*path

Vastaukset

  • 200Tunnistuspyyntö
  • 404Ei löytynyt (tai kuuluu toiselle organisaatiolle)
get/verify

Julkinen aitoustarkistus (EI vaadi API-avainta)

Tarkistaa onko annettu SHA-256-tiiviste eSinetin sinetöimä asiakirja ja palauttaa allekirjoitustapahtumat ilman henkilötunnisteita (ei hetua, ei syntymäaikaa, ei sähköpostia). Julkinen ja tenant-riippumaton — kuka tahansa jolla on sinetöity PDF (ja voi siis laskea sen tiivisteen) voi tarkistaa sen aitouden. IP-pohjainen rate limit (30/min).

Ei vaadi API-avainta (julkinen).

Parametrit

sha256*queryAsiakirjan (sinetöidyn PDF:n) SHA-256-tiiviste heksadesimaalina.

Vastaukset

  • 200Tulos (found: false jos tiivistettä ei löydy — tämä ei ole virhe)
  • 400Virheellinen sha256-parametri
  • 429Liikaa pyyntöjä