ShopLink

Introduktion

ShopLink gør det muligt via fladfilsudveksling, at integrere shoppen med eksterne systemer som regnskab- og lagersystemer mv. idet det giver mulighed for, at hente, oprette, redigere og slette entiteter i shoppen på samme måde som med import af produkter osv. ShopLink gør det muligt, at synkronisere ordrer fra shoppen til eksterne systemer samt, at synkronisere produkter (uden varianter) fra eksterne systemer til shoppen. I princippet kan ShopLink bruges til alle økonomisystemer, som understøtter fladfilsudveksling.

ShopLink er en Windows terminal applikation til .NET 4.6.1, der arbejder via shoppens API. Man vil typisk afvikle applikationen fra en server via scheduled tasks så opgaverne udføres med de intervaller der er behov for. Hver gang ShopLink afvikles indlæses en konfigurationsfil, solutions.txt, som bestemmer de handlinger programmet udfører. Shoplink benytter TLS 1.2.

ShopLink gør brug af webshoppens eksisterende import/eksport format, som er beskrevet i vores generelle guide til eksport.

I praksis

ShopLink udfører følgende opgaver:

• Eksport af nye ordrer fra shopsystemet:
  • Der kontrolleres om der er ordrer i webshoppen med status "under behandling" (status kode 2). Normalt markeres en ordre som "Ordre modtaget" (status kode 1) når den oprettes. Dette kan ændres til "under behandling" (status kode 2) under betalingsmetoden, hvis f.eks. ordren ønskes overført til C5 med det samme.
    • Hvis der forekommer nye ordrer, eksporteres disse i CSV/XML-format som beskrevet ovenfor og placeres i <Installationsmappe>/orderexport/ med navngivning ”shopnavn_dato”
    • Der kaldes et angivet batchscript (bat), som sørger for at behandle de eksporterede ordredata til det eksterne system.
      • Det pålægges batchscriptet, at fjerne CSV/XML-filer fra eksport-folderen efter, at de er behandlet i det eksterne system.
  • ShopLink gemmer efter hver ordreeksport, ID'er på de overførte ordrer i filen /installationsmappe/ids.txt. Denne indeholder således en komplet liste over alle eksporterede ordrer. Fjernes et ID fra denne fil vil ordren med det pågældende ID blive eksporteret næste gang eksportrutinen køres, hvis den stadig er "under behandling" (status kode 2).

• Import af data (f.eks. produkter eller brugere) fra det eksterne system til en given webshop.
  • Ønskes opdatering eller oprettelse af et eller flere data fra det eksterne system til en webshop placeres en CSV eller XML-fil i <Installationsmappe>/import/ folderen. Formatet skal ligne den generelle eksport fra webshopsystemet, beskrevet i den generelle manual (under Moduler > Eksport).
  • Efter import flytter mellemlaget importerede filer til <Installationsmappe>/import/imported/ folderen.
  • Det er muligt automatisk at importere produkt-billeder fra shoplink. Dette understøttes kun ved import af produkter i XML-format. Det/De angivne billeder skal ligge i <Installationsmappe>/import/ folderen og de skal navngives så deres navn stemmer overens med det der er angivet under PICTURES for produkterne.

Bemærk: Ordrer kan IKKE importeres.

Opsætning

Shoplink er et tilkøbsmodul som skal aktiveres på shoppen før nedenstående procedure kan gennemføres.

ShopLink kan hentes her (download ZIP-fil) og kræver .NET 4.6.1.
Udpak programfilerne i en mappe:

I solutions.txt filen indtastes oplysninger for de løsninger der ønskes synkroniseret. Hver linje repræsenterer én løsning i følgende format (se eksempler længere nede i artiklen):

    <export-format>, <Solution>, <Password>, <Installationsmappe>, <Import Script>, <Server>, <FTP brugernavn>, <FTP kodeord>

I denne parameteroversigt kan du se opbygningen af forespørgsler:

• Vælges eksempelvis mappen <Installationsmappe> vil programmet oprette følgende undermapper:
  <Installationsmappe>/orderexport/ - her placeres nye ordre fra shoppen i CSV/XML format (alt efter <export-format>)
  <Installationsmappe>/import/ - her skal CSV/XML filer med produkter placeres for at blive importeret af ShopLink
  <Installationsmappe>/import/imported/ - efter en produkt CSV/XML fil er importeret placeres den i denne mappe
• <Import Script> indsættes stien til et evt. batch script som sørger for at importere ordre CSV/XML-filer fra <Installationsmappe>/orderexport/ folderen til det eksterne system, og eksportere produkter fra det eksterne system til <Installationsmappe>/import/ folderen.
  Parameteret kan efterlades blank hvis der ikke ønskes noget script kørt.
• <Server> udfyldes med værtsnavnet (ftps.mywebshop.io) eller IP-adressen på FTP-serveren som din løsning kører på.
• <FTP brugernavn> og <FTP kodeord> udfyldes med brugernavnet og adgangskoden til din FTP-konto på din løsning. Kan efterlades blank hvis der ikke ønskes automatisk overførsel af billeder.

Hvis du har brug for overførsel af billeder skal du oprette en FTP-bruger i shoppen under Indstillinger > FTP-konti med adgang til rodmappen "/upload_dir/". Du kan læse hvordan dette gøres her.

Aktiver API adgang i shopsystemet under Indstillinger > API: SOAP.
Bemærk: Opsætningen kræver en dedikeret API-bruger. Standard administrator brugeren kan med andre ord ikke benyttes. Du kan læse mere om API-brugere her.

Eksempel på linje i solutions.txt med tilknyttet ftp-konti og udtræk af filer som xml, samt import script beliggende i c:\path\to\script\file.exe:

    xml,username,password,c:\path\to\file\folder\,c:\path\to\script\file.exe,ftps.mywebshop.io,ftplogin,ftppassword

Eksempel på linje i solutions.txt uden tilknyttet ftp-konti eller import script og udtræk i csv format:

    csv,username,password,c:\shoplink\output\,,,,

Gem solutions.txt og kør ShopLink, der automatisk indlæser solutions.txt og kører forespørgslen.

Når du kører ShopLink via terminal (cmd) får du et overblik over eksekveringen som vist her:

1. I første forsøg var oplysningerne i solutions.txt ikke korrekte.
2. Her er oplysningerne korrekte og forespørgslen eksekveres som forventet.

Output eksempel

I eksemplet herunder har vi ændret ordrestatus til "Under behandling" (se sektionen I praksis vedr. ordrestatus) på vores ordre med ID 22, og kørt Shoplink.exe via vores terminal. Softwaren tager nu fat i solutions.txt og udfører eksporten af alle ordrer med denne status (se sektionen I praksis vedr. filen ids.txt, der kan benyttes til at ekskludere og inkludere ordrer i udtrækket). Herefter fremkommer den eksporterede fil i mappen orderexport:

Vores ordre-eksport indeholder alle de datafelter som det er muligt, at eksportere via ShopLink (alle felter eksporteres uanset om de indeholder en værdi eller ej). Til sammenligning har vi sat en standard ordreeksport op ved siden af vores ShopLink-eksport; ShopLink til venstre og en manuel ordreeksport til højre:

Rækkerne er sorteret alfabetisk i dette eksempel. Bemærk: Shoplink eksporten er til venstre (højre eksempel er en manuel shop eksport).

Fejlsøgning

• Husk at benytte den seneste version af ShopLink.
• Brugernavn og password er dine SOAP-API brugeroplysninger og ikke dit administrator-login til shoppen.
• Den angivne sti til mappen skal være tilgængelig for ShopLink. Tjek linket til mappen en ekstra gang.
• FTP værtsnavnet skal være "ftps.mywebshop.io", hvis du benytter FTP-funktionaliteten (ellers kan feltet undlades).
• Hvis du har mange tusinde ordrer til eksport kan forespørgslen nå at time ud før alle data kan rekvireres. I så fald skal du begrænse mængden af ordrer til udlæsning ved, at tilføje ordre ID i ids.txt filen, som skal undlades (dette kan gøres via en ordreeksport), eller ved, at sætte et mindre antal ordrer til ordrestatus "Under behandling".
• ShopLink er et separat tilkøbsmodul til shoppen. Det er med andre ord ikke nok at aktivere API og opsætte en API-bruger.

Scheduled task

Der kan med fordel sættes en Windows scheduled task op som f.eks. kører ShopLink hvert 5. minut.
Bemærk: Ved opsætning som scheduled task skal stien til solutions.txt angives som det første argument til programmet under opsætningen af scheduled task. Start taskschd.msc og opret en ny opgave. Du kan læse mere om Windows Task Scheduler her.

Filformater

ShopLink benytter webshoppens eksisterende import/eksport format. Dog tilbyder Shoplink ikke så bredt et udvalg af datafelter som en standard eksport fra shoppen. Se formatet i manualen under eksport.

Nyttige links

• Tilføj produkter til kurven via link med Åben indkøbskurv
• Bliv notificeret omkring nye ordrer med Webhooks
• Find og installer ny shopfunktionalitet med App store