API-rajapinta – Easoft Oy

1. Lyhyt esittely

Easoft ERP:n API-rajapinta avaa pääsyn Easoftin tietosisältöön ja toimintoihin, joten sen päälle voi rakentaa integraatioita hyvin laajasti eri tarpeisiin. Yleisimpiä integraatioita ovat esimerkiksi:

Liidien ja yhteydenottojen tuonti nettisivuilta, mainoskampanjoista tai muista järjestelmistä suoraan Easoftin asiakasrekisteriin ja myyntiputkeen
Verkkokauppaintegraatio: verkkokaupan tilaukset Easoftiin, varastosaldojen ylläpito
Dokumenttien ja liitteiden automaattinen tallennus asiakkaan tai liidin yhteyteen, esim. tarjoukset ja sopimukset muista järjestelmistä
Huolto- ja asennustyön aikataulutus, kun kenttätyön tiedot halutaan yhdistää muihin sovelluksiin
Laskutuksen ja tilausten automatisointi, kun tilaukset tai laskut halutaan viedä tai hakea muusta järjestelmästä
Tapahtumapohjainen automaatio webhookien avulla, esim. ilmoitus myyjälle tai muille järjestelmille kun Easoftiin syntyy uusi liidi, tilaus tai muu tapahtuma

Tämä artikkeli antaa yleiskuvan rajapinnan käyttöönotosta, mahdollisuuksista ja teknisistä reunaehdoista sekä täydentää Easoftin varsinaista rajapintakuvausta. Ajantasainen lista endpointeista, niiden parametreista ja paluuarvoista löytyy osoitteesta api-doc.easoft.eu. Tämä on ensisijainen lähde, jos tämä artikkeli ja rajapintakuvaus eroavat toisistaan.

2. Vaatimukset

Rajapinnan käyttöön tarvitaan:

Rajapinta-avain (bearer-token) — ks. kohta 3, Käyttöönotto
Ympäristö tai työkalu HTTP-kutsujen tekemiseen: oma järjestelmä/sovellus, tai integraatioalusta kuten Zapier
Kyky käsitellä JSON-muotoista dataa; tiedostosiirroissa myös binääridataa (application/octet-stream)

3. Käyttöönotto

Rajapinnan käyttöönotto ei edellytä erillisiä lisäpalveluita tai sopimusta. Käyttö hinnoitellaan tehtyjen rajapintakutsujen määrän mukaan (ks. hinnasto alla).

Rajapintatunnuksen voi luoda kahdella tavalla:

Itse Easoftissa: Profiilikuvake (oikea yläkulma) → Rajapinta-avaimet → Luo uusi
Pyytämällä Easoftin tuesta (tuki@easoft.fi)

Avainta luodessa:

avain nimetään
asetetaan tarvittaessa vanhenemispäivämäärä
valitaan luettelosta ne endpointit, joita avaimella saa käyttää
voidaan määrittää käyttäjä, jonka nimissä rajapintakutsujen aikana tehdyt toimenpiteet suoritetaan

Tallennuksen jälkeen muodostuu bearer-token, jolla rajapinta autentikoidaan (ks. kohta 4, Tekninen kuvaus).

Hinnoittelu

Kuukausihinta määräytyy sen mukaan, kuinka monta rajapintakutsua tehdään yhteesnä kuukauden aikana. Kaikkien integraatioiden kutsut lasketaan yhteen (voit siis tehdä eri integraatioille omat avaimet).

Kutsumäärä / kk	Hinta
100–1 000	10,00 €
1 000–10 000	20,00 €
10 000–50 000	100,00 €
50 000+	300,00 €

Rajapinnan toimintoihin voidaan lisäksi yhdistää Easoftin webhookeja (Asetukset -> Webhookit). Jos Webhook-asetusvalikko ei ole näkyvissä, voit pyytää sen aktiiviseksi Easoftin tuesta (tuki@easoft.fi).

4. Tekninen kuvaus

Rajapintakutsut osoitetaan muotoon https://{subdomain}.easoft.eu/api/v1/... (korvaa {subdomain} omalla Easoft-tunnuksella)
Autentikointi: Authorization: Bearer <rajapinta-avain> -otsaketta käyttäen
Pyynnöt ja vastaukset ovat JSON-muodossa, poikkeuksena tiedostojen siirto, joka tehdään binääridatana (Content-Type: application/octet-stream)

Kaikkien endpointtien tarkat kentät, parametrit, paluuarvot ja virhekoodit löytyvät osoitteesta api-doc.easoft.eu. Rajapintakuvaus sisältää myös ajantasaisen muutoslokin rajapintaan tehdyistä muutoksista.

Rajapintakuvauksessa eri endpointien schemat löytyvät seuraavasti:

Avaa api-doc.easoft.eu ja etsi haluamasi endpoint (esim. GET /customers). Klikkaa riviä, jolloin endpointin kuvaus avautuu. Schema löytyy kahdesta paikasta:
- Request body: jos endpoint ottaa vastaan JSON-bodyn, sen alla on välilehdet "Example Value" ja "Schema" – klikkaa "Schema", jolloin näet kenttien nimet, tietotyypit ja pakollisuuden.
- Responses: vastaukset-osiossa eri statuskoodien (esim. 200) alta klikkaa "Schema"-välilehteä vastaavalla tavalla.
Pakolliset kentät on merkitty schemassa tähdellä (*) kentän nimen perässä.

5. Ohjeita yleisimpiin käyttötapauksiin

5.1 Liidin/yhteydenoton luonti nettisivuilta

Nettisivujen yhteydenottolomake voidaan kytkeä Easoftiin kutsulla POST /customers. Yksinkertaisimmillaan asiakas luodaan pelkällä nimellä; laajemmassa kutsussa voidaan välittää kaikki yhteystiedot ja pyytää samalla tekstiviesti- tai sähköposti-ilmoitus myyjälle saapuneesta yhteydenotosta (messaging-kenttä).

Jos käytössä on myyntiputki, liidi voidaan luoda asiakkaan luonnin jälkeen kutsulla POST /pipeline_items. Tähän tarvitaan mm.:

customer_id — saadaan POST /customers-kutsun paluusanomasta
user_id — se käyttäjä, jolle liidi ohjataan (usein sama kuin asiakkaan luonnissa käytetty, mutta voi olla myös kiinteä)
pipeline_id ja pipeline_column_id — myyntiputki ja sarake, johon liidi asetetaan; nämä voi hakea kutsulla GET /pipelines

Esimerkki POST /pipeline_items -kutsun rungosta:

json

{
  "name": "Testi Asiakas 3",
  "description": "Kuvaus joka tulee liidiin",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "date": "2022-11-09",
  "pipeline_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pipeline_column_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "probability": 0,
  "price": 1500
}

Rajapinnan osoite on muotoa https://subdomain.easoft.eu/api/v1/customers (korvaa "subdomain" omalla tiedolla).

5.2 Tiedoston tallentaminen liidin yhteyteen

Liitteen lisääminen liidiin tapahtuu kolmessa vaiheessa:

Liidi luodaan kutsulla POST /pipeline_items (ks. 5.1) → vastauksena saadaan liidin id
Liitteen metadata luodaan kutsulla POST /attachments/uploadMetadata:

json

{
  "model": "PIPELINE_ITEM",
  "foreign_key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Liitteen nimi",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "commercial": true
}

foreign_key = liidin id
user_id = sen henkilön id, jonka nimissä liite luodaan (yleensä sama kuin liidin käyttäjä)
Vastauksena saadaan liitteen id, jota vasten tiedosto siirretään

Itse tiedosto siirretään kutsulla POST /attachments/upload/{id} binääridatana:

curl -X 'POST' \
  'https://subdomain.easoft.eu/api/v1/attachments/upload/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @/path/directory1/Filename.pdf

5.3 Liidin luonti kolmannen osapuolen automaatiotyökalulla (esim. Zapier)

Jos liidejä halutaan tuoda Easoftiin järjestelmästä, johon ei ole omaa integraatiota (esim. Facebook Lead Ads, lomaketyökalut tms.), voidaan käyttää automaatiotyökalua kuten Zapieria. Tähän on kaksi tapaa:

Easoftin oma Zapier-sovellus (suositeltu tapa)

Easoftilla on virallinen Zapier-sovellus, jonka avulla yleisimmät toiminnot onnistuvat ilman erillistä webhook-määrittelyä. Sovellusta pääsee kokeilemaan julkisella kutsulinkillä.

Käyttöönotto:

Luo Zapieria varten uusi rajapinta-avain Easoftista: profiilikuvake (oikea yläkulma) → Rajapinta-avaimet
Anna avaimelle käytettävien toimintojen tarvitsemat oikeudet (ks. taulukko alla)
Kirjaudu Easoftin Zapier-sovellukseen rajapinta-avaimen tokenilla ja yrityksen subdomainilla

Sovelluksen tarjoamat toiminnot ja niiden vaatimat rajapinta-avaimen oikeudet:

Toiminto	Kuvaus	Tarvittavat oikeudet
Liidin luonti	Luo asiakkaan tai käyttää sähköpostiosoitteella jo olemassa olevaa asiakasta, ja luo liidin	Asiakkaat: `GET /customers`, `POST /customers`; Käyttäjät: `GET /users`; Liidi: `POST /pipeline_items`; Myyntiputki: `GET /pipelines`
Liidin haku	Hakee yksittäisen liidin tiedot	Liidi: `GET /pipeline_items/{id}`
Asiakkaan haku	Hakee asiakastietoja	Asiakkaat: `GET /customers`
Myyntiputkien haku	Hakee myyntiputket	Myyntiputki: `GET /pipelines`

Vaihtoehto: yleinen Webhook-integraatio

Jos käytössä on jokin muu automaatiotyökalu kuin Zapier, tai Zapierin oma Easoft-sovellus ei kata tarvittavaa toimintoa, rajapintaa voi käyttää myös yleisellä HTTP-pyynnöllä (esim. Zapierin Webhook by Zapier -toiminnolla, tai vastaavalla toiminnolla muissa työkaluissa):

Rajapinta-avaimelle annetaan oikeus vähintään Asiakkaat → POST /customers; tarvittaessa myös Käyttäjät → GET /users ja Myyntiputki → GET /pipelines, jos näiden id:t halutaan hakea
Triggerinä toimii lähdejärjestelmän tapahtuma (esim. uusi liidi Facebook Lead Adsista)
Actionina käytetään mukautettua HTTP-pyyntöä (Zapierissa: Webhook by Zapier → Custom Request), jossa:
- Method: POST
- URL: https://subdomain.easoft.eu/api/v1/customers
- Headers: Authorization: Bearer <rajapinta-avain>
- Data: JSON-runko asiakkaan tiedoilla ja tarvittaessa pipeline_items-taulukolla, esimerkiksi:

json

{
  "name": "",
  "address": "",
  "postcode": "",
  "phone": "",
  "email": "",
  "locality": "",
  "customer_type": 1,
  "customer_label_code": "",
  "pipeline_items": [{
    "name": "",
    "user_id": "",
    "date": "",
    "description": "",
    "pipeline_column_id": ""
  }]
}

Kenttiä kuten pipeline_column_id ja user_id ei voi yleensä hakea suoraan automaatiotyökalun sisältä, vaan niiden id:t haetaan erikseen komentoriviltä ja syötetään käsin, esim.:

curl -X GET --location "https://subdomain.easoft.eu/api/v1/pipelines" -H "Authorization: Bearer api-token"
curl -X GET --location "https://subdomain.easoft.eu/api/v1/users" -H "Authorization: Bearer api-token"

Data-kentän tulee olla validia JSON:ia (voit tarkistaa esim. jsonlint-työkalulla) — tyhjäksi jäävät tai ei-halutut kentät kannattaa poistaa kutsusta.

6. Muut huomiot

Rajapinnan käyttö on maksullista ja hinnoitellaan kuukausittaisten kutsujen määrän mukaan (ks. kohta 3).
Rajapinnan toimintoihin voidaan yhdistää Easoftin webhookeja tapahtumapohjaista automaatiota varten
Rajapinta-avaimelle voidaan asettaa vanhenemispäivämäärä — muista uusia avain ennen sen vanhenemista.
Rajapintakuvauksessa eri endpointien schemat löytyvät seuraavasti:
- Avaa api-doc.easoft.eu ja etsi haluamasi endpoint (esim. GET /customers). Klikkaa riviä, jolloin endpointin kuvaus avautuu. Schema löytyy kahdesta paikasta:
  - Request body: jos endpoint ottaa vastaan JSON-bodyn, sen alla on välilehdet "Example Value" ja "Schema" – klikkaa "Schema", jolloin näet kenttien nimet, tietotyypit ja pakollisuuden.
  - Responses: vastaukset-osiossa eri statuskoodien (esim. 200) alta klikkaa "Schema"-välilehteä vastaavalla tavalla.
- Pakolliset kentät on merkitty schemassa tähdellä (*) kentän nimen perässä.