Kontakto - yrityshaku ja yritystietorajapinta

Kontakto API / Rajapinta

Kontakton API (application programming interface) tarjoaa koneluettavassa (JSON) muodossa yritystiedot sähköisesti esimerkiksi käytössä olevaan ERP-järjestelmään.

Yritystietorajapinnan käyttöön tarvitaan API-avain, joka toimitetaan tilaushetkellä tilaajan sähköpostiin.

Tämän jälkeen rajapintaa voidaan käyttää tilattujen käyttöoikeuksien puitteissa.

Huomattavaa on, että rajapintaa kehitetään jatkuvasti. Tarkoituksena on, että olemassaolevia kenttiä ei muuteta, mutta uusia lisätään. Mikäli ns. breaking change -tyyppisiä muutoksia tulee, tullaan ne julkaisemaan rajapinnan toisena versiona. Informoimme rajapintamuutoksista tilaajille sähköpostitse.


Autentikaatio

Kun tilaat rajapinnan käyttöoikeuden, saat välittömästi sähköpostiin salaisen avaimesi. Tällä avaimella pystyt muodostamaan varsinaisia käyttöavaimia (tokeneita).

Käytämme esimerkeissä salaisena avaimena kontaktoSecret ja tokenina kontaktoToken.

Voimme muodostaa tokenin yksinkertaisella POST-kutsulla, tässä curl -esimerkki:

curl -X POST https://api.kontakto.fi/token -H "Authorization: kontaktoSecret" -H "Content-Type: application/json" -d '{"id": "1", "expires": 10000}'

Esimerkissä siis tehdään kutsu endpointiin /token. HTTP Headereihin asetetaan kontaktoSecret.
Dataksi asetetaan JSONina kentät

  • id, jolla pystytään määrittelemään avaimen tunnistetieto. Tunnistetiedon käyttö on raportoitavissa jälkikäteen.
  • expires, jolla määritellään tokenin vanhentumisaika sekunteina. Vanhentumisajan tulee olla alle kaksi viikkoa. Voit luoda myös ikuisesti käytössä olevia käyttöavaimia jättämällä koko expires -datan kutsusta pois.

Vastauksena kyselyyn tulee access_token:
{"access_token":"kontaktoToken"}

Tämän jälkeen tokenia voi käyttää kutsussa määritellyn ajan. Kun token vanhenee tai vaihtoehtoisesti ei muuten toimi, palautuu HTTP Status 401.

Token asetetaan HTTP Headeriin muodossa Authorization: Bearer kontaktoToken.

Käyttöavaimen muodostaminen web-lomakkeella

Voit käyttää käyttöavaimien muodostamiseen myös sivulla https://kontakto.fi/token olevaa lomaketta.

Yritystiedot

Yritystietojen rajapinta koostuu tällä hetkellä kahdesta endpointista:

  • /search/[hakusana] - Palauttaa hakutulokset (10 kpl) yrityksistä, jotka täsmäävät hakusanaan joko yrityksen nimen tai y-tunnuksen perusteella, voidaan käyttää esim autocomplete -tyyppisissä ratkaisuissa

  • /companies/[businessID] - Palauttaa haetun yksittäisen yrityksen (Y-tunnus) tarkat/kaikki tiedot.

Rajapinnan mahdollisia käyttötarkoituksia:

  • Verkkosivusto, joka tarjoaa yrityksen ajantasaiset tiedot käyttäjille. Etusivulla /search/ -endpointiin perustuva autocomplete -haku ja /companies/ -endpointiin perustuva yritystietosivu. Esimerkkinä https://kontakto.fi

  • Verkkosivusto, jossa tarvitaan yrityksien tietoja: kysytään käyttäjältä yrityksen nimi, haetaan sen perusteella yrityksen tiedot ja täytetään yrityksen tiedot valmiiksi ja parannetaan näin asiakkaan käyttökokemusta. Samalla voidaan tarkistaa yrityksen kuuluminen tarpeellisiin rekistereihin (ALV-rekisteri, ennakkoperintärekisteri).

  • Laskutusohjelmisto / toiminnanohjausjärjestelmä, jossa halutaan perustaa uusi asiakkuus tai hakea olemassaolevan asiakkaan tämänhetkiset tiedot. Palvelusta saatavilla tiedoilla voidaan myös täyttää tai päivittää verkkolaskuosoitetiedot oikeiksi.

API-kuvaus lyhyesti

Pääpiirteissään rajapinta toimii seuraavasti:
  • API vastaa osoitteessa https://api.kontakto.fi/
  • Autentikaatio toimii token-pohjaisesti, tokenin muodostaminen kerrottu ylhäällä
  • Älä julkaise mihinkään kontaktoSecretiä. Generoi aina kontaktoToken käyttäjien käyttöön.

Esimerkiksi Y-tunnuksen 1234567-8 tiedot saat vastauksena curl-kyselyllä:
curl -H "Authorization: Bearer kontaktoToken" https://api.kontakto.fi/companies/1234567-8
Esimerkkivastaus
{
  "businessId": "1234567-8",
  "auxiliaryNames": ["Kauppaliike Yritys", "Yritysesimerkkikeskus"],
  "businessName": "Oy Yritys Ab",
  "kontaktoRating": {
    "color": "green",
    "reason": "Yritys on aktiivinen, ennakkoperintärekisterissä ja ALV-rekisterissä"
  },
  "businessStatus": {
    "asOf": "1990-01-15",
    "description": "Aktiivinen",
    "history": []
  },
  "domicile": {
    "city": "Närpiö",
    "code": "545",
    "country": "FI"
  },
  "industry": {
    "asOf": "1990-01-15",
    "description": "Toimiala tuntematon",
    "tol2008code": "00000"
  },
  "languages": ["fi"],
  "legalForm": {
    "asOf": "1990-01-15",
    "description": "Osakeyhtiö",
    "code": "16"
  },
  "mailAddress": {
    "careOf": "",
    "streetAddress": "Postiosoite 1",
    "postCode": "0000",
    "postOffice": "KAUPUNKI",
    "country": "FI"
  },
  "visitingAddress": {
    "careOf": "",
    "streetAddress": "Käyntiosoitekatu 1",
    "postCode": "00000",
    "postOffice": "KAUPUNKI",
    "country": "FI"
  },
  "modifiedAt": "2019-04-01T13:57:01.111Z",
  "phoneNumber": {
    "landline": "01234567",
    "mobile": "04412345678",
    "fax": "0141234567"
  },
  "vatNumber": "FI12345678",
  "website": "www.example.com",
  "officialLanguage": "fi",
  "register": {
    "preliminaryTaxWithholdingRegister": {
      "asOf": "1990-01-15",
      "description": "Ennakkoperintärekisteri",
      "status": true
    },
    "vatRegister": {
      "vatLiabilities": [
        {
          "asOf": "1990-01-15",
          "code": "80",
          "description": "Liiketoiminnasta arvonlisäverovelvollinen",
          "status": true
        },
        {
          "asOf": "1990-01-15",
          "code": "82",
          "description": "Kiinteistön käyttöoikeuden luovuttamisesta",
          "status": true
        }
      ],
      "status": true
    },
    "taxAdministrationRegister": {
      "asOf": "1990-01-15",
      "description": "Verohallinnon perustiedot",
      "status": true
    },
    "employerRegister": {
      "asOf": "1990-01-15",
      "description": "Työnantajarekisteri",
      "status": true
    },
    "tradeRegister": {
      "asOf": "1990-01-15",
      "description": "Kaupparekisteri",
      "status": true
    }
  },
  "eInvoice": {
    "finvoice": {
      "receiving": [
        {
          "name": "Oy Yritys Ab",
          "address": "0037012345678",
          "operatorCode": "003721291126",
          "operator": "Maventa",
          "ovt": "0037012345678"
        }
      ],
      "sending": [
        {
          "name": "Oy Yritys Ab",
          "operatorCode": "003721291126",
          "operator": "Maventa",
          "ovt": "0037012345678"
        },
        {
          "name": "Oy Yritys Ab",
          "operatorCode": "NDEAFIHH",
          "operator": "Nordea",
          "ovt": "0037012345678"
        }
      ]
    }
  }
}
Yleinen käyttömalli
Yleinen käyttömalli voisi mennä seuraavasti
  1. Haetaan yritystä nimellä kontakto, tekemällä GET osoitteeseen https://api.kontakto.fi​/search/kontakto
  2. Näytetään käyttäjälle koko ajan päivittyvä lista hakutuloksista (autocomplete/typeahead) jossa näytetään myös kontaktoRating.color
  3. Käyttäjä valitsee oikean yrityksen
  4. Haetaan valinnan mukaisen yrityksen kaikki tiedot tekemällä GET osoitteeseen https://api.kontakto.fi​/companies/1234567-8
  5. Tämän jälkeen yrityksen perustiedot voidaan kirjoittaa käytettävän järjestelmän soveltuviin kenttiin tai näyttää käyttäjälle haetut yrityksen tiedot ja antaa käyttäjälle mahdollisuus valita päivitettävät tiedot
Kenttäkuvaukset

Alla yksinkertaistetut kuvaukset kaikista kentistä:

businessId (String)

Y-tunnus, suomalaisessa muodossa. Muotoa 0000000-1.

auxiliaryNames (Array of Strings)

Luettelo yrityksen rekisteröidyistä aputoiminimistä

businessName (String)

Yrityksen virallinen nimi

