Jetshop AB WEBSERVICE-API 1.2 ANVÄNDARMANUAL. Version 1.2 2011-10-12

Jetshop AB WEBSERVICE-API 1.2 ANVÄNDARMANUAL Version 1.2 2011-10-12

1. Förord I det här dokumentet ges en generell beskrivning av det Webservice-API som är utvecklat av Jetshop AB, och är avsett för dig som önskar att skräddarsy en integrationslösning med ditt affärsystem eller liknande. Detta förutsätter att du som utvecklare har goda kunskaper kring programmering, gärna i ett objektorienterat programmeringspråk så som C#, C++ eller java. Det är tänkt att detta dokument ska svara på alla typer av frågor, men om annat skulle vara fallet kontakta då Jetshop support för vägledning. Det är viktigt att i förhand veta att det finns olika rättigheter kopplade till varje användarkonto. Alla användarkonton har som minsta rättighet standard-rollen, vilket innebär att den kan exekvera metoderna som beskrivits under stycke 6.1 (Generell datahantering). I de fall där otillåtna metoder körs kastas en AccessViolationException och exekveringen avbryts. Det är möjligt för den som vill få en överblick över vad webservicen kan erbjuda, genom att logga in i webservicen med hjälp av en webbläsare. Det går även att köra en del av metoderna från webbläsaren. I appendix A.1 finns en lista på de metoder som i dagsläget går att exekvera från en webbläsare. Adressen till webservicen är http://webservices20.jetshop.se/api2.5/ I slutet av dokumentet i Appendix B finns klassdiagram över alla de objekt som är nödvändiga vid utveckling mot webservicen. Därför kommer få av alla möjliga egenskaper för dessa objekt att nämnas i exempelkoden. Se dessa diagram för mer tekniskt detaljerad beskrivning. All kod som beskrivs i dokumentet är i programmeringsspråket C-sharp Bilduppladdning via webservicen beskrivs i ett eget dokument (bilduppladdning.pdf)

2. Innehållsförteckning 1. Förord... 2 2. Innehålsförteckning... 3 3. Kravspecifikation... 4 4. Förberedelse... 5 4.1. Kom igång med Visual Studio 2008.... 5 5. Börja utveckla... 8 6. API dokumentation... 8 6.1. Generell datahantering... 9 6.2. Kunddatahantering... 9 6.3. Orderdatahantering... 9 6.4. Produktdatahantering... 9 6.5. Webservicedefinierade Datatyper... 10 7. Exempelsamling... 12 7.1. Hämta en specifik produkt.... 12 7.2. Skapa ny/uppdatera produkt... 12 Appendix A.... 14 A. Exekverbara methoder från en webbläsare.... 14 Appendix B... 15 B1. Generell datahantering... 15 B2. Kunddatahantering... 16 B3. Orderdatahantering... 17 B4. Produktdatahantering... 19

3. Kravspecifikation Utveckling mot Webservicen kan göras i olika miljöer, men Visual Studio är den som rekommenderas och kommer därför att beskrivas mest. I övrigt är det möjligt att implemetera mot Webservicen med alla programmeringsspråk som kan importera och nyttja Webservice som resurs. Det finns inga specifika krav på datorprestanda men den dator som används måste kunna hantera en utvecklingsmiljö av den typ som önskas användas.

4. Förberedelse 4.1. Kom igång med Visual Studio 2008. Det finns huvudsakligen en viktig steg som måste utföras innan det går att börja implementera. Detta steg innebär att skapa en referens till Webservicen. Detta görs i stora drag på samma sätt i Visual Studio 2005 som Visual Studio 2008 men små skillnader. Eftersom det är mer komplext i VS 2008 kommer enbart den att beskrivas. Steg 1. Högerklicka på References i Solutoin Explorer trädet. Välj där Add Service References. Steg 2. Klicka på Advanced... knappen längst ner till vänster i rutan som dyker upp. Steg 3. Klicka på Add Web Reference... knappen längst ner till vänster i rutan som dyker upp.

Se figur 1 nedan för visuell beskrivning av Steg 1, 2 och 3. Figur 1. Steg 4. I rutan som dyker upp anges adressen till webservicen. Adressen är http://webservices20.jetshop.se/api2.5/. Steg 5. När adressen angivits visas en inloggningsruta. Tryck här Cancel en gång så att rubriken på inloggningsrutan ändras till Discovery Credentials. Ange nu dina inloggningsuppgifter och loggar in. När inloggningsrutan försvunnit kan du i textrutan till höger som heter Web reference name ange ett namn på webservicen som ska användas under utvecklingen i form av ett namespace. Klicka på Add reference knappen under namnrutan. Det läggs in en reference till webservicen i ditt projekt och kommer finnas under Reference mappen i solution explorer trädet.

Observera figurerna nedan för en visuell beskrivning. Figur 2. Figur 3.

5. Börja utveckla När det finns en referens till webservicen inuti det Visual Studio projekt som används går det att börja utveckla mot din specifika shop på Jetshop. Om det inte finns en referens vars namn valdes vid import av webserviceren, under Reference mappen i solution explorer trädet, återgå till punkt 4 ovan. (Förberedelse). Förutsatt att ett projekt är skapat och webservicereferensen är importerad, går det att börja implementera. Nedan kommer kod exempel på hur ett webserviceobjekt skapas och vilka egenskaper som måste finnas med för att få en fungerade integration mot webservicen. I koden nedan heter webservicereferensen JetshopWebservices. JetshopWebservices.WebServiceProvider _webservice = new JetshopWebservices.WebServiceProvider(); _webservice.cookiecontainer = new System.Net.CookieContainer(); _webservice.credentials = new System.Net.NetworkCredential("Användarnamn", "lösenord"); Instruktionerna ovan behöver enbart exekveras en gång. Sedan utför man alla operationer genom _webservice objektet. Det innebär att _webserviceobjektet bör vara deklarerat som en global variabel om den ska kunna användas globalt. 6. API dokumentation Det finns en mängd metoder tillgängliga från webservicen som tilllåter kontroll över stora delar av en shops databas. Dessa beskrivs kort nedan. Notera att de flesta nedan nämnda metoder är så kallade override metoder vilket innebär att de kan exekveras med olika inparametrar. De återkommande alternativa parametrarna är val av språk och val av shop. För att ha nytta av att kunna specificera shop måste det finnas fler än shop knuten till användarkontot som används, och för att kunna nyttja möjligheten av att välja språk måste det finnas stöd för flera språk i den angivna shopen. Utveckling mot webservicen är uppdelat i 4 huvuddelar, Generelldatahantering, Kunddatahantering, Orderdatahantering och Produktdatahantering. För dessa finns definierat enskilda datatyper med vars hjälp genomförs olika typer av operationer. Datatyperna är CommonDataManager, CustomerManager, OrderManager och ProductManager. Dessa beskrivs i mer detalj i section 6.5 (Webservicedefinierade Datatyper).

6.1. Generell datahantering GetCultures(...) Hämta alla tillgängliga språk för shoppen. GetOrderStatuses(...) Hämta tillgängliga orderstatusar. GetPaymentTypes(...) Hämta alla betaltyper. GetShopIdentifiers() Hämta alla shopidn kopplade till det användarkonto som används. 6.2. Kunddatahantering Customer_AddUpdate(...) Lägg till eller uppdatera befintliga kunder i shoppen. Customer_Delete(...) Ta bort kunder från shoppen. Customer_GetAll(...) Hämta all kundinformation som finns på shoppen. Customer_GetSingle(...) Hämta kundinformation för en enstaka kund som är registrerad på shoppen. 6.3. Orderdatahantering Order_Get(...) Hämta alla ordrar med respektive information som lagts in på shoppen. Order_UpdateOrderData(...) Uppdatera orderinformation som inkluderar synkroniserad flagga, streckkod och kollinummer. Order_UpdateStockItemCountByPartialDeliveryInfo(...) Uppdatera lagersaldo på produkter efter delleverans på en specifik order. 6.4. Produktdatahantering Product_AddUpdate(...) Lägg till nya eller uppdatera befintliga produkter I shoppen. Product_Get(...) Hämta alla produkter med respektive information från shoppen. Product_UpdateStockData(...) Uppdatera befintlig produkt med information som inkluderar lagersaldo, lagerstatus, leveransdatum och användning av avancerad produktstatus.

6.5. Webservicedefinierade Datatyper Utveckling mot webservicen är updelat i 4 delar. Se följande tabell för beskrivning på hur datatyperna relaterar till de 4 huvuddelarna. - Generell datahanteringstyper: CommonDataManager Innehåller metoder för generell datahantering. (6.1 Generell datahantering) Language Returneras av metoden GetCultures( ) OrderStatus Returneras av metoden GetOrderStatuses( ) PaymentType Returneras av metoden GetPaymentTypes( ) ConnectionItem - Returneras av metodengetshopidentifiers(...) Result Returneras av metoderna som skapar nya/uppdaterar data. (Gäller samtidliga metoder, men resultseten kan se något olika ut.) - Kunddatahanteringstyper: CustomerManager Innehåller metoder för kunddatahantering. (6.2 Kunddatahantering) Returneras av metoden Customer_GetAll(...) och Customer_GetSingle(...). CustomerDataItem Används som inparameter för metoden Customer_AddUpdate(...) vid inladdning eller uppdatering av kunddata. Alternativt returneras den i samband med hämtning av kunddata. AddressDataItem Denna innehåller adressinformation för en kund. Addressfältet i CustomerItemDatatypen tilldelas en lista av AddressDataItem vid inladdning eller uppdatering av kunddata. Vid kunddatahämtning kommer denna returneras och finnas tillgänglig i CustomerItemData. - Orderdatahanteringstyper: OrderManager Innehåller metoder för orderdatahantering. (6.3 Orderdatahantering) Returneras av metoderna Order_Get. OrderItemData Returneras i form av en lista tillgänglig i OrderManagertypen som returneras av hämta metorderna för orderar. OrderDetailsItem Returneras i form av en lista i OrderItemDatatypen. OrderDiscountItem Returneras i form av en lista inbakat i OrderItemDatatypen.

OrderDeliveryInfo Används som inparameter i metoden Order_UpdateStockItemCountByPartialDeliveryInfo(...) vid uppdatering av delvis levererad order. OrderUpdateData Används som inparameter i metorden Order_UpdateOrderData(...) vid uppdatering av orderdata. OrderDetailsUpdateData Tilldelas till orderdetaljdatafältet i OrderUpdateData och används därmed vid uppdatering av orderdata. - Produktdatahanteringstyper: ProductManager Innehåller metoder för produktdatahantering. (6.4 Produktdatahantering) Returneras av metorderna Product_Get. ProductDataItem Används som inparameter i metoden Product_AddUpdate(...) vid inladdning eller uppdatering av produktdata. Alternativt returneras den i samband med hämtning av produktdata och är därför tillgänglig i ProductManagertypen. ProductAttributeDataItem Denna typ håller attributdata för en specifik produkt. Det finns ett fält av typen ProductAttributeDataItem-lista som tilldelas en lista av denna typ vid inladdning eller uppdatering av produktdata. I övrigt returneras vid hämtning av produktdata och blir tillgänglig från ProductDataItem. ProductSpecificationDataItem Denna typ håller specifikationsdata för en produkt. Det är inte möjligt att ladda in eller uppdatera denna typ av information genom webservicen men vid hämtning av produktdata returneras den och blir tillgänglig i ProductDataItem. ProductStockData Används som inparameter vid uppdatering av lagerinformation för en specifik produkt. Den anges i form av en lista vid exekvering av metoden Product_UpdateStockData(...).

7. Exempelsamling De kommande exempelkoden förutsätter att det som förklarades i stycke 5 (Börja utveckla) är utfört och att det finns ett referensobjekt för webservicen tillgängligt som kallas _webservice. 7.1. Hämta en specifik produkt. I de fall där målet är att hämta data från shoppen är implementeringen liknande oavsett vilken typ av data som ska hämtas. Därför förklaras här bara uthämtning av produktdata för en specifik produkt. Det returneras alltid ett så kallad managerobjekt vid exekvering av alla typer av hämta metoderna. I dessa objekt finns bl.a. information om huruvida hämtningen lyckats eller inte, och även önskad data och antal hämtade objekt. Följande kodrad exekverar metoden som heter Product_Get med det artikelnummer som önskas och värdet true för att även inkludera produktens attributdata eller specifikationsdata i resultatet. ProductOptions po = new ProductOptions(); po.articlenumber = 123456 po.getattributesandspecifications = true; Jetshop.ProductManager productmanager = _webservice.product_get("artikelnummer", true); Det följande är den typ av information i productmanagerobjektet som returneras från webservicen efter produktdatahämtning: productmanager.count; (int) productmanager.productitemcollection; (ProductDataItem) productmanager.result; (int) Observera att det även finns alternativparametrar för objektet ProductOptions. Det är möjligt att även specificera det språk produktdatat ska returneras i, vilken shop data ska hämtas från osv. Dessa förutsätter att det finns stöd för flera språk och att det finns mer än en shop knuten till användarkontot. Se ProductOptions som ett filter. Väljer man att anropa metoden Product_Get(...) utan att ange några värden för ProductOptions kommer alla produkter i shoppen returneras. Egenskaper i ProductOptions po.synchstatus = Hämta produkter med en viss synkstatus po.onlyvisibleproducts = Endast synliga produkter i shoppen po.rowcount = Antal produkter som önskas returnerade po.productsortorder = Sorteringsordning för returnerade produkter po.pricelistidorname = Prislista för returnerade produkter po.shopidentifier = Från vilken shop skall data hämtas (om man har flera) po.culture = Vilket språk vill man ha datan returnerad på. (sv-se, nb-no)

7.2. Skapa ny/uppdatera produkt För att skapa eller uppdatera en produkt är det nödvändigt att ha kännedom om några produktdatarelaterade objekt som är definierade i webservicen. Dessa objekt är ProductStockData, ProductAttributeDataItem, ProductDataItem och ProductManager. Dessa kommer nu att förklaras, instansieras och användas. Nedan skapas först det objektet som håller all information för en viss produkt dvs. ProductDataItem. I klassdiagrammen i Apendix B finns en lista med alla egenskaper som det går att tilldela värden till. Nedan används några av de vanligaste. Notera, ProductID fältet tilldelas värde enbart vid updatering. När en ny produkt skapas, skapas även ProductID för denna. JetshopWebservices.ProductDataItem huvudprodukt = new ProductDataItem(); huvudprodukt.productid = 18343; huvudprodukt.articlenumber = "Produkt_artikelnummer"; huvudprodukt.name = "Produkt_namn"; huvudprodukt.productdescription = "Produkt_beskrivning"; huvudprodukt.discountenddate = DateTime.Now; huvudprodukt.discountstartdate = DateTime.Now; Nästa kodstycke skapar ProductStockDataobjektet alltså det objekt som håller värden för lagerinformation. I objektet kan man sätta värden på följande egenskaper på liknande sätt som gjorts för StockStatusID (lagerstatusid) nedan. NewStockCount, UseAdvancedStatus, DeliveryDate och StockStatusID. JetshopWebservices.ProductStockData lagerdata = new ProductStockData(); lagerdata.stockstatusid = 2; Här tilldelas Huvudprodukt instansens lagerdata-hållare, lagerdata objektet som skapades först och attributdata-hållaren tilldelas listan med attribut dvs. attributlista. huvudprodukt.stockdata = lagerdata; Nu exekveras metoden för inladdning/uppdatering av produktdata. Metoden returnerar en lista av typen Result som innehåller information för varje produkt som fanns med i listan av produkter som skapats/uppdaterats. Informationen säger om metoden exekverats utan problem för den specifika produkten. JetshopWebservices.Result[] res = _webservice.product_addupdate(new ProductDataItem[] { p });

Appendix A. A. Exekverbara methoder från en webbläsare. GetCultures(...) GetOrderStatuses(...) GetPaymentTypes(...) GetShopIdentifiers(...) Customer_GetAll(...) Customer_GetSingle(...) I stycke 6 (API dokumentation) finns beskrivningar på vad metoderna utför.

Appendix B B1. Generell datahantering

B2. Kunddatahantering

B3. Orderdatahantering

B4. Produktdatahantering