Die SOAP-Schnittstelle

Die SOAP-Schnittstelle

Einleitung

SOAP ist Teil der offenen Web-Service-Schnittstellen des CRM-Ssrvice. Dieses Dokument bietet Entwicklern einen technischen Überblick über die Integration von Anwendungen von Drittanbietern in das CRM-service.

Die neuesten Spezifikationen und Leistungsbeschreibungen finden Sie in unserer Online-Dokumentation:

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

Wenn Sie mit SOAP-basierten Webdiensten nicht vertraut sind, sollten Sie einige Hintergrundinformationen dazu lesen. Nachstehend finden Sie eine kurze Beschreibung von SOAP und WSDL.

Was ist SOAP?
SOAP (Simple Object Access Protocol) ist ein Standardprotokoll für Webdienste 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 Funktionen und Strukturen eines bestimmten Webdienstes 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-Sclüssel?
Ein API-Schlüssel ist ein eindeutiger Schlüssel für den Zugriff auf CIWS-Webdienste. Jeder API-Schlüssel kann über einen eigenen Satz zulässiger Webdienste verfügen.

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

CRM Integration Web Services

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

Alle folgenden Beispiele sind in PHP geschrieben. Sie können die Webdienst-API jedoch mit jeder Programmiersprache verwenden.

Abbildung 1: Die Authentifizierung beim Webdienst erfolgt über einen eindeutigen API-Schlüssel, wenn der Webdienst die Sitzungsinstanz zurückgibt. Die Sitzung kann dann verwendet werden, um den Rest Ihrer Webdienstanforderungen zu authentifizieren.

Erstellen Sie Ihre Sitzung
Um loszulegen, 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
 }

Code-Beispiel 1: Sitzungsvariable erstellen.

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

Wichtig – Wenn ein Fehler auftritt, gibt der Webdienst eine SOAP-Fehlerausnahme zurück. Es ist immer wichtig, Ausnahmen von Ihren Web-Service-Anforderungen zu behandeln. Viele Programmiersprachen, wie der native PHP-SOAP-Client, geben diese als Ausnahmen an.

Verwenden Sie die API – Authentifizieren Sie Ihre Kunden mit der Web-Service-API
Die API bietet eine einfache Methode zur Authentifizierung Ihrer Kunden gegenüber Anwendungen von Drittanbietern. Die Authentifizierung kann über den Contact Manager-Dienst erfolgen. Jeder Kontakt kann in CRM als Portalnutzer 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.
}

Code-Beispiel 2: Authentifizieren von CRM-Portalnutzern (Kontakten) mit der Webdienst-API.

Die Portalnutzerauthentifizierung wird von Contact Manager durchgeführt, daher müssen wir zuerst ein contactManager-Objekt erstellen. Die Anmeldeinformationen werden mit dem PortalUserLoginDetails-Objekt an contactManager übergeben, daher erstellen wir auch eine Eins. Es werden drei Parameter benötigt: E-Mail, Passwort und Portal-ID. Die Portal-ID ist eine eindeutige ID für das Portal, mit dem wir uns authentifizieren möchten. In einem CRM können mehrere Portale vorhanden sein, daher müssen wir definieren, mit welchem ​​Portal wir uns authentifizieren möchten. Der Kontakt muss ein aktiver Portalnutzer in diesem bestimmten Portal sein, damit die Authentifizierung erfolgreich ist.

Schließlich können wir die authenticatePortalUser-Methode von contactManager zur Authentifizierung aufrufen. Wenn die Authentifizierung erfolgreich war, wird ein authenticatedCustomer-Objekt zurückgegeben, andernfalls wird eine Erwartung ausgelöst.

Ein weiteres Beispiel – Verkaufsauftrag anlegen
Im folgenden Beispiel erstellen wir einen neuen Verkaufsauftrag mit der Web-Service-API von CRM-Service.

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
}

Code-Beispiel 3: Erstellung eines neuen Verkaufsauftrags mithilfe der Web-Service-API

In den ersten beiden Zeilen werden die erforderlichen Webdienstklassen für die Webdienstanforderung hinzugefügt. In den Zeilen 7–22 wird das Produkt mit einer entsprechenden Produktnummer gesucht. In den Zeilen 27–42 wird ein SalesOrder-Objekt erstellt und die erforderlichen Parameter hinzugefügt.

In den Zeilen 44–52 wird eine Auftragsproduktzeile für den Verkaufsauftrag erstellt. Die Produktzeilen der Bestellung werden auf den SalesOrder-Objekt- “Zeilen” -Parameter festgelegt, der ein Array von Bestellproduktzeilenobjekten als Parameter verwendet. Sie können beliebig viele Zeilen hinzufügen.

Schließlich wird der Verkaufsauftrag in Zeile 56 erstellt.

Alle API-Anforderungen sollten in eine Try-Catch-Klausel eingeschlossen werden. Die Web-Service-API generiert im Fehlerfall eine Ausnahme mit einer Fehlermeldung.

Weitere Lektüre

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

Combined Shape