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.

Lähetä yksi pyyntö kerrallaan ja odota vastaus ennen seuraavaan pyynnön lähettämistä.

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.

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

  • Rajapinnassa luotaville myyntilaskuille on suositeltavaa asettaa oma laskunumerosarjansa Fennoaan (Fennoa > Asetukset > Laskunumerot)
  • 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
    • email
    • finvoice
    • consumerfinvoice
    • consumerdirect
    • PEPPOL

Fennoa tukee seuraavia verkkolaskuoperaattoreita, sanomalla tulee käyttää verkkolaskuoperaattorin tunnusta:

Tunnus                                       Operaattori

HELSFIHHAktia Pankki Oyj
003723327487Apix Messaging Oy
BAWCFI22Basware Oyj
003703575029CGI Suomi Oy
5909000716438Comarch
CREDIFLOWCrediflow Ab
DABAFIHHDanske Bank Oyj
DNBAFIHXDNB Bank ASA
HANDFIHHHandelsbanken
885790000000418HighJump AS
INEXCHANGEInExchange Factorum AB
EXPSYSLexmark Expert Systems AB
003721291126Maventa
003726044706Netbox Finland Oy
NDEAFIHHNordea
003708599126OpenText / Liaison Technologies Oy
OKOYFIHHOP-Pohjola-ryhmä
003710948874OpusCapita Group Oy  Itella
E204503OpusCapita Solutions Oy
PAGEROPagero
003723609900Pagero
POPFFI22Paikallisosuuspankit
PALETTEPalette Software
PEPPOLPEPPOL BIS Billing 3.0
003710948874Posti Messaging Oy
003701150617PostNord Strålfors Oy
003714377140Ropo Capital Oy / Enfo Zender
SBANFIHHS-Pankki Oy
ITELFIHHSäästöpankit
003703575029Telia Finland Oyj
003701011385TietoEVRY Oyj
885060259470028Tradeshift 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”