Yhteistä kaikille rajapinnan toiminnoille on
- Fennoa API URL on aina sama https://app.fennoa.com/api/
- Enkoodaus UTF-8
- Päivämäärät ovat ANSI–muodossa
- Maakoodit ovat aina ISO 3166-1
- Valuuttakoodit ISO 4217
- Kielikoodit ISO 639-1
- Liitteet ovat aina Base64 -enkoodattuna sanomaan
- Desimaalierottimena tulee käyttää pistettä
- Pakollisia kenttiä ei tule jättää tyhjäksi
- Tyhjiä elementtejä ei tarvitse kirjoittaa sanomaan
- API dokumentaatiossa on kerrottu muoto (FORM DATA tai json), jota kutsussa tulee käyttää sekä pakolliset elementit ja vastaukset.
Ohje rajapintapyynnön hallintaan
- Pyyntöjen vastaanotto ja kapasiteetti: Järjestelmässä on jonopuskuri, johon mahtuu enintään 100 pyyntöä / IP-osoite kerrallaan. Tämä tarkoittaa, että jonossa voi olla korkeintaan 100 pyyntöä odottamassa käsittelyä.
- Pyyntöjen käsittelyvauhti: Jonosta siirtyy pyyntöjä käsittelyyn tasaisella nopeudella, enintään 5 kappaletta sekunnissa. Tämä rajoite varmistaa, ettei järjestelmä ylikuormitu.
- Ylitäyden jonon tilanne: Kun jonopuskuri on täynnä ja siihen tulee uusia pyyntöjä, niitä ei voida ottaa vastaan. Tällöin uudet pyynnöt hylätään ja niistä annetaan virheilmoitus 429 Too Many Requests until the active request count drops below the limit
- Vanhentuneet pyynnöt: Jos jonossa olevia pyyntöjä ei käsitellä, ne katsotaan vanhentuneiksi ja poistetaan automaattisesti. Näistä pyynnöistä palautuu virheilmoitus.
- Käytännön suositus: Parhaan toimivuuden ja virheiden välttämiseksi suositellaan lähettämään enintään 5 pyyntöä sekunnissa ja odottamaan jokaisesta vastaus ennen seuraavan lähettämistä. Näin pyyntöjen käsittely pysyy sujuvana ja virhetilanteet vähenevät.
Rajapinnan vastaukset
200 – OK
400 – Tarkista data. Esim. päivämäärä virheellisessä muodossa tai pakollinen elementti puuttuu
401 – Tunnuksilla ei ole riittäviä oikeuksia tai API avain / käyttäjätunnus on virheellinen. Tarkista tilitoimistolta API käyttäjän oikeudet / tunnukset.
404 – Haku ei tuota tulosta. Esim. hakuun käytettyä ID:tä ei löydy
405 – Tarkista käytetty metodi
429 – Liian monta pyyntöä. Palvelimelle on lähetetty liian monta pyyntöä, liian nopeasti. Aktiivisten pyyntöjen enimmäisraja IP-osoitetta kohti on 100 sekunnissa. Jos tämä raja ylittyy, palvelin palauttaa virheen kaikkiin seuraaviin pyyntöihin, kunnes aktiivisten pyyntöjen määrä laskee rajan alapuolelle.
500 – Server error, kokeile hetken päästä uudelleen
503 – Service unavailable – esim. hallittu versiopäivitys kuukauden ensimmäinen keskiviikko
Virheiden hallinnan tulee tapahtua integroitavassa järjestelmässä, vähintään virheviesteistä tulee ilmoittaa loppukäyttäjälle selkeästi.
Toimintokohtaisia huomioita:
Myyntilaskut (POST/sales_api/add)
- Rajapinnassa luotaville myyntilaskuille on suositeltavaa asettaa oma laskunumerosarjansa Fennoaan (Fennoa > Asetukset > Laskunumerot) Laskunumerosarjan id tulee katsoa käyttöliittymästä. Halutun laskunumerosarjan id annetaan sales_invoice_series_id elementissä.
- Rajapinnan kautta luodut laskut tulevat Fennoassa Luonnoksiin (Myynnit > Luonnokset), josta ne tulee hyväksyä ja lähettää erikseen. Mikäli halutaan automatisoida rajapinnan kautta luotujen laskujen hyväksyntä ja lähetys, voidaan se tehdä rajapinnan kautta. Laskun hyväksyntä POST/sales_api/do/approve/<id> ja lähetys POST /sales_api/do/send
- Myyntilaskun verokoodit ovat:
- 1 = Domestic sales (S) Default
- 2 = EU-sales services (K)
- 3 = EU-sales goods (K)
- 4 = Construction services (AE)
- 5 = Scrap metal sales (AE)
- 6 = Foreign sales, outside of EU (G)
- 7 = Domestic sales VAT-free (Z)
- 8 = Triangulation (K)
- Laskun lähetystapa (delivery_method) on määräävä laskun lähetyskanavaksi, toimitustapojen koodit ovat:
- postal
- manual
- finvoice
- consumerfinvoice
- consumerdirect
- PEPPOL
Fennoa tukee seuraavia verkkolaskuoperaattoreita, sanomalla tulee käyttää verkkolaskuoperaattorin tunnusta:
Tunnus Operaattori
| HELSFIHH | Aktia Pankki Oyj |
| 003723327487 | Apix Messaging Oy |
| BAWCFI22 | Basware Oyj |
| 003703575029 | CGI Suomi Oy |
| 5909000716438 | Comarch |
| CREDIFLOW | Crediflow Ab |
| DABAFIHH | Danske Bank Oyj |
| DNBAFIHX | DNB Bank ASA |
| HANDFIHH | Handelsbanken |
| 885790000000418 | HighJump AS |
| INEXCHANGE | InExchange Factorum AB |
| EXPSYS | Lexmark Expert Systems AB |
| 003721291126 | Maventa |
| 003726044706 | Netbox Finland Oy |
| NDEAFIHH | Nordea |
| 003708599126 | OpenText / Liaison Technologies Oy |
| OKOYFIHH | OP-Pohjola-ryhmä |
| 003710948874 | OpusCapita Group Oy Itella |
| E204503 | OpusCapita Solutions Oy |
| PAGERO | Pagero |
| 003723609900 | Pagero |
| POPFFI22 | Paikallisosuuspankit |
| PALETTE | Palette Software |
| PEPPOL | PEPPOL BIS Billing 3.0 |
| 003710948874 | Posti Messaging Oy |
| 003701150617 | PostNord Strålfors Oy |
| 003714377140 | Ropo Capital Oy / Enfo Zender |
| SBANFIHH | S-Pankki Oy |
| ITELFIHH | Säästöpankit |
| 003703575029 | Telia Finland Oyj |
| 003701011385 | TietoEVRY Oyj |
| 885060259470028 | Tradeshift Ab |
| 003722207029 | Åland Post Ab |
| AABAFI22 | Ålandsbanken |
Ostolaskujen merkinnät ja kirjanpidon tositteet
Ostolaskujen merkintöjen asettamisessa POST/purchases_api/do/set_tags sekä kirjanpidon tositteiden luomisessa POST/accounting_api/add ja kirjanpidon pääkirjan haku GET /accounting_api/get/ledger käyttävät alv-koodeja.
Käytössä olevat alv-koodit saa tarkistettua kutsulla GET /accounting_api/get/vatcodes
Uudet standardi koodit ovat:
”id”: ”63”,
”name”: ”Standard”,
”vatpercent”: ”25.50”,
”type”: ”sales”
”id”: ”58”,
”name”: ”Standard”,
”vatpercent”: ”25.50”,
”type”: ”purchases”