Integration von Web Services

Über diese Dokument

Dieses Dokument bietet Entwicklern einen technischen Überblick über die Integration von Drittanbieter-Anwendungen mit CRM-service.

Allgemeines

Wir bieten eine SOAP-API für Ihre eigenen Anwendungen und Integrationen an. In unserer Online-Dokumentation finden Sie immer die neuesten Spezifikationen und Servicebeschreibungen:

https://<Your CRM-service-url>/CrmIntegrationWebservice/

Wenn Sie mit SOAP-basierten Webdiensten nicht vertraut sind, kann es nützlich sein, einige Hintergrundinformationen darüber zu lesen. Es folgt eine kurze Beschreibung von SOAP und WSDL.

Was ist SOAP?
SOAP (Simple Object Access Protocol) ist ein Standardprotokoll für Web Services zum Austausch strukturierter Informationen über das Internet.

Was ist WSDL?
In einem SOAP-basierten Webdienst wird der Dienst in WSDL-Dokumenten (Web Service Description Language) beschrieben. WSDL ist eine XML-basierte Sprache, die einfach alle Funktionalitäten und Strukturen eines bestimmten Web Service beschreibt. Das WSDL-Dokument beschreibt, wie der Service aufgerufen werden kann, welche Parameter er erwartet und welche Datenstrukturen er zurückgibt.

Was ist ein API-Schlüssel?
Ein API-Schlüssel ist ein einzigartiger Schlüssel für den Zugriff auf CIWS-Webdienste. Für jeden API-Schlüssel kann ein eigener Satz zulässiger Webdienste verwendet werden.

Voraussetzungen
Es wird empfohlen, basierend auf der WSDL-Definition Proxy-Klassen zu generieren. Die meisten modernen IDEs tun dies automatisch. In den folgenden Beispielen werden die Klassen und Datenobjekte mit dem freien wsdl2php-Skript erzeugt (http://www.urdalen.no/wsdl2php/). Bitte beachten Sie, dass es auch viele andere Anwendungen gibt und Sie können die von Ihnen bevorzugte Anwendung verwenden.

CRM Integration Web Services

Um CRM Integration-Web-Services zu verwenden, benötigen Sie einen gültigen API-Schlüssel.

Alle folgenden Beispiele sind in PHP geschrieben. Sie können jedoch die Web-Service-APIs mit einer beliebigen Programmiersprache verwenden.

Abbildung 1: Die Authentifizierung mit dem Web-Service erfolgt mithilfe eines einzigartigen API-Schlüssels, wenn der Web-Service die Sitzungsinstanz zurückgibt. Die Sitzung kann dann verwendet werden, um den Rest Ihrer Web-Service-Anfragen zu authentifizieren.

Sitzung erstellen
Um zu beginnen, müssen Sie zuerst eine Sitzung erstellen, um Ihre Anforderungen zu authentifizieren.

//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
 }

Codebeispiel 1:  Erstellung einer Sitzungsvariablen.

Nachdem Sie die Sitzung erstellt haben, können Sie die gewünschten Webdienste verwenden. Eine vollständige Liste der verfügbaren Methoden finden Sie in der Online-Dokumentation.

Wichtig – Wenn etwas schief geht, gibt der Web Service eine SOAP-Fehlerausnahme zurück. Es ist immer wichtig, Ausnahmen Ihrer Web-Service-Anfragen zu behandeln. Viele Programmiersprachen, wie der native PHP SOAP-Client, heben diese als Ausnahmen auf.

Verwendung der API – Kunden mit der Web Service API authentifizieren
Die API bietet eine einfache Methode zur Authentifizierung Ihrer Kunden bei Anwendungen von Drittanbietern. Die Authentifizierung kann mit dem Contact Manager-Dienst vorgenommen werden. Jeder Kontakt kann als Portalnutzer im CRM festgelegt werden.

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.
}

Codebeispiel 2:  CRM-Portalnutzer (Kontakte) mit der Web Service API authentifizieren.

Die Portal-Benutzerauthentifizierung wird vom contactManager durchgeführt. Zuerst muss das contactManager-Objekt erstellt werden. Da die Login-Informationen an den contactManager mit dem PortalUserLoginDetails-Objekt übergeben wird, muss ebenso dieses Objekt erstellt werden. Es benötigt drei Parameter: Email, Passwort und Portal-ID. Das Portal-ID ist eine einzigartige ID für das Portal, mit dem wir uns authentifizieren möchten.  Es kann nämlich mehrere Portale im selben CRM geben, also muss definiert werden, mit welchem Portal der Kontakt authentifiziert werden soll. Der Kontakt muss in dem spezifischen Portal aktiver Portalnutzer sein, damit die Authentifizierung für dieses erfolgreich ist.

Schließlich kann die authenticatePortalUser-Methode von dem contactManager zur Authentifizierung aufrufen. Wenn die Authentifizierung erfolgreich war, wird ein authentifiziertes Kundenobjekt zurückgegeben, andernfalls wird eine Ausnahme ausgelöst.

Weiteres Beispiel – Kaufauftrag erstellen
Im folgenden Beispiel wird ein neuer Kaufauftrag mithilfe des CRM-service Web Service API erstellt:

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
}

Codebeispiel 3: Erstellen eines neuen Kaufauftrags mithilfe der Web-Service-API

Die ersten beiden Zeilen fügen erforderliche Web-Service-Klassen für die Web-Service-Anfrage hinzu. In den Zeilen 7-22 wird das Produkt mit einer entsprechenden Produktnummer gesucht. Die Zeilen 27-42 erstellen ein SalesOrder-Objekt (Kaufauftrag) und fügen ihm benötigte Parameter hinzu.

Die Zeilen 44-52 erzeugen eine Auftragsproduktreihe zum Kaufauftrag. Die Produktreihen des Auftrags werden auf den Parameter SalesOrder-object “rows” gesetzt, der ein Array von Produkten der Auftragsproduktzeile als Parameter akzeptiert. Sie können so viele Zeilen hinzufügen, wie Sie möchten.

Schließlich wird der Kaufauftrag in Zeile 56 erstellt.

Alle API-Anforderungen sollten in eine try-catch-Klausel eingebettet werden. Die Web Service API generiert im Fehlerfall eine Ausnahme mit einer Fehlermeldung.

Weiterführende Literatur

Die vollständige Liste der Web-Services und weitere Informationen finden Sie in unserer Web-Service-Dokumentation:
https://<Your CRM-service-url>/CrmIntegrationWebservice/

Integration von Web Services
Combined Shape