Yleiset ohjeet koskien rajapintaa

Yhteistä kaikille rajapinnan toiminnoille:

• 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

1. 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ä.
2. 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.
3. 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
4. Vanhentuneet pyynnöt: Jos jonossa olevia pyyntöjä ei käsitellä, ne katsotaan vanhentuneiksi ja poistetaan automaattisesti. Näistä pyynnöistä palautuu virheilmoitus.
5. 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
  • email
  • finvoice
  • consumerfinvoice
  • consumerdirect
  • PEPPOL

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

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”