Rajapinta - Data-api

Data-api

Data-api rajapinnan avulla toinen ohjelma pääsee lukemaan ja kirjoittamaan palveluun kirjoitettua tietoa.

Rajapintayhteyden avaaminen

Rajapintayhteys tulee avata ennen käyttöä.

Rajapinta sisältää seuraavat operaatiot: Add, Update, List, Delete, DeletedList,Get, Search, Dictionary/Fields.

Kun operaatiota kutsutaan täytyy määrittää tietolähde, johon operaatio kohdistetaan. Esimerkiksi Add - operaatio kohdistetaan tietolähteeseen company kun halutaan lisätä yritys yritysrekisteriin.

Add

Add-operaatiolla lisätään tietoa palveluun.

 

Tässä esimerkissä lisätään henkilö kontaktirekisteriin.

https://app.helppocrm.fi/LoihdinApp/data-api/v1/add?apicode=adensydemo&password=api2018&source=contactperson&data={

  "firstname": "Erkki2",

  "lastname": "Esimerkki",

  "company": "192228",

  "jobtitle": "Sihteeri",

  "phonenumber": "09B3583493493",

  "mobilephone": "09B3583493493",

  "email": "Erkki@uusioy.fi"

}

 

Parametrit:

 

Source:                               Tietolähde, johon rivi lisätään

data:                                   JSON – muotoiltu tietosisältö, jossa uuden rivin tiedot.

 

Vastausviesti:

 

Sisältää seuraavat tiedot:

Success:                             tieto siitä, onko operaatio onnistunut

Rowid:                                uuden rivin tunniste

 

{"rowid":344160,"success":true}

Update

https://app.helppocrm.fi/LoihdinApp/data-api/v1/update?apicode=jsonapi2018&password=1&rowid=290314&source=contactperson&data={

  "firstname": "Erkki",

  "lastname": "Esimerkki",

  "jobtitle": "Toiminnanjohtaja",

  "phonenumber": "\u002B358405512345",

  "mobilephone": "\u002B358405512345",

  "email": "erkki@sininauha.fi"

}

 

Parametrit:

Source:                               Tietolähde, johon päivitys kohdistuu

data:                                    JSON – muotoiltu tietosisältö, jossa uuden rivin tiedot.

rowid:                                 Rivin tunniste

 

Vastausviesti:

Sisältää seuraavat tiedot:

 

Success:                              tieto siitä, onko operaatio onnistunut

Rowid:                                päivitetyn rivin id (pysyy samana)

 

 

response {"rowid":290314,"success":true}

Delete

https://app.helppocrm.fi/LoihdinApp/data-api/v1/delete?apicode=jsonapi2018&password=1&rowid=343620&source=contactperson

 

Parametrit:

Source:                               Tietolähde, johon päivitys kohdistuu

rowid:                                 Rivin tunniste

 

Vastausviesti:

Sisältää seuraavat tiedot:

 

Success:                              tieto siitä, onko operaatio onnistunut

Rowid:                                poistetun rivin id (pysyy samana).

 

 

{"rowid":343620,"success":true}

List

Tässä esimerkissä haetaan tietoja kontaktirekisteristä.

 

https://app.helppocrm.fi/LoihdinApp/data-api/v1/list?apicode=jsonapi2018&password=1&source=contactperson&order=editeddate&limit=1&returnfields=firstname,lastname,company&lastsynced=2018-09-09 00:00:00

 

Parametrit:

Source:                               Tietolähde, josta tietoja haetaan

Order:                                 Paluuaineiston jäjestys

Limit:                                   Maksimi palautettavien rivien määrä

Returnfields:                      Palautettavat kentät.  Käytä All, jos haluat palauttaa kaikki kentät.

LastSynced:                        Aikaleima. Palautetaan ne rivit, joita on muokattu tai lisätty tämän jälkeen.

 

HUOM:

Maksimimäärä palautettavia rivejä on tällä hetkellä 1000. Suosittelemme käyttämään tätä operaatiota silloin kun tietoja synkronoidaan kahden ohjelma välillä. Muussa tapauksessa on suositeltavaa käyttää search-operaatiota.

 

Vastausviesti:

Jokainen vastausviesti sisältää seuraavat kentät

 

Title:                                     Rivin otsikko

Versionnr:                           Rivin versionumero, joka kasvaa kun riviä päivitetään

Createdby:                          Rivin lisääjän käyttäjän ID

CreatedDate:                      Rivin lisäys pvm

Allowed-Operations:         Kun käytetään käyttäjäkohtaista tunnistautumista, palauttaa tiedot siitä mihin toimintoihin tällä tunnuksella on oikeus.

EditedBy:                            Viimeisimmän muokkauksen tehneen käyttäjän tunnus. Jos muokkaus tulee Extranetin kautta                                                           tunnus viittaa asiakkaan henkilöön, jolle on perustettu käyttäjätunnus.

EditedDate:                        Viimeisimmän muokkauksen pvm

 

ReturnFields:                     Rivin tiedot. Tietosisältö riippuu valitusta tietolähteestä.

 

[  

  {  

    "title":"Mikko Salla",

    "versionnr":28,

    "createdby":-1,

    "createddate":2009-12    -09,

    "allowed-operations":"list,view,add,remove,edit,viewhistory",

    "editedby":45,

    "editeddate":2018-10    -09,

    "rowid":58,

    "fields":{  

      "banphonemarketing":false,

      "segments":,

      "lastname":"Salla",

      "extranetaccesstoorders":false,

      "isextranetuser":false,

      "needmanualupdate":false,

      "mobilephone":"",

      "jobtitle":"As3232",

      "contactclass":{  

        "title":"",

        "rowid":""

      },

      "defaultforcompany":{  

        "title":"",

        "rowid":""

      },

      "fullcontactsearchsuccess":false,

      "extranetaccesstoquotes":false,

      "unansweredcallcount":0,

      "customernr":"3",

      "companylinks":,

      "mailchimpemail":"mikko.salla@jarr.fi",

      "phonenumber":"",

      "fax":"",

      "banemailmarketing":false,

      "allowmarketing":false,

      "fullcontactsearchdone":false,

      "extranetaccesstocontactpersons":false,

      "callliststatus":{  

        "text":"Kontaktoimaton",

        "listid":"0"

      },

      "firstname":"Mikko",

      "privatecustomer":false,

      "extranetaccesstoaddress":false,

      "isextranetadmin":false,

      "extranetaccesstoinvoices":false,

      "privatecustomerstatus":{  

        "text":"Ei asiakashistoriaa",

        "listid":"0"

      },

      "answeredcallcounttotal":0,

      "email":"mikko.salla@jarr.fi",

      "bansmsmarketing":false,

      "company":{  

        "title":"Jarr Oy",

        "rowid":46

      },

      "owner":{  

        "title":"Tero Nieminen",

        "rowid":321

      },

      "unansweredcallcounttotal":0

    }

  }

]

 

Vinkki toteutukseen:

1. Tämä operaatio voi palauttaa samoja rivejä kuin aikaisempi kutsu. Rajapinnan toteuttajana sinun tulee huomioida tämä mikäli tallennat tietoa toiseen järjestestelmään.

2. Kun käytät List-operaatiota ota, seuraavat suosittelemme että otat talteen viimeisimmän palautetun rivin editeddate - ajankohdan. Käytä sitä parameterina kun seuraavan kerran käytät tätä operaatiota samasta tietolähteestä.

3. Tämä metodi palauttaa vain tietyn ajankohdan jälkeen muokatut ja lisätyt rivit. Rajapinnan käyttäjän tulee käyttää ListDeleted-operaatiota tunnistamaan poistetut rivit.

,

      "lastname":"Salla",

      "extranetaccesstoorders":false,

      "isextranetuser":false,

      "needmanualupdate":false,

      "mobilephone":"",

      "jobtitle":"As3232",

      "contactclass":{  

        "title":"",

        "rowid":""

      },

      "defaultforcompany":{  

        "title":"",

        "rowid":""

      },

      "fullcontactsearchsuccess":false,

      "extranetaccesstoquotes":false,

      "unansweredcallcount":0,

      "customernr":"3",

      "companylinks":,

      "mailchimpemail":"mikko.salla@jarr.fi",

      "phonenumber":"",

      "fax":"",

      "banemailmarketing":false,

      "allowmarketing":false,

      "fullcontactsearchdone":false,

      "extranetaccesstocontactpersons":false,

      "callliststatus":{  

        "text":"Kontaktoimaton",

        "listid":"0"

      },

      "firstname":"Mikko",

      "privatecustomer":false,

      "extranetaccesstoaddress":false,

      "isextranetadmin":false,

      "extranetaccesstoinvoices":false,

      "privatecustomerstatus":{  

        "text":"Ei asiakashistoriaa",

        "listid":"0"

      },

      "answeredcallcounttotal":0,

      "email":"mikko.salla@jarr.fi",

      "bansmsmarketing":false,

      "company":{  

        "title":"Jarr Oy",

        "rowid":46

      },

      "owner":{  

        "title":"Tero Nieminen",

        "rowid":321

      },

      "unansweredcallcounttotal":0

    }

  }

]

 

Vinkki toteutukseen:

1. Tämä operaatio voi palauttaa samoja rivejä kuin aikaisempi kutsu. Rajapinnan toteuttajana sinun tulee huomioida tämä mikäli tallennat tietoa toiseen järjestestelmään.

2. Kun käytät List-operaatiota ota, seuraavat suosittelemme että otat talteen viimeisimmän palautetun rivin editeddate - ajankohdan. Käytä sitä parameterina kun seuraavan kerran käytät tätä operaatiota samasta tietolähteestä.

3. Tämä metodi palauttaa vain tietyn ajankohdan jälkeen muokatut ja lisätyt rivit. Rajapinnan käyttäjän tulee käyttää ListDeleted-operaatiota tunnistamaan poistetut rivit.

]

ListDeleted

https://app.helppocrm.fi/LoihdinApp/ data-api/v1/deletedlist?apicode=jsonapi2018&password=1&lastsynced=2018-10-10 00:00:00

 

Parametrit:

LastSynced:                        Aikaleima. Palautetaan ne rivit,  jotka on poistettu aikaleiman jälkeen.

 

Vastausviesti:

Jokainen vastausviesti sisältää seuraavat kentät:

 

Dataclass:                           Tietolähde, johon poisto on kohdistettu

Rowid:                                Poistetun rivin tunniste.

 

 

[{"dataclass":"contactperson","rowid":296568}]

]

Get

https://app.helppocrm.fi/LoihdinApp/data-api/get?apicode=jsonapi2018&password=1&rowid=290314&dataclass=contactperson

 

Parametrit

Rowid:                                Rivin tunniste.

dataclass:                           Tietolähde, josta tiedot haetaan.

 

Vastausviesti:

Paluu viesti kuten list – operaatiossa.

Search

Esimerkki: tunnisteiden haku

 

https://app.helppocrm.fi/LoihdinApp/data-api/v1/search?apicode=jsonapi2018&password=1&source=contactperson&query=firstname:mikko

 

Esimerkki: tietojen listaaminen ja sivutus

 

https://app.helppocrm.fi/LoihdinApp/data-api/v1/search?apicode=jsonapi2018&password=1&source=contactperson&query=firstname:mikko&returnfields=firstname, lastname,jobtitle&pagestart=0&pagesize=10

 

Parametrit:

 

Source                               

Tietolähde, josta tiedot haetaan.

 

Query:                               

 hakuehto, esim:

 firstname:mikko (kaikki, joiden etunimi on mikko)

 firstname*mik (kaikki, joiden etunimessä on teksti mik)

 

Muut operaattorit:

> suurempi kuin

< pienempi kuin

 

Returnfields                        

Valinnainen. Määritä kentät, jotka palautetaan tulosjoukossa

 

Pagestart    ja pagesize - parametrit         

Valinnainen. Pagestart ja pagesize  - parametrit ovat valinnaisia. Niiden avulla voit parantaa vasteaikaa palauttamalla pienemmän tulosjoukon. Esim.  Pagestart=0&pagesize=10 palauttaa tulokset 0-10.    Näitä ei voi käyttää erikseen vaan on joko annettava molemmat parametrit tai ei kumpaakaan.                       

 

Vastausviesti:

Listaus ROWID-tunnisteista. (jos returnfields-parametria ei ole käytetty)

 

JSON - muotoiltu listaus sisältäen returnfields - kyselyssä määritellyt kentät.

Dictionary / Fields

https://app.helppocrm.fi/LoihdinApp/data-api/v1/dictionary/fields?apicode=jsonapi2018&password=1&source=contactperson

 

Parametrit:

 

Source                                Tietolähde, jonka kentät listataan

 

 

Paluuviesti (Lyhennetty):

 

Huom: Asiakaskohtaiset lisäkentät näkyvät paluu viestissä _ext – alkuisina.

 

 

{  

  "id":"contactperson",

  "description":"kontakti",

  "fields":[  

        {  

      "id":"contactclass",

      "desription":"kontaktiluokka",

      "type":"object"

    },    {  

      "id":"firstname",

      "desription":"etunimi",

      "type":"text"

    },

    {  

      "id":"lastname",

      "desription":"sukunimi",

      "type":"text"

    },

    {  

      "id":"company",

      "desription":"yritys",

      "type":"object"

    },

        {  

      "id":"mobilephone",

      "desription":"matkapuhelin",

      "type":"text"

    },