DomusPro / Documentation

DomusPro Webservice documentation

DA: Alt tekst vedrørerende dokumentation er på engelsk

Services

The system is broken up into individual webservices with an WSDL file for each service. The authentification algorithm, and identifier system for the services are the same and is documented below.

Identifiers

The central root aggregate of the system is an Association (DA: Forening). Each association, has a unique id at DomusPro, but also has an External identifier. The External identifier, is the identifier in the system that call the webservice. The External identifier is mandatory when calling the webservice methods, whereas the DomusPro is not.

The External identifiers should be unique for the system calling the services.

Security and data integrity

Each call to the webservice must be called with a partner ID and a token. The partner ID is unique for each system, and can be requested by sending an e-mail to info@domuspro.dk. The token is a checksum calculated with the following rules

  • * Find all parameters in methods that are marked as "Included in token generation" and sort them alphanumerically
  • * For each parameter construct a string name:value (ex. identifier:abc)
  • * Concatenate all parameters with an underscore _
  • * Append the shared secret specific for the given PartnerID prefixed by an underscore _
  • * Generate a SHA1-checksum of the resulting string, and send is as the token parameter

Example

The documentation for the addFiles method in the Document service lists the following parameters as part of the token calculation

  • *partnerIdentifier
  • *domusProIdentifier
  • *externalIdentifier

Sorting theses gives (example values inserted for convenience)

  • *domusProIdentifier ('123')
  • *externalIdentifier ('abc')
  • *partnerIdentifier ('63b74aee-9852-4810-8c5b-98cea0188ebf')

If this partner has the shared secret kaffe, the resulting string will be

domusProIdentifier:123_externalIdentifier:abc_partnerIdentifier:63b74aee-9852-4810-8c5b-98cea0188ebf_kaffe

Which has sha-1 checksum 9bc91f747ae8bab012167faf949e25294df130f6 which should be used for the token generation

Simple PHP based example
		ini_set('soap.wsdl_cache_enabled', 0);
		$wsdl = 'http://ws.domuspro.dk/service/soap/domuspro.webservice/v2/document.wsdl';
		$client = new SoapClient($wsdl);

		$documentData = base64_encode(file_get_contents('../Fixtures/About Stacks.pdf'));

		$partnerId = '63b74aee-9852-4810-8c5b-98cea0188ebf';
		$domusProId = '123';
		$externalId = 'abc';
		$files = array(
			array(
				'filename' => 'test.pdf',
				'encodedData' => $documentData
			)
		);
		$token = generateToken($partnerId, $domusProId, $externalId);
		try {
			$res = $client->addFiles($partnerId, $token, $domusProId, $externalId, $files);
			print "Done!";
		} catch (SoapFault $e) {
			print 'Error: ' . $e->getMessage();
		}

		function generateToken($partnerId, $domusProdId, $externalId) {
			$sharedSecret = 'YOUR SECRET';
			$string = '';
			$string .= 'domusProIdentifier:' . $domusProdId . '_';
			$string .= 'externalIdentifier:' . $externalId . '_';
			$string .= 'partnerIdentifier:' . $partnerId . '_';
			$string .= $sharedSecret;
			return sha1($string);
		}