Installera och koppla en kund

Det här kapitlet går igenom hur tjänsten installeras och hur den kopplas till en kunds Fortnox, från behörigheterna i Fortnox utvecklarportal till det första levererade verifikatet. Räkna med 20-30 minuter första gången. Du behöver inte kunna programmera, men du behöver tillgång till kundens Fortnox och till maskinen där tjänsten körs.

Installera tjänsten

Tjänsten finns för Windows, Linux och Mac under r-go.se/downloads/fortnox. Packa upp arkivet där tjänsten ska bo, till exempel C:\R-GO\fortnox eller ~/fortnox. Programmen arbetar relativt den katalogen:

Lägg nycklarna från FHD i secrets/keys.json (paketet har en exempelfil som visar formatet). Katalogen secrets/ ska bara kunna läsas av den som kör programmen: den som har nycklarna och kundens koppling kommer åt kundens bokföring. På Mac är programmen inte signerade; kör xattr -dr com.apple.quarantine . i katalogen en gång.

Tjänsten behöver komma åt källsystemets exportarkiv - för R-GO kassa receiptprinterns export/ - antingen på samma maskin eller via en delad katalog.

Räkna med 20-30 minuter första gången.

Innan du börjar

Tre saker måste finnas på plats hos kunden:

Och du behöver kunna logga in i kundens Fortnox med en användare som får godkänna integrationer.

Steg 1: Behörigheter i utvecklarportalen

Görs en gång för hela integrationen, inte per kund. Hoppa över det här steget om det redan är gjort.

Logga in på https://developer.fortnox.se, öppna integrationen r-go och gå till Behörigheter.

Fyra rutor ska vara ikryssade:

Lämna resten tom. Portalen säger det själv: “Begär därför endast behörigheter som behövs” - varje behörighet kan ställa licenskrav på kunden.

Kryssa INTE i “Ta bort verifikat”. Tjänsten tar aldrig bort något, och behörigheten skulle bara öka vad ett misstag kan ställa till med.

“Arkivplats” är inte samma sak som “Inbox”. Det tog oss ett extra försök: arkivplats gäller filarkivet, inbox är den brevlåda en bilaga går igenom. Du behöver inbox.

Efter publicering kräver nya behörigheter en ny förfrågan till Fortnox, så det är värt att få rätt från början.

Steg 2: Godkänn kopplingen för kunden

På maskinen där tjänsten körs:

fortnox-setup connect "Kundens Namn AB" --scope "bookkeeping companyinformation inbox connectfile"

Programmet skriver ut en adress och väntar.

1. Öppna adressen i en webbläsare på samma maskin. Den pekar på localhost, så en webbläsare på en annan dator når den inte.
2. Logga in som kunden och godkänn. Dialogen säger “r-go vill få tillgång till…”.
3. Programmet svarar Klart och sparar nycklarna.

Namnet du anger är ditt eget - det används bara för att hålla isär kunder i tjänsten. Välj något du känner igen, gärna företagsnamnet.

Om det inte fungerar

invalid_scope - An unsupported scope was requested Behörigheten är inte ikryssad för integrationen. Gå tillbaka till steg 1. Felet ser ut som ett stavfel men är det nästan aldrig.

kunde inte lyssna på port 8099 En tidigare körning väntar fortfarande. Stäng den och försök igen.

Inget händer när du godkänt Webbläsaren körs troligen på en annan dator än tjänsten.

Steg 3: Verifikationsserie i Fortnox

Kassans kontoplan använder normalt serie Z, som inte finns i Fortnox standarduppsättning. Lägg upp den i kundens Fortnox:

Bokföring → Inställningar → Verifikationsserier, ny serie:

Manuell måste vara Ja. En serie som inte är manuell avvisar varje verifikat utifrån, med felet “Verifikationsserien är inte manuell”. “Manuell” betyder här att verifikat kommer från ett annat system - till skillnad från de serier Fortnox fyller själv, som kundfakturor och lön.

Använder kunden en annan serie ändrar du i stället kassans kontoplan, under fliken Kontoplan i kassans inställningssida.

Steg 4: Provlevera ett verifikat

Ta fram ett verifikat i källsystemet. I R-GO kassa görs det med en Z-rapport, som skapar en katalog i exportarkivet:

kassa-1_voucher_z000001/
  bokforing.si      <- verifikatet
  verifikat.pdf     <- bokföringsordern
  zrapport.pdf      <- Z-rapporten den byggdes av

Titta först, skicka sedan:

fortnox-deliver check "Kundens Namn AB" .../kassa-1_voucher_z000001/bokforing.si

Den visar konton, belopp och om verifikatet balanserar - utan att skicka något. Ser det rätt ut:

fortnox-deliver send "Kundens Namn AB" .../bokforing.si --with-pdf

Svaret ska bli Levererat som Z1. följt av bilagorna.

Kontrollera i Fortnox: Bokföring → Verifikationer, välj rätt räkenskapsår och serie Z.

Det viktigaste att förstå

Ett verifikat kan inte tas bort. Fortnox har ingen sådan funktion i API:et, och ingen i webbgränssnittet heller för ett bokfört verifikat. Ett verifikat som skickats av misstag ligger kvar och måste rättas med ett motverifikat.

Därför finns en leveransjournal (data/deliveries.db) som håller reda på vad som skickats. Skickar du samma Z-rapport igen svarar tjänsten:

Redan levererat som Z1 - ingenting skickades.

Journalen måste följa med. Flyttar du tjänsten till en annan maskin, eller återställer från säkerhetskopia, måste data/ följa med. En borttappad journal betyder att allt kan skickas igen - och dubbletterna går inte att städa bort.

Underhåll

Förnya innan 45 dagar. Kopplingen håller i 45 dagar och förnyas automatiskt varje gång tjänsten används. En kund som bokför kvartalsvis hinner tappa sin koppling mellan körningarna - då får du göra om steg 2.

Kontrollera läget med:

fortnox-setup list

Står det token utgången - kör refresh:

fortnox-setup refresh "Kundens Namn AB"

Felmeddelanden du kan möta

Det sista är värt att ta på allvar. Tjänsten antecknar att den ska skicka innan den gör det, så ett avbrott mitt i lämnar ett frågetecken i stället för en tyst dubblett. Finns verifikatet i Fortnox är det klart; finns det inte kan du skicka igen.

Rätta en felaktig bilaga

Verifikat går inte att ta bort, men bilagor gör det: DELETE /3/voucherfileconnections/{FileId}. Har fel PDF hamnat på ett verifikat kan kopplingen tas bort och rätt fil fästas i stället.

Det finns inget kommando för det än - säg till om det behövs.

Vad tjänsten aldrig gör

• Tar inte bort något i Fortnox
• Rör inte kundregister, artiklar eller fakturor
• Ändrar inte ett verifikat som redan skickats
• Skickar inget automatiskt - varje leverans startas av någon

Tjänsten är också fristående från kassan. Den läser filer ur exportarkivet och bryr sig inte om vilket system som skrev dem.