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.

Yhden esimerkin mahdollisesta lopputuotteesta näet tässä videossa:

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

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

Kenttäkuvaukset

Alla yksinkertaistetut kuvaukset kaikista kentistä: