Watch-API

Yleistä

Watch-toiminnallisuus mahdollistaa yrityksen tietojen muutoksien seuraamisen. Järjestelmään rekisteröidään kuuntelijoita, joiden mukaan lähetetään ilmoituksia muuttuneista yrityksistä.

Tunnistautuminen

Kutsu: POST https://auth.fonapi.fi/token/login Headerit: Content-Type: application/x-www-form-urlencoded Body: grant_type=client_credentials&client_id= oma_client_id&client_secret=oma_client_secret

Vastaus:

    {
      "access_token":"8e2da0f9-b32c-1bc8-eedd-7c259c37d51b",
      "token_type":"Bearer",
      "expires_in":"90000",
      "scope":[{"service":"SEARCH_contacts_watch",
      "permission":"READ","orderId":null}],
      "uniqueId":null,
      "clientId":"oma_client_id"
    }

Tämän jälkeen kaikissa kutsuissa Watch-APIn pitää kuljettaa access_token kentässä olevaa arvoa header-tietona:

Authorization: Bearer 8e2da0f9-b32c-1bc8-eedd-7c259c37d51b

Watch-API

Rest API -osoite: https://search.fonapi.fi/

Prosessi

Watch-toiminnallisuus

Rekisteröinti

Voit rekisteröidä kuuntelijan osoitteen, jonne ilmoitukset muuttuneista kontakteista lähetetään. Käytä siihen kutsua:

POST /contactwatch/watchers

{
  "watcherId":"yksiloivatunnus123",
  "callbackUrl":"https://example.org/api/callback"
}

Tämän jälkeen voit rekisteröidä kuunneltuja yrityksiä ja henkilöitä: Sinun on aina annettava myös yrityksen id, mikäli haluat seurata päättäjää id:n avulla.

POST /contactwatch/watch

{
  "watcherId": "yksiloivatunnus123",
  "watchedContacts": [
    {
      "companyId": "1239011",
      "personIds": [
        "1234"
      ]
    },
     {
      "companyId": "8684930"
    }
  ]
}

Kun yrityksen tai päättäjän tietoon tulee muutos, saat seuraavanlaisen viestin rekisteröimääsi rajapinta-osoitteeseen:

{
    "Id": "8684930",
    "watcherId": "yksiloivatunnus123",
    "timestamp": "1456212678",
    "personId" : "6543234567",
    "checksum": "sumhere"
}

Kenttien selitykset

id = Yrityksen ID

watcherId = rekisteröityessä annettu ID

timestamp = epoch-aikaleima

personId = Valinnainen henkilön ID. Mikäli k.o. päivitys on yritykseen, tätä kenttää ei ole.

checksum = sha256 hex-tiiviste kentistä: watcherId+clientId+id+personId+epochtime (clientId on authentikoituessa käytettävä autentikoinnin id)

Loput REST API toiminteista löytyy alla olevasta kuvauksesta.

Virheviestit

HTTP Status koodit

200 Kaikki OK

401 Ei oikeutta palveluun. Avain voi olla vanhentunut.

403 Toiminto ei ole sallittu. Esimerkiksi batch-haku tukee vain maksimissaan 100:lla ID:llä hakemista.

404 Tallennettua kuuntelijaa ei löydy. WatcherId on väärin ja ei löydy. Vaihdoehdoisesti ID:llä ei löydy yritystä.

500 Sisäinen virhe.

Tekninen API-dokumentaatio

 

Konsoli

Tarkoitus

Konsolin avulla voi testata Yhteystieto- ja Palveluhaku-APIen toimintaa rajatusti ja suoraan ilman tunnistautumista.

Käyttäminen

Konsolin käyttäminen on rajoitettu Yhteystieto- ja Palveluhaku-rajapintoihin ja Fonecta-aiheisiin tuloksiin. Konsoli on käytettävissä tableteilla ja niitä suuremmilla laitteilla.

Yhteystieto-API

/v2/contacts/search

Esim. /v2/contacts/search?what=fonecta&where=televisiokatu

/v2/contacts/businessId/{businessId}

Vain business id 17550076 on haettavissa:

/v2/contacts/businessId/17550076

/v2/contacts/autocomplete

esim. /v2/contacts/autocomplete?what=media

Palveluhaku-API

/v2/contacts/boundingBoxSearch

Esim. /v2/contacts/boundingBoxSearch?what=fonecta&pinLatitude=60.20413&pinLongitude=24.92520&topLeftLatitude=60.20459&topLeftLongitude=24.92383& bottomRightLatitude=60.20416&bottomRightLongitude=24.92533

Koordinaattirajauksella ei konsolissa ole vaikutusta

/v2/contacts/lineOfBusinesses

Vain lineOfBusiness A3300C on haettavissa:

/v2/contacts/lineOfBusinesses?lineOfBusinessCode=A3300C

Tarkemmat tiedot rajapinnoista löytyvät kohdasta Tekninen dokumentaatio