NAV Navbar
Logo
JSON

API Dokumentaatio

Tervetuloa Slotin API-dokumentaatioon! Tämän API-dokumentation alta löydät tietoa ja ohjeita Slotin REST API rajapintojen käyttöön.

Slotista löytyy sekä julkiseen varaussivuun verrattavissa oleva Ajanvaraus API että työntekijäjärjestelmän tietojen käsittelyyn tarkoitettu Slotti API.

Autentikointi

Autentikointi Slotin rajapintoihin tehdään API-avaimen (API-key) ja HTTP Basic Auth -kirjautumisen avulla. API avainta käytetään Basic Authin käyttäjänimenä, salasanaa ei tarvita.

API-avaimen saat luotua tilisi Integraatio-asetuksista. Täältä voit myös poistaa tai vaihtaa aikaisempia avaimia.

Versiointi

Kaikki rajapinnat versioidaan polkuun lisättävällä versionumerolla, kuten “v1”.

Esimerkki: https://slotti.fi/api/v1/

Mikäli rajapintaan tehdään taaksepäin yhteensopimattomia muutoksia, julkaistaan uusi (esim. “v2”) rajapintaversio. Vanhojen versioiden poistumisesta käytöstä tiedotetaan erikseen etukäteen.

Testausympäristö

Integraatioiden testausta varten suosittelemme tekemään tilin Slotin testausympäristöön, osoitteessa https://dev.slotti.fi. Kaikki rajapinnat sekä toiminnot ovat normaalisti käytettävissä myös testausympäristössä.

Pitkäkestoinen testaus

Mikäli testitiliä käytetään pitkään, vastaan voi tulla kokeilujakson päättyminen. Tällöin tilin saa takaisin käyttöön joko tekemällä tilauksen tilin asetuksista (oikeata laskua asiasta ei lähde sillä testitilin käyttö on ilmaista) tai pyytämällä pidennystä tuesta.

Pitempiaikaisen testauksen yhteydessä on hyvä kuitenkin huomioida, että emme takaa testiympäristössä olevien tilien ja niiden asetusten säilyvyyttä, vaan saatamme ajoittain tuoda tuoreemmat tilikopiot tuotantotileistä testauspuolelle, asiasta erikseen ilmoittamatta.

Ajanvaraus API

Ajanvaraus API:n kautta voit tehdä uusia varauksia haettujen vapaiden aikojen perusteella. Ajanvaraus API on siis ohjelmallinen vastine Slotin varaussivulle. Uusien varauksien tekoa varten API:sta saa noudettua seuraavat tiedot:

Ajanvaraus API:n kautta ei voi noutaa

API ROOT

API on tilikohtainen ja sen perusosoitteena toimii tilin varaussivun osoite. Esimerkiksi:

https://slotti.fi/booking/{tili}/api/v2/

Palvelut

Yrityksen tarjoamat palvelut voi noutaa tästä resurssista.

Pyyntö palauttaa listan palveluita JSON-muotoisena:

[
  {
    "categoryGuid": "72d6b334-cc87-439d-a9d0-3c41d906875d",
    "providerGuids": [
      "7d0a73c3-274e-47d3-ad3a-9eb358cc05c3"
    ],
    "ordinal": 0,
    "price": 30,
    "translations": [
      {
        "name": "Testipalvelu",
        "languageCode": "fi",
        "description": null
      }
    ],
    "durationMinutes": 30,
    "onlyBookableByPhone": false,
    "guid": "2358dbde-7e1c-42f6-a31d-50f05b95217d"
  }
]

HTTP Request

GET https://slotti.fi/booking/{testitili}/api/v2/services

Kenttä Selite
categoryGuid Sen palveluryhmän tunniste, johon tämä palvelu kuuluu
providerGuids Lista palvelun tarjoavien resurssien tunnisteita
ordinal Järjestysnumero, jonka mukaan järjestettynä palvelut tulisi näyttää
price Palvelun hinta (EUR)
translations Lista käännöksiä palvelun nimestä ja kuvauksesta
→ languageCode Kielitunnus
→ name Palvelun nimi
→ description Palvelun kuvaus
durationMinutes Palvelun kesto minuutteina
onlyBookableByPhone Boolean, joka on true jos palvelu tulee varata puhelimitse
guid Palvelun uniikki tunniste

Resurssit

Resurssit, kuten työntekijät tai muut varauksen kohteet voi noutaa tästä API-resurssista.

Pyyntö palauttaa listan resursseja JSON-muotoisena. Esimerkkivastaus:

[
  {
    "name": "Testi Käyttäjä",
    "imgUrl": null,
    "guid": "7d0a73c3-274e-47d3-ad3a-9eb358cc05c3",
    "id": 2
  }
]

HTTP Request

GET https://slotti.fi/booking/{testitili}/api/v2/resources

Kenttä Selite
name Resurssin nimi
imgUrl Resurssin kuvaan osoittava polku
guid Resurssin uniikki tunniste
id Resurssin numeerinen tunniste

Vapaat ajat

Kun haluttu palvelu, mahdollinen resurssi ja aikaväli on tiedossa, voi API:sta noutaa vapaat ajat kyseisillä parametreilla tästä resurssista.

Pyynnön sisältö (JSON payload):

    {
      "params": {
        "start": "2016-03-30T21:00:32.334Z",
        "end": "2016-06-09T21:00:32.334Z",
        "serviceLinks": [
          {
            "type": "primary",
            "serviceGuid": "2358dbde-7e1c-42f6-a31d-50f05b95217d",
            "durationMinutes": 30
          }
        ],
        "resourceId": 2
      }
    }

Päivämäärät ISO8601 muotoisina (javascript: new Date().toISOString())

HTTP Request

POST https://slotti.fi/booking/{testitili}/api/v2/bookings/serviceavailability

Pyynnön params-objektin kentät

Kenttä Selite
start pyydetyn aikavälin alku
end pyydetyn aikavälin loppu
serviceLinks palveluyhdistelmä, jolle vapaat ajat haetaan
→ type palvelun tyyppi, normaalisti “primary”
→ serviceGuid palvelun tunniste
→ durationMinutes palvelun kesto
resourceId resurssi, jolle vapaita aikoja haetaan (vapaaehtoinen)

Vastaus

Esimerkkivastaus, jossa 3.4.2016 ei ole vapaita aikoja, mutta 4.4.2016 aikoja löytyy:

[
  ...
  {
    "availableTimes": [],
    "date": "2016-04-03"
  },
  {
    "availableTimes": [
      {
        "resourceGuid": "7d0a73c3-274e-47d3-ad3a-9eb358cc05c3",
        "resourceId": 2,
        "start": "2016-04-04T09:00+03:00",
        "end": "2016-04-04T09:30+03:00"
      },
      {
        "resourceGuid": "7d0a73c3-274e-47d3-ad3a-9eb358cc05c3",
        "resourceId": 2,
        "start": "2016-04-04T09:30+03:00",
        "end": "2016-04-04T10:00+03:00"
      },
      ...
    ],
    "resourceGuid": "7d0a73c3-274e-47d3-ad3a-9eb358cc05c3",
    "date": "2016-04-04"
  },
  ...
]

Pyyntö palauttaa listan päivittäin ryhmiteltyjä vapaita aikoja.

Kenttä Selite
date päivä, jolle vapaat ajat on listattuna
availableTimes Lista vapaita aikoja kuvaavia objekteja
→ start ajan alku
→ end ajan loppu
→ resourceGuid vapaan ajan resurssin tunniste
→ resourceId vapaan ajan resurssin numeerinen tunniste

Uusi varaus

Esimerkkipyyntö:

{
  "resourceId": 2,
  "start": "2016-04-04T07:00:00.000Z",
  "end": "2016-04-04T07:30:00.000Z",
  "customerLink":{
    "personCount": 1,
    "customer": {
      "firstName": "Testi",
      "lastName": "Asiakas",
      "email": "testi@example.com",
      "phone": "040-12345678",
      "language": "fi"
    }
  },
  "info": null,
  "serviceLinks": [
    {
      "type": "primary",
      "serviceGuid": "2358dbde-7e1c-42f6-a31d-50f05b95217d",
      "durationMinutes": 30
    }
  ],
  "anyProvider": false
}

Kun haluttu aika on tiedossa (valittu haetuista vapaista ajoista), voidaan uusi varaus tehdä seuraavalla pyynnöllä:

HTTP Request

POST https://slotti.fi/booking/{testitili}/api/v2/bookings/

Pyynnön kentät

Resurssin tunnus sekä ajan alku ja loppu on tarkoitus poimia aiemmin haetusta vapaasta ajasta.

Kenttä Selite
resourceId varattavan resurssin numeerinen tunnus (vapaasta ajasta)
start varattavan ajan alkuajankohta (vapaasta ajasta)
end varattajan ajan loppuajankohta (vapaasta ajasta)
customerLink asiakastapahtumaan liittyvät tiedot
→ personCount Montako henkilöä tämän asiakkaan nimissä saapuu (yleensä 1, muutoin vaatii varauksen ryhmäkoko -lisäosan)
→ customer Asiakas-objekti
→ → firstName Asiakkaan etunimi
→ → lastName Asiakkaan sukunimi
→ → email sähköpostiosoite (pakollisuus varaussivun asetusten mukainen)
→ → phone puhelinnumero (pakollisuus varaussivun asetusten mukainen)
→ → language kielikoodi (vapaaehtoinen, tällöin oletuksena suomi)
info varauksen lisätiedot
serviceLinks varattavien palveluiden yhdistelmä (lista)
→ type palvelun tyyppi, normaalisti “primary”
→ serviceGuid palvelun tunniste
→ durationMinutes palvelun kesto
anyProvider vapaaehtoinen, “true” jos asiakkaalle ei väliä mikä resurssi palvelun tarjoaa

Vastauskoodit

Varauksen haku

Varauksen perustiedot voi hakea paluuosoitteen mukana annettavilla queryparametreilla seuraavasti:

GET https://slotti.fi/booking/{testitili}/api/v2/bookings/customerlink/{customerLinkGuid}

Palvelin palauttaa perustiedot varauksesta (ajankohta, palvelu), mutta tietosuojasyistä mitään asiakastietoja ei palauteta. Jos tarkempia tietoja varauksesta tarvitaan, tulee tietoja hakea suojatun Slotti-API:n kautta.

Slotti API

Slotti API:n kautta rajattu osa Slotti varausjärjestelmän ja Slotti kassan tiedoista on käytettävissä ohjelmallisesti.

API ROOT

Slotti API löytyy osoitteesta https://slotti.fi/api/v1/.

Toimipisteet

Pyyntö palauttaa listan toimipisteitä JSON-muotoisena:

[
  {
    "guid": "52b2556d-cede-404f-a2c8-57047bb03123",
    "translations": [
      {
        "name": "Helsinki",
        "confirmationInfo": null,
        "languageCode": "fi"
      },
      {
        "name": "Helsingfors",
        "confirmationInfo": null,
        "languageCode": "sv"
      }
    ],
    "city": null,
    "phone": null,
    "addressLine1": null,
    "addressLine2": null
  }
]

Voit hakea toimipistelistauksen seuraavasti.

HTTP Request

GET https://slotti.fi/api/v1/locations/

Kenttä Selite
guid Toimipisteen tunniste
translations Toimipisteen käännettävät kentät
city kaupunki
phone puhelinnumero
addressLine1 Osoiterivi 1
addressline2 Osoiterivi 2

Asiakkaat

HTTP Request

Esimerkki vastaus asiakaslistaukseen.


{
  "count": 1,
  "items": [
    {
      "guid": "851982cd-6b68-40b2-82c5-cd3f10c3b382",
      "firstName": "Testi",
      "lastName": "Asiakas",
      "language": "fi",
      "notes": null,
      "streetAddress": null,
      "phone": "044-3411156",
      "email": null,
      "city": null,
      "zipCode": null,
      "company": true,
      "companyName": "Test Company Ltd",
      "companyDepartment": "IT",
      "companyCode": "9876543-2",
      "finvoiceAddress": "003798765432",
      "finvoiceIntermediator": "HELSFIHH"
    }
  ]
}

GET https://slotti.fi/api/v1/customers

Parametrit

Parametri Selite
searchTerm Hakuehto asiakaskyselyyn
limit Rajoitus, montako hakutulosta yhdellä sivulla palautetaan. Oletus ja maksimi on 20.
offset Määrä, montako hakutulosta hypätään yli ennen poiminnan aloittamista

Asiakaskyselyn vastaus on PagedResult-tyyppinen, eli se sisältää hakuosumien määrän count-kentässä ja hakuosumat items-kentässä.

Varaukset

Varausten haku

Pyyntö palauttaa listan varauksia

[
  {
    "guid": "0822b475-73f7-4b3b-8a9b-85da065f2094",
    "resourceGuid": "9abcaf2b-14cb-4d60-aecc-d91c8ab9523b",
    "created": "2017-01-15T15:32:00Z",
    "modified": "2017-01-15T15:32:00Z",
    "warmupStart": "2017-02-01T07:15:00Z",
    "start": "2017-02-01T07:15:00Z",
    "end": "2017-02-01T10:15:00Z",
    "cooldownEnd": "2017-02-01T10:15:00Z",
    "info": "Lisätiedot",
    "privateNotes": null,
    "busyTime": false,
    "busyTimeTitle": null,
    "anyProvider": false,
    "customerLinks": [
      {
        "customer": {
          "guid": "851982cd-6b68-40b2-82c5-cd3f10c3b382",
          "firstName": "Testi",
          "lastName": "Asiakas",
          "language": "en",
          "notes": null,
          "streetAddress": null,
          "phone": "044-3411156",
          "email": null,
          "city": null,
          "zipCode": null,
          "company": false,
          "companyName": null,
          "companyDepartment": null,
          "companyCode": null,
          "finvoiceAddress": null,
          "finvoiceIntermediator": null
        },
        "onlineBooking": false,
        "personCount": 1,
        "token":"4DV3C88M"
      }
    ],
    "serviceLinks": [
      {
        "durationMinutes": 180,
        "service": {
          "guid": "3fd6fc7e-4572-4eff-bd9e-75ffdadc05c7",
          "translations": [
            {
              "name": "Testipalvelu",
              "languageCode": "fi",
              "description": "Palvelun kuvausteksti"
            }
          ]
        }
      }
    ],
    "attributes": [
        {
          "typeGuid": "a60bdf00-aa56-4574-a409-f7c13e39dade",
          "typeName": "how_did_you_find_us",
          "dataType": "string",
          "stringValue": "google mainoksen perusteella",
          "booleanValue": null,
          "enumValue": null,
          "decimalValue": null
        }
     ]
  }
]

HTTP Request

GET https://slotti.fi/api/v1/bookings/?from=2017-01-30T09:31:24.631Z&to=2017-02-27T09:31:24.631Z

Parametri Selite
from ISO Aikaleima, mistä lähtien varaukset poimitaan.
to ISO Aikaleima, mihin asti varaukset poimitaan. Max 30pv from-parametrista.

Vastaus

Kenttä Selite
guid Varauksen uniikki tunniste
resourceGuid Varatun resurssin, esim. käyttäjän uniikki tunniste
created Varauksen luontiajankohta
modified Varauksen viimeisin muokkausajankohta
warmupStart Varauksen alkujärjestelyajan alku
start Varauksen alkuajankohta (asiakkaalle varattu aika)
end Varauksen loppuajankohta (asiakkaalle varattu aika)
cooldownEnd Varaukksen loppujärjestelyajan loppu
info Asiakkaan varaukseen liittyvät lisätiedot
privateNotes Sisäiset lisätiedot
busyTime Boolean, joka kertoo onko kyseessä muu meno
busyTimeTitle Muun menon otsikko
anyProvider Onko kyseessä varaus, johon ei ole valittu tiettyä resurssia
customerLinks Lista varaukseen liittyviä asiakkaita lisätietoineen, ks. CustomerLink-objekti alla
serviceLinks Lista varaukseen liittyviä palveluita lisätietoineen, ks ServiceLink-objekti alla
attributes Lista varaukseen liittyviä lisäkenttiä tyyppi- ja arvokenttineen, ks. Attribute-objekti

CustomerLink-objekti

Kenttä Selite
customer Varauksen tehnyt asiakas
onlineBooking true jos asiakas on varannut ajan netissä.
personCount Varaukseen saapuvien henkilöiden määrä. Aina 1, ellei lisäosa ole käytössä.
token Varauksen koodi (asiakaskohtainen)
queued true jos varaus on tunnille ja jonossa.

ServiceLink-objekti

Kenttä Selite
durationMinutes Palvelun kesto
service Varattu palvelu

Attribute-objekti

Kenttä Selite
typeGuid Lisäkentän yksilöivä tunniste
typeName Lisäkentän yksilöivä nimi
dataType Lisäkentän tietotyyppi. Arvo on sijoitettu tyyppiä vastaavaan kenttään.
stringValue Tekstimuotoisen lisäkentän arvo
booleanValue Boolean-muotoisen lisäkentän arvo
enumValue Monivalintalisäkentän arvo
decimalValue Numeerisen lisäkentän arvo

Kassa

Kassarekisterit

Pyyntö palauttaa listan kassarekisteri-objekteja.


[
  {
    "guid": "389a229d-cc16-4909-a53e-616e210e111b",
    "locationGuid": "52b2556d-cede-404f-a2c8-57047bb03123",
    "name": "Kassa 1"
  }
]

HTTP Request

GET https://slotti.fi/api/v1/pos/cashregisters

Kenttä Selite
guid Kassarekisterin tunniste
locationGuid Kassarekisterin toimipisteen tunniste
name Kassarekisterin nimi

Uusi myynti

Pyyntö, jolla myynnin saa lähetettyä Slotti kassan kassarekisteriin.


{
  "cashRegisterGuid": "17e6a08b-9045-41f7-b56e-0d15c0f9f602",
  "invoice": {
    "created": "2017-01-25T11:22:35.647Z",
    "customer": {
      "firstName": "Testi",
      "lastName": "Asiakas",
      "guid": "75147581-f65c-4f1b-9ec4-075f97487bb2",
      "language": "fi"
    },
    "items": [
      {
        "price": 40,
        "description": "Foam Roller",
        "quantity": 2,
        "taxPercentage": 24,
        "itemType": "product",
        "serviceGuid": null,
        "productGuid": "690d2611-933a-4138-9678-c257be7ecb7a",
        "relatedItemGuids": []
      },
      {
        "price": 79,
        "description": "Valmennus",
        "quantity": 1,
        "taxPercentage": 24,
        "itemType": "service",
        "serviceGuid": null,
        "productGuid": null,
        "relatedItemGuids": []
      }
    ]
  }
}

Slotti kassaan voi lähettää myyntiluonnoksen alla olevalla pyynnöllä. Luonnos välitetään avoinna olevaan kassaan, joka avaa käyttäjälle ikkunan myynnin tuontia varten.

HTTP Request

POST https://slotti.fi/api/v1/pos/sales/drafts/

Tallennettu myyntiluonnos palautuu pyynnön vastauksena.

Kenttä Selite
cashRegisterGuid Sen kassarekisterin tunnus, jolle myyntiluonnos lähetetään. Pakollinen, mikäli tilillä on useampi kuin yksi kassa.
invoice (pakollinen) Lähetettävä myynti
→ created (pakollinen) Myynnin luontiajankohta
→ customer Asiakas
→ items (pakollinen) Lista laskurivejä myynnille, ks. laskurivi-objekti alla.
Laskurivi-objekti
Kenttä Selite
price (pakollinen) laskurivin yksikköhinta, EUR, esim. 38.95
description (pakollinen) laskurivin selite
quantity (pakollinen) laskurivin kappalemäärä
taxPercentage (pakollinen) laskurivin ALV-veroprosentti
itemType (pakollinen) laskurivin tyyppi: product, service, invoiceItemDiscount, invoiceTotalDiscount.
serviceGuid Slotti-palvelun tunnus, johon laskurivi liittyy
productGuid Slotti-tuotteen tunnus, johon laskurivi liittyy
relatedItemGuids Kohderivien tunnukset, kun rivi liittyy muihin saman myynnin laskuriveihin.

Mikäli rivin tyyppi on invoiceItemDiscount, relatedItemGuids-kentän täytyy sisältää alennuksen kohderivin tunnus.

Webhookit

Yleisesti webhookeista

Webhookien avulla Slotista voi tilata tapahtumapohjaisia huomautuksia erityyppisistä tapahtumista.

Joissain tilanteissa Webhook-tapahtuma saatetaan laukaista useamman kuin yhden kerran, joten webhookin vastaanottajan tulisi kohdella tapahtumia idempotentteina, esimerkiksi kirjaamalla tapahtuman tunniste ja jättämällä jo käsitellyt tapahtumat huomiotta.

Webhook-tapahtuman tunnistaminen

Webhookin tunnistetiedot löytyvät header-arvoista. Payload on puolestaan JSON-muotoinen objekti.

Header Selite
X-Slotti-Event Webhookin typpi
X-Slotti-Shot-ID Webhook-tapahtuman tunniste

Autentikointi ja allekirjoitus

Tarvittaessa webhookkeihin on mahdollista lisätä HTTP Basic Auth ja/tai HMAC SHA256 digest. Basic Auth lisätään vain HTTPS-protokollaa käytettäessä. Allekirjoitus löytyy X-Slotti-Digest header-arvosta ja sisältää secret-kentän arvolla lasketun pyynnön payloadin HMAC SHA256 hashin.

Webhookin luonti

Esimerkki-Webhook

{
  "deliveryUrl": "http://192.168.2.108:3000/slotti_webhook/",
  "topics": ["booking.created", "booking.modified"],
  "secret": "salaisuus",
  "authUser": "xyz123-qwerty343",
  "authPassword": null
}

HTTP Request

POST https://slotti.fi/api/v1/webhooks/

Kenttä Selite
deliveryUrl Mihin osoitteeseen webhook toimitetaan
topics Lista webhook-tyyppejä, joista webhookit halutaan. Myös *-wildcard kaikkien tapahtumien tilaamiseen on mahdollinen.
secret HMAC SHA256 digestin laskentaan käytettävä salaisuus
authUser Basic authiin käytettävä käyttäjänimi
authPassword Basic authiin käytettävä salasana

Vastaus

Onnistunut pyyntö palauttaa luodun webhookin uniikin tunnisteen.

Webhookien listaus

HTTP Request

GET https://slotti.fi/api/v1/webhooks

Pyyntö palauttaa listan Webhook-objekteja.

Webhookin poisto

DELETE https://slotti.fi/api/v1/webhooks/{guid}

guid - Webhookin uniikki tunniste.

Webhook tyypit

Webhook-tyyppi Selite
booking.created Varaus luotu. Payloadina Varaus-objekti
booking.modified Varaus muuttunut. Payloadina Varaus-objekti.
booking.deleted Varaus poistettu. Payloadina varauksen tunniste (guid).
class.signup Tuntivaraukselle on lisätty uusi osallistuminen. Payload: CustomerLink-objekti.
class.signup_modified Tuntivarauksen osallistuminen on muuttunut. Payload: CustomerLink-objekti.
class.signup_cancelled Tuntivarauksen osallistuminen on peruttu. Payload: CustomerLink-objekti.
pos.sale.created Uusi kassamyynti. Payloadina myyntitapahtuma.