Versand Office API v0.2 documentation

Allgemeiner Aufbau

Der Webservice ist als SOAP 1.1 realisiert.

Produktion: https://www.versand-office.de/soap/gostnorm
Testing: https://dvl.versand-office.de/soap/gostnorm

Alle Requests müssen folgende Felder enthalten:

user 		=> muster@email.de
token 		=> 572a4e7a9a9b91dfd714149647a1f125a4cfca4a
time 		=> 1431339549
version 	=> 0.1
user: die registrierte Email Adresse.
time: der UNIX Zeitstempel zur zeit der Erstellung des Requests. Requests mit einem Stempel älter als 5min werden nicht akzeptiert.
token: ist ein SHA1 Hash generiert aus allen Feldern des Requests außer des Token Feld..

Algorithmus zur Hash Generierung

1. Alle Felder dem Namen nach alphabetisch sortieren
2. das token Feld entfernen
3. alle Felder durch ';' getrennt zusammenfassen
4. SHA1 auf apikeyfelderZeile anwenden.

Beispiel am VoidPickupRequest:

VOVoidPickupRequest{
	user 		=> muster@email.de
	token 		=> 1ec590bb17dd9f6fa9825b9c08bcc1bb0259d671
	time 		=>  1431340480
	version 	=> 0.1
	id 		=> 152
	errors 		=> NULL
}

1. Sortieren

errors 		=> NULL
id 		=> 152
time 		=> 1431340480
token 		=> 1ec590bb17dd9f6fa9825b9c08bcc1bb0259d671
user 		=> muster@email.de
version 	=> 0.1

2. Token Feld entfernen

errors 		=> NULL
id 		=> 152
user 		=> muster@email.de
time 		=> 1431340480
version 	=> 0.1

3. Zusammenfassen

;152;muster@email.de;1431340480;1.1

4. Hash bilden

sha1(abc123abc123;152;muster@email.de;1431340480;1.1) 
Resultat = 1ec590bb17dd9f6fa9825b9c08bcc1bb0259d671

Mögliche Antwort:

VOVoidResponse { 
	user*               => string(50) muster@email.de 
	token* 	=> string(40) 1e5782687e5d68a52024dc5523c8b7594480649a"
	time* 		=> int 1431328601
	success* 	=> bool true
	errors*     	=> array NULL 
}
success: auf true gesetzt falls es keine Fehler gab
errors: ein array mit Fehlermeldungen, NULL wenn keine Fehler vorliegen.

Genereller Ablauf

1. Adressen anlegen via VOAddressRequest.

Es müssen 2 Adressen im unseren System vorhanden sein.
Eine mit dem Typ:

VOAddressRequest::SEND_ADDRESS 		= 1 → Absenderadresse

Eine mit dem Typ

VOAddressRequest::DESTINATION_ADDRESS 	= 5 → Zieladresse

Falls eine Abholauftrag erstellt werden soll dann muss zusätzlich eine Adresse angelegt werden mit dem Typ:

VOAddressRequest::PICKUP_ADDRESS             	= 2 → Abholadresse

In der Antwort auf diese Anfragen ist ein ID Feld das für weitere Anfragen verwendet wird.
Diese IDs können für mehrere Anfragen verwendet werden.

2. Paketschein erstellen mit VOShipmentRequest

Nachdem die Adressen in Unserem System erfolgreich hinterlegt wurden können Paketscheine erstellt werden.

In der Antwort wird unsere interne ID des Pakets, die UPS TrackingNummer und die URL für den Paketschein zurückgegeben.

3. Abholauftrag erstellen mit VOPickupRequest

Die interne Paket ID kann zum erstellen eines Abholauftrags oder zur Stornierung verwendet werden.

VOLib

Zur Anbindung unseres Services wird eine Bibliothek in php zu Verfügung gestellt. Diese hat den hash algorithm und eine einfache Validierung der Anfragen und der Antworten implementiert.

Initialisierung der Bibliothek

require_once(dirname(__FILE__).'/VOLib.php'); 
define('ENVIRONMENT', 'development');// zum testen
apikey = 'abc123abc123'; 
url    	= 'https://www.versand-office.de/soap/gostnorm'; 

$voLib  = new VOLib(apikey, url);

Verwendung der Bibliothek

Anlegen einer Addresse

user                             	= 'muster@email.de'; 
address 				= new VOAddressRequest(user); 
address->company_name 			= 'Muster Firma'; 
address->contact_name 			= 'Muster Mann'; 
address->country           		= 'DE'; 
address->street                    	= 'Musterstr'; 
address->house_number        		= '12a'; 
address->additional_information    	= ''; 
address->postal_code              	= '10115'; 
address->city                      	= 'Berlin'; 
address->email                     	= 'muster@email.com'; 
address->phone_number        		= '9999999999'; 
address->type                      	= VOAddressRequest::SEND_ADDRESS; 

response = voLib->addAddress(address); 

absenderAdressId = response->id;

Weitere Methoden der Bibliothek

VOAddressResponse  addAddress(VOAddressRequest request) 
VOPickupResponse  requestPickup(VOPickupRequest request) 
VOShippmentResponse  createShipment(VOShipmentRequest request) 
VOVoidResponse  voidPickup(VOVoidPickupRequest request) 
VOVoidResponse  voidShipment(VOVoidShipmentRequest request)

Aufbau der Anfragen

VOAddressRequest

VOAddressRequest{
  	company_name* 		=> string(35) Muster Firma
  	contact_name*		=> string(35) Muster Mann
  	country* 		=> string(20) DE
  	street* 		=> string(35) Musterstr
  	house_number* 		=> string(5) 12a
  	additional_information 	=> string(35) 
  	postal_code* 		=> string(9) 10115
  	city* 			=> string(30) Berlin
  	email			=> string(50) muster@email.com
  	phone_number* 		=> string(15) 9999999999
  	type* 			=> int 1
  	user* 			=> string(50) a.mueller@laary.eu
  	token* 			=> string(40) 572a4e7a9a9b91dfd714149647a1f125a4cfca4a
  	time* 			=> int 1431339549
  	version* 		=> string(4)  0.1
  	errors*			=> array NULL				
}

* pflicht felder.

company_name: Firma oder Name des Empfängers
contact_name: Kontaktname
country: Land, als ISO2(DE) oder voller Name in Deutsch(Deutschland) oder Englisch(Germany)
street: Straße
house_number: Haus Nummer
additional_information: zusätzliche Information/Adresszeile
postal_code: Postleitzahl
city: Stadt
email: email addresse
phone_number: Telefon-Nummer
type: mögliche werte: 
VOAddressRequest::SEND_ADDRESS 		= 1 → absender Adresse
VOAddressRequest::PICKUP_ADDRESS        = 2 → abhol Adresse
VOAddressRequest::DESTINATION_ADDRESS 	= 5 → ziel Adresse

VOAddressResponse

class VOAddressResponse{ 
	id*        	=> int 903
	user*           => string(50) muster@email.de
	token*       	=> string(40) d19c87a1a2258d9c8ebae76fe717f44a5e97257c"
	time*        	=> int 1431328598
	success*       	=> bool true
	errors*		=> array NULL
}

* pflicht felder.

id: interne id der Adresse, zur späteren Verwendung beim erstellen der labels

VOShipmentRequest

VOShipmentRequest{ 
	send_address_id*        	=> int 100
    	destination_address_id* 	=> int 101
    	content                		=> string(35) Muster Ware
    	reference              		=> string(35) Muster Reference
    	weight ¹                  	=> int 6000
    	worth                  		=> int 600
    	insurance              		=> bool false
    	product*                	=> string (10) NES
    	user*                   	=> string(50) muster@email.de 
    	token*                  	=> string(40) f2b99b071d5352a110c185be1d24d8102ba01d6e 
    	time*                   	=> int 1431343739
    	version*                	=> string(4) 0.1 
    	errors*				=> array NULL 
}

* pflicht felder.
¹ verfügbar ab Version 0.2

send_address_id: interne id der absender Addresse
destination_address_id: interne id der ziel Addresse
content: agaben zum Inhalt der Sendung und ist bei internationalen Sendungen pflicht.
reference: Händler Referenz, wird auf dem Label abgedruckt
worth: Angaben zum Wert der Sendung, ist notwendig falls die Sendung zusatzversichert werden soll.
weight: Angaben zum Gewicht der Sendung in Gramm.

VOShippmentResponse

VOShippmentResponse{ 
  	id*          			=> int 100 
  	trackingNr*  			=> string 1Z0080RV6890740181
  	url*         			=> string  https://www.versand-office.de/send/label/100 
  	user*                   	=> string(50) muster@email.de 
  	token*       			=> string(40) 9aee5483133471616e056564fdeb8c541cf56ed9"
  	time*        			=> int 1431328600
  	success*     			=> bool true 
	errors*				=> array NULL
}

* pflicht felder.

id: interne id des erstellten Packets
trackingNr: UPS Packet Nachverfolgungs Nummer
url: url für das Label

VOPickupRequest

VOPickupRequest{ 
    	date*            	=> int 1431604800 
	from*            	=> string(4) 0900
	till*           	=> string(4) 1700 
	address_id*     	=> int 100 
	package_ids*  		=> array{ 
    		[0] 		=> int 100 
    		[1] 		=> int 101
	} 
	weight ¹ ² 			=> int 12000 
	count ¹ ²			=> int 5
	category ¹ 			=> int 1
	user*              	=> string(50) muster@email.de
	token*    			=> string(40) 5feea3e0f1f2d5c77b8ac2052a64154a11dd70c5 
	time*     			=> int 1431328601 
	version*     	        => string(4) 0.1
	errors*				=> array NULL 
}

* pflicht felder.
¹ verfügbar ab Version 0.2
² enweder count + weight oder eine liste von Paket ids.

date: abholdatum
from: abhol bereit ab
till: abzulholen bis
address_id: id der Abholaddresse
package_ids: ein Array mit ids der Packete die abgeholt werden sollen
weight: ungefährer Gesamtgewicht in Gramm der Sendungen der Abholung
count: Angabe der Anzahl der Sendungen die abgeholt werden sollen.
category: Angabe der Abholart, derzeit 1 → Standartversand.

VOPickupResponse

VOPickupResponse{ 
	id*     		=> int 102
	pickupNr*     		=> string 2929602E9CP
	user*                   => string(50) muster@email.de 
	token*    		=> string(40) 5feea3e0f1f2d5c77b8ac2052a64154a11dd70c5
	time*     		=> int 1431328601
	success*    		=> bool true
	errors*     		=> array NULL
}

* pflicht felder.

id: interne id des erstellten Abholauftrags
pickupNr: UPS Nummer des erstellten Abholauftrags 2929602E9CP

VOVoidShipmentRequest

VOVoidShipmentRequest{ 
    	id*            	=> int 23
	user*           => string(50) muster@email.de
	token* 		=> string(40) 1e5782687e5d68a52024dc5523c8b7594480649a" 
	time* 		=> int 1431328601 
	version*        => string(4) 0.1
	errors*		=> array NULL 
}

* pflicht felder.

id: interne id des erstellten Pakets

VOVoidResponse

VOVoidResponse { 
	user*           => string(50) muster@email.de 
	token* 		=> string(40) 1e5782687e5d68a52024dc5523c8b7594480649a"
	time* 		=> int 1431328601
	success* 	=> bool true
	errors*     	=> array NULL 
}

* pflicht felder.

VOVoidPickupRequest

VOVoidPickupRequest{ 
    	id*            	=> int 23
	user*           => string(50) muster@email.de
	token* 		=> string(40) 1e5782687e5d68a52024dc5523c8b7594480649a" 
	time* 		=> int 1431328601 
	version*        => string(4) 0.1
	errors*		=> array NULL 
}

* pflicht felder.

id: interne id des erstellten Abholauftrags 

VOVoidResponse { 
	user*           => string(50) muster@email.de 
	token* 		=> string(40) 1e5782687e5d68a52024dc5523c8b7594480649a"
	time* 		=> int 1431328601
	success* 	=> bool true
	errors*     	=> array NULL 
}

* pflicht felder.