kontaktoRating (String)

Yrityksen tila rekisterimerkintöjen näkökulmasta

kontaktoRating.color (String)

Yrityksen tila nelitasoisesti: green / yellow / red / black. Green: Todennäköisesti täysin toiminnassa oleva yritys. Yellow: Mahdollisia riskitekijöitä rekisterimerkinnöissä. Red: Liiketoimintatila yhtiössä negatiivinen. Black: Yrityksellä ei toimintaa.

kontaktoRating.reason (String)

Yrityksen tilan selvennys

businessStatus (Object)

Sisältää tietoja yrityksen liiketoiminnallisesta tilasta

businessStatus​.asOf (String)

Yrityksen tilan viimeisimmän muutoksen päivämäärä​. Muodossa `yyyy-mm-dd`​.

businessStatus​.description (String)

Liiketoiminnallisen tilan kuvaus, esimerkiksi `Aktiivinen` / `Toiminta lakannut`

businessStatus​.isActive (String)

Onko yrityksen liiketoiminta aktiivisessa tilassa

businessStatus​.history (Array)

Liiketoiminnallisen tilan historiatiedot

deliveryAddress (Object)

Yrityksen toimitusosoite

deliveryAddress​.careOf (String)

Yrityksen toimitusosoitteen c/o -tieto

deliveryAddress​.streetAddress (String)

Yrityksen toimitusosoite - katuosoite ja numero

deliveryAddress​.postCode (String)

Yrityksen toimitusosoitteen postinumero

deliveryAddress​.postOffice (String)

Yrityksen toimitusosoitteen postitoimipaikka

deliveryAddress​.country (String)

Yrityksen toimitusosoitteen maa

domicile (Object)

Yrityksen kotipaikkatiedot

domicile​.city (String)

Yrityksen kotipaikka, esimerkiksi `Kuopio`

domicile​.code (String)

Yrityksen kotipaikan tunnus, esimerkiksi Kuopion tapauksessa `297`

domicile​.country (String)

Yrityksen kotipaikan maa

email (String)

Yrityksen ensisijainen sähköpostiosoite

faxNumber (String)

Yrityksen faksinumero

industry (Object)

Yrityksen toimialatiedot

industry​.asOf (String)

Toimialatiedon viimeisimmän muutoksen päivämäärä​. Muodossa `yyyy-mm-dd`​.

industry​.description (String)

Toimialatiedon kuvaus

industry​.tol2008code (String)

TOL2008-toimialaluettelon mukainen toimialakoodi

invoiceAddress (Object)

Yrityksen laskutusosoite

invoiceAddress​.careOf (String)

Yrityksen laskutusosoitteen c/o -tieto

invoiceAddress​.streetAddress (String)

Yrityksen laskutusosoite - katuosoite ja numero

invoiceAddress​.postCode (String)

Yrityksen laskutusosoitteen postinumero

invoiceAddress​.postOffice (String)

Yrityksen laskutusosoitteen postitoimipaikka

invoiceAddress​.country (String)

Yrityksen laskutusosoitteen maa

languages (Array of Strings)

Yrityksen viralliset kielet

legalForm (Object)

Tiedot yrityksen juridisesta muodosta

legalForm​.asOf (String)

Yritysmuodon päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

legalForm​.description (String)

Yritysmuodon kuvaus, esimerkiksi `Osakeyhtiö`

legalForm​.short (String)

Yritysmuodon tunnus, esimerkiksi Osakeyhtiön tapauksessa `16`​.

mailAddress (Object)

Yrityksen postiosoite

mailAddress​.careOf (String)

Yrityksen postiosoitteen c/o -tieto

mailAddress​.streetAddress (String)

Yrityksen postiosoite - katuosoite ja numero

mailAddress​.postCode (String)

Yrityksen postiosoitteen postinumero

mailAddress​.postOffice (String)

Yrityksen postiosoitteen postitoimipaikka

mailAddress​.country (String)

Yrityksen postiosoitteen maa

officialLanguage (String)

Yrityksen virallinen kieli

phoneNumber (Object)

Yrityksen käytössä olevat puhelinnumerot

phoneNumber​.landline (String)

Yrityksen käytössä oleva lankapuhelin

phoneNumber​.mobile (String)

Yrityksen käytössä oleva matkapuhelin

url (Object)

Yrityksen käytössä olevat verkkosivustot (web, muut mahdolliset sosiaalisen median urlit)

url​.web (String)

Yrityksen www-osoite

visitingAddress (Object)

Yrityksen käyntiosoite

visitingAddress​.careOf (String)

Yrityksen käyntiosoitteen c/o -tieto

visitingAddress​.streetAddress (String)

Yrityksen käyntiosoite - katuosoite ja numero

visitingAddress​.postCode (String)

Yrityksen käyntiosoitteen postinumero

visitingAddress​.postOffice (String)

Yrityksen käyntiosoitteen postitoimipaikka

visitingAddress​.country (String)

Yrityksen käyntiosoitteen maa

register (Array of Objects)

Yrityksen viranomaisrekisteritiedot

register​.preliminaryTaxWithholdingRegister (Object)

Yrityksen ennakkoperintärekisteritiedot

register​.preliminaryTaxWithholdingRegister​.status (Boolean)

Tieto siitä, onko yritys ennakkoperintärekisterissä tällä hetkellä vai ei

register​.preliminaryTaxWithholdingRegister​.asOf (String)

Ennakkoperintärekisteröinnin päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

register​.vatRegister (Object)

Yrityksen arvonlisäverorekisteritiedot

register​.vatRegister​.status (Boolean)

Tieto siitä, onko yritys jossain arvonlisäverorekisterissä tällä hetkellä vai ei

register​.vatRegister​.vatLiabilities (Array of Objects)

Tieto siitä, mistä toiminnasta yritys on arvonlisäverovelvollinen

register​.vatRegister​.vatLiabilities[n]​.asOf (String)

Arvonlisäverorekisteröinnin päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

register​.vatRegister​.vatLiabilities[n]​.liability (String)

Arvonlisäverorekisteröinnin rekisterikoodin kuvaus

register​.vatRegister​.vatLiabilities[n]​.code (String)

Arvonlisäverorekisteröinnin rekisterikoodi

register​.taxAdministrationRegister (Object)

Yrityksen verohallinnon perustietojen rekisteröinti

register​.taxAdministrationRegister​.status (Boolean)

Tieto siitä, onko yritys rekisteröitynyt verohallintoon tällä hetkellä vai ei

register​.taxAdministrationRegister​.asOf (String)

Verohallintorekisteröinnin päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

register​.employerRegister (Object)

Yrityksen työnantajarekisteritiedot

register​.employerRegister​.status (Boolean)

Tieto siitä, onko yritys työnantajarekisterissä tällä hetkellä vai ei

register​.employerRegister​.asOf (String)

Työnantajarekisteröinnin päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

register​.tradeRegister (Object)

Yrityksen kaupparekisteritiedot

register​.tradeRegister​.status (Boolean)

Tieto siitä, onko yritys kaupparekisterissä tällä hetkellä vai ei

register​.tradeRegister​.asOf (String)

Kaupparekisterin rekisteröinnin päivämäärä, voimassa tästä hetkestä nykyhetkeen​. Muodossa `yyyy-mm-dd`​.

eInvoice (Object)

Sisältää kaikki verkkolaskutukseen liittyvät tiedot

eInvoice​.finvoice (Object)

Sisältää kaikki Finvoice-verkkolaskutukseen liittyvät tiedot

eInvoice​.finvoice​.receiving (Array)

Luettelo osoitteista, joissa yritys vastaanottaa Finvoice-verkkolaskuja​. Mikäli luettelossa ei ole osoitteita, ei yritys todennäköisesti vastaanota verkkolaskuja​.

eInvoice​.finvoice​.receiving[n]​.name (String)

Verkkolaskun vastaanottonimi esimerkiksi toimipaikka / yksikkö

eInvoice​.finvoice​.receiving[n]​.address (String)

Verkkolaskuosoite

eInvoice​.finvoice​.receiving[n]​.operatorCode (String)

Verkkolaskuoperaattorin tunnus

eInvoice​.finvoice​.receiving[n]​.operator (String)

Verkkolaskuoperaattorin nimi / kuvaus

eInvoice​.finvoice​.receiving[n]​.ovt (String)

Verkkolaskun vastaanottajan OVT-tunnus, yleensä muotoa 0037+Y-tunnus+mahdollinen tarkiste

eInvoice​.finvoice​.sending (Array)

Luettelo osoitteista/operaattoreista, joiden kautta yritys lähettää ulospäin verkkolaskuja​. Mikäli luettelossa ei ole osoitteita, ei yritys todennäköisesti lähetä verkkolaskuja​.

eInvoice​.finvoice​.sending[n]​.name (String)

Verkkolaskun lähettäjänimi esimerkiksi toimipaikka / yksikkö

eInvoice​.finvoice​.sending[n]​.operatorCode (String)

Lähettävän verkkolaskuoperaattorin tunnus

eInvoice​.finvoice​.sending[n]​.operator (String)

Lähettävän verkkolaskuoperaattorin nimi / kuvaus

eInvoice​.finvoice​.sending[n]​.ovt (String)

Verkkolaskun lähettäjän OVT-tunnus yleensä muotoa 0037+Y-tunnus+mahdollinen tarkiste

Copyright © 2020 Kontakto Oy (2831767-5)