SOAP gränssnittet

Introduktion

SOAP är en del av CRM-tjänstens öppna Web Service-gränssnitt. Detta dokument ger en teknisk översikt till utvecklare för att integrera tredjepartsapplikationer med CRM-tjänst.

De senaste specifikationerna och tjänstebeskrivningarna finns tillgängliga i vår onlinedokumentation:

https://<Din CRM-tjänst-url>/CrmIntegrationWebservice/

Om du inte är bekant med SOAP-baserade webbtjänster kan det vara bra att läsa lite bakgrundsinformation om det. Det finns en mycket kort beskrivning om SOAP och WSDL nedan också.

Vad är SOAP?

SOAP (Simple Object Access Protocol) är ett standardprotokoll för webbtjänster för att utbyta strukturerad information över internet.

Vad är WSDL?
I en SOAP-baserad webbtjänst beskrivs tjänsten i WSDL-dokument (Web Service Description Language). WSDL är ett XML-baserat språk som helt enkelt beskriver alla funktioner och strukturer för specifika webbtjänster. WSDL-dokumentet beskriver hur tjänsten kan anropas, vilka parametrar den förväntar sig och vilka datastrukturer den returnerar.

Vad är en API nyckel?
En API-nyckel är unik nyckel för att ge åtkomst till CIWS webbtjänster. Varje API-nyckel kan ha sin egen uppsättning tillåtna webbtjänster att använda.

Förutsättningar
Det rekommenderas att generera proxyklasser baserat på WSDL-definitionen. De flesta moderna IDE:er gör detta automatiskt. I exemplen nedan genereras klasserna och dataobjekten med det kostnadsfria wsdl2php-skriptet (http://www.urdalen.no/wsdl2php/). Observera att det också finns många andra applikationer och du är fri att använda den applikation du föredrar.

CRM Integration webb tjänst

För att kunna använda CRM Integration Web Services behöver du en giltig API-nyckel.

Alla exempel nedan är skrivna i PHP. Du kan dock använda Web Service API med vilket programmeringsspråk som helst.

Image 1: Autentisering med Web Service görs med en unik API-nyckel när Web Service returnerar sessionsinstans. Sessionen kan sedan användas för att autentisera resten av dina webbtjänstförfrågningar.

Skapa din session
För att komma i gång måste du först skapa en session för att autentisera dina förfrågningar.

//sessionManager is a proxy class generated using wsdl2php

 require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");$apiKey = YOUR_UNIQUE_API_KEY;//creating session

 $sessionManager = new sessionManager();try {
 $session = $sessionManager->createSession($apiKey);
 catch(Exception $e) {
 //do some exception handling
 }

Kodexempel 1:  Skapa en sessionsvariabel.

När du har skapat sessionen är du redo att använda de önskade webbtjänsterna. För den fullständiga listan över tillgängliga metoder, se onlinedokumentationen.

Viktigt – Om något går fel kommer webbtjänsten att returnera ett SOAP-fel undantag. Det är alltid viktigt att hantera undantag från dina webbtjänstförfrågningar. Många programmeringsspråk, som den inbyggda PHP SOAP-klienten, tar upp dessa som undantag.

Använd API:et – Autentisera dina kunder med Web Service API

API:et tillhandahåller en enkel metod för att autentisera dina kunder till alla tredjepartsapplikationer. Autentisering kan göras med tjänsten Contact Manager. Varje kontakt kan ställas in som portalanvändare från CRM.

require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");
require("PATH_TO_YOUR_LIBRARY_FILES/contactManager.php");$contactManager = new contactManager();$login = new PortalUserLoginDetails();

 $login->email = $email_address;
 $login->password = $password;
 $login->portal_id = $portal_id; //id for specific portal
 //there can be multiple portals in CRM and every contact is not involved
 //automatically to every portal. portal_id parameter defines the portal we are
 //authenticating to. Contacts and portals can be managed in CRM.

 try {
 $user = $contactManager->authenticatePortalUser($session, $login);
 } catch(Exception $e) {
 //Authentication failed. Handle exception for example by showing error page.
}

Kodexempel 2:  Autentisera CRM-portalanvändare (kontakter) med Web Service API.

Portal Användarautentisering görs av Contact Manager, så först måste vi skapa contactManager-objekt. Inloggningsinformation skickas till contactManager med PortalUserLoginDetails-objektet, så vi skapar ett sådant också. Den behöver tre parametrar: e-post, lösenord och portal-id. Portal-id är unikt ID för portalen vi försöker autentisera med. Det kan finnas flera portaler i samma CRM så vi måste definiera vilken portal vi försöker autentisera med. Kontakten måste vara aktiv portalanvändare i den specifika portalen för att autentiseringen ska lyckas.

Tillslut kan vi ringa contactManagers authenticatePortalUser-metod för autentisering. Om autentiseringen lyckades returneras ett authenticatedCustomer-objekt, annars skapas en förfrågan.

Ytterligare exempel – Skapa fakturamall
I exemplet nedan skapar vi en ny försäljningsorder med hjälp av CRM-tjänstens Web Service API.

require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");
require("PATH_TO_YOUR_LIBRARY_FILES/salesOrderManager.php");
require(“PATH_TO_YOUR_LIBRARY_FILES/accountManager.php”);//… create session as in the previous example …//We only know the product number, so let’s find the product ID from the Web Service.

 $productManager = new ProductManager();//We need a productSearchCriteria-object for our product search
 $productSearchCriteria = new ProductSearchCriteria();
 $productSearchCriteria->field = "product_no";
 $productSearchCriteria->value = "PRO2124";
 $productSearchCriteria->limit = 1;
 $productSearchCriteria->offset = 0;$products = null;try {
 $products = $productManager -> searchProducts($session,
 $productSearchCriteria);
 } catch (Exception $e) {
 //handle exceptions
 }

 $product = $products[0];

 //let’s create the sales order
 $salesOrderManager = new salesorderManager();
 $salesOrder = new SalesOrder();
 $salesOrder->account_id = 10000; // ID of Account
 $salesOrder->assigned_user_id = 1; //ID of Assigned User
 $salesOrder->bill_city = "Helsinki"
 $salesOrder->bill_code = "00100"
 $salesOrder->bill_country = "Finland";
 $salesOrder->bill_street = "Mannerheimintie 55";
 $salesOrder->contact_code_ext;
 $salesOrder->contact_id = 10001;
 $salesOrder->description = "Test sales order from PHP example file";
 $salesOrder->duedate = date("Y-m-d”);
 $salesOrder->status = "Created";
 $salesOrder->subject = "Test Order from PHP example";

//Add products to the sales order. In this example we have only one product though.
 $orderProductRow1 = new OrderProductRow();
 $orderProductRow1->productid = $product->id; //get product id f
 $orderProductRow1->description = $product->description
 $orderProductRow1->qty = 2;
 $orderProductRow1->value_period = 1;
 $orderProductRow1->unit_price = 200;

 $salesOrder->rows = array($orderProductRow1);

try {
 //finally we create our sales order
 $newSalesOrder = $salesOrderManager->createSalesOrder($session, $salesOrder);
 }  catch(Exception $e) {
 //do some exception handling
}

Kodexempel 3: Skapa en ny försäljningsorder med Web Service API

De första två raderna lägger till nödvändiga webbtjänstklasser för webbtjänstbegäran. På rad 7–22 söks produkten med motsvarande produktnummer. Raderna 27–42 skapar ett SalesOrder-objekt och lägger till nödvändiga parametrar till det.

Raderna 44–52 skapar en orderproduktrad till försäljningsordern. Produktraderna för beställningen är inställda på parametern SalesOrder-object ”rows” som tar array av orderproduktradobjekt som en parameter. Du kan lägga till så många rader du vill.

Slutligen skapas försäljningsordern på rad 56.

Alla API-förfrågningar bör lindas in i en try-catch-klausul. Web Service API genererar undantag med felmeddelande vid fel.

Ytterligare guider

Den fullständiga listan över webbtjänster och mer information finns i vår webbtjänstdokumentation:
https://<Your CRM-service-url>/CrmIntegrationWebservice/