Home

Integration Manual

1. ssssssssssccsssssssssssssccecsessessssssscesesssssssssssssssnseees 24 5 4 Returned parameters rcr roro eno enn neu uno noua ono na eo ou ra aura Fo Fa repara soa rana 25 5 5 Confirming tlie OLE c0ssseeninnsevssessvesnnnaesevssessveessnnasssssnesvseesnecesteoseresssereresneesen 27 5 6 D PE dDgg m a 27 5 7 EFRFOF COGO oor Deere trien Dres Deed Des Dens Deer deus venosa Dens Deva ven DeER EROR RaE 27 G WebServices serrer rere asa anaras aaa anasa aaar aaa riia S 29 6 1 Shipping API implementation sssssessssssssssssssssseeesssessssecesssseessseecessssessssssseeseese 29 6 1 1 REST a E E E T 29 6 12 Protocole starao vsse ei caine cemorenti tein reete conte iveueanvetessutecsenctoreagediiedateeshsatecsaberecasuevertene 29 Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 2 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Ge EMAC OUNE E er TREE o Acn 6 15 IVIL Validation bere eene erui aeta en inta pier va dev uas e do nM EEEREN OSEE ooi c wales tae ee eee es av ace Sees tae eee 6 7 3 Srat s COS rasa eres renasci tu cee O A EE E E E A 6 2 Create or Replace Order Web Service cssssssssssssscccccssssssssssssseceeessssssssss
2. The HTTP POST request must contain a Content type header field Attribute WETS HTTP Header Content type application vnd bpost shm order v2 XML In the body of the HTTP POST request you need to put the XML code describing the order Attribute Description HTTP Body XML lt order gt element Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 35 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual lt order gt element tags Name accountId Allowed Values c bpost Description Your unique customer ID of bpost P amp E orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info status value OPEN value PENDING value CANCELLED value COMPLETED value ON HOLD Order status costCenter This information is used on your invoice and allows you to attribute different cost centers orderLine The items that are included in the order Order lines are shown in the back end of the shipping manager and facilitate the use of the tool The subtags are explained in lt orderLine gt element tags customer C
3. Version 2 0 9 08 2012 11 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost B1 Create Order WS The web shop sends information to bpost via a secured web service B2 Validate The request is validated based on account ID security key and configuration B3 Save shipping data All relevant shipping information is saved in the bpost Back End Some information is returned to the web shop C1 Finish shipping data The customer logs into the Back End within the portal and adapts the shipping data Labels Track amp Trace etc can be managed C2 Create labels Labels are automatically generated by the bpost systems 3 4 3 Scenario 3 story line Below are the steps describing the process of scenario 3 the deep Front End and deep Back End integration A1 Setup After signing a contract the customer integrates the shipping application in a web shop A2 Configure The customer configures the admin panel of the shipping application according to the needs of the organization A3 Activate The customer is activated in the shipping manager B1 Create Order WS Optional The web shop sends information to bpost via a secured web service This information can be sent from the ERP or from the web shop B2 Validate The request is valid
4. lt xml version 1 0 encoding UTF 8 gt orderRefBarcodeMap xmlnsz http schema post be shm deepintegration v 2 entry orderReference 201106241506 orderReference barcode CD100000016BE barcode lt entry gt lt orderRefBarcodeMap gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 66 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual cl bpost 6 9 Retrieve PDF Labels For Box Web Service The Retrieve PDF Labels For Box web service retrieves printable barcodes in a PDF file This web service will retrieve both national and international labels 6 9 1 Operation To use the Retrieve PDF Labels For Box web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orders orderReference Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Retrieve Barcode as PDF URI is GET URI POST PUT GET DELETE serviceEndPoint accountId labels barcode pdf X X v X ATTENTION POST PUT and DELETE operations on a Retrieve PDF Labels For Box URI are prohibit
5. your web shop included in the hash Same as the extra parameters but hashed deliveryMethod Delivery method selected by the consumer deliveryMethodPriceDefault Default price of the selected delivery method deliveryMethodPriceOverride Price override of the selected delivery method deliveryMethodPriceTotal Total price of the selected delivery method Selected services if applicable for your integration Please refer to 8 APPENDIX Returned service information Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 26 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 5 5 Confirming the order It is recommended to confirm the order to bpost This will change the status of the order in the back end system allowing you to identify which orders have been paid and which remain pending bpost is not able to retrieve what happens between the selection of the delivery method and the actual payment of the order If the confirmation is not provided there is no difference between orders that were cancelled between the delivery step and the payment step which may lead to wrong deliveries To confirm the order a new http request should be performed with CO
6. 400px shmIFrame css top 50px 3 lt script gt A sample integration using php javascript and jquery is available upon request Please contact shippingmanager bpost be if you are interested in receiving this information 5 4 Returned parameters The following table lists the parameters that are returned by the shipping manager to the web shop when the consumer clicks the Confirm button The address information that will be returned in the parameters is the chosen delivery address Name Allowed Values Description orderReference Max length 50 Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info costCenter Max length 50 This information is used on your invoice and allows you to attribute different cost centers e g different shops warehouses suppliers orderTotalPrice Euro cents Total price of the basket order in Euro cents excluding shipping costs customerFirstName First name of the customer Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 25 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpos
7. DE German settings of your browser Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 18 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost checksum Required No SHA 256 hash Checksum of fields See 5 1 2 Checksum orderReference Required Yes Max length 50 Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info costCenter Optional Yes Max length 50 This information is used on your invoice and allows you to attribute different cost centers e g different shops warehouses suppliers orderTotalPrice Optional No Euro cents Total price of the basket order in Euro cents excluding shipping costs customerFirstName Optional No First name of the customer customerLastName Optional No Last name of the customer The first name and the last name together should not be longer than 40 characters Only 40 characters are shown on the label customerCompany Optional No Max length Name of the company of the receiver customerStreet Op
8. V Dont show order reference Dont show prices of 0 EUR Back to shop overview 1 In the General Settings tab make sure the following fields are filled in Confirm URL in this field key in the URL of the confirmation web page on the web Error URL Cancel URL Passphrase shop This is the web page that will be shown to the consumer after he has clicked the Confirm button in the Front End pop up This page will receive all HTTP POST parameters described in the next section in this field enter the URL of the error web page on the web shop This screen is shown when an error occurs in this field enter the URL of the cancel action that the web shop provides It will be shown when the consumer clicks the Back to shopping button on the Front End pop up in this field key in the password that will be used for generating the security hash Please modify the default value of this field and by Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 16 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost preference use a password that contains a combination of letters and numbers and has at least 10 characters in length 2 Click the Delivery Methods tab 999009 Marketing Demosh
9. deliveryMethod gt lt order gt lt orderInternationalLabelInfos gt Server Response If your request to create an order and a national label is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server response will contain a Content type header field Attribute Value HTTP Header Content type application vnd bpost shm orderAndIntLabels v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 65 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost In the body of the server response you will receive XML code containing the order and label element Attribute Description HTTP Body XML orderRefBarcodeMap element lt orderRefBarcodeMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info barcode Bar code Example The following example shows a response confirming that the label was created successfully HTTP 1 1 200 OK Content type application vnd bpost shm orderAndIntLabels v2 XML
10. e En a eE AaS Me aqu mme pde Mee ME EA dde 6 8 2 Creating an order and an international label sesesee eene 6 9 Retrieve PDF Labels For Box Web Service ceeeee e eere eee ee eene nnn 6 9 1 OPO ATION eee E 6 9 2 Retrieving a PDF label for a DOX csscssssscsscessecssccsseeecssecssnsecssccessseseseecesssssneceesnes 6 10 Retrieve PDF Labels For Order Web Service eeeeee eee eere nnne 6 10 1 OperatiO Merss eene esaet eade EEA Yea ea Dee nea Pene Yea ea Hee add bende YER PY HE RE Pes DER SVER SERRE 6 10 2 Retrieving PDF labels for an order enne enne 7 shm deep integration v2 Xsd scccccssssssssssccscsssssssssssececssssssssssnscesessssssssssssssnseses 8 APPENDIX Returned service information eeeeeeee creen eene eene nennt 8 1 bpack home regular delivery eeeeeeee eese eee eee eene ener nnns 8 2 bpack bpost pugo delivery 4 esee eee eere eene nennen nennt 8 3 bpack 24 7 Parcels depot delivery eeeese seres eee en eene 8 4 bpack business bpack BUSINESS delivery eese eere eere 8 5 bpack express bpack EXPRESS delivery eeeeee esee 8 6 Sample code to retrieve parameters eeeeeee eese e eene rennen nenne eene nnnn nunt Co
11. insurance The subtags are explained in lt deliveryMethod gt lt intExpress gt lt insured gt element tags lt deliveryMethod gt lt intExpress gt lt insured gt element tags Name Allowed Values Insurance tag Description One of the subtags that are used under the lt insurance gt tag See lt insurance gt element tags options For the options subtags see Additional services lt options gt element tags Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 39 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual I f bpost deliveryMethod intBusiness element tags Name Allowed Values Description insured International Business insurance The subtags are explained in lt deliveryMethod gt lt intBusiness gt lt insured gt element tags lt deliveryMethod gt lt intBusiness gt lt insured gt element tags Name Allowed Values Description Insurance tag One of the subtags that are used under the lt insurance gt tag See lt insurance gt element tags options For the options subtags see Additional services lt options gt element tags Additional services lt options gt eleme
12. lt xs complexType gt lt xs element gt lt xs choice gt lt xs complexType gt value 1 gt value 2 gt value 3 gt value 4 gt value 5 gt value 6 gt value 7 gt value 8 gt value 9 gt value 10 gt value 11 gt xs complexType name signatureType gt lt xs choice gt lt xs element name signature gt lt xs complexType gt lt xs element gt lt xs element name signaturePlus gt lt xs complexType gt lt xs element gt lt xs choice gt lt xs complexType gt xs complexType name optionsType gt lt xs sequence gt lt xs element name infoDistributed type notificationType minOccurs 0 gt lt xs element name infoNextDay type notificationType minOccurs 0 gt lt xs element name infoReminder type notificationType minOccurs 0 gt lt xs element name automaticSecondPresentation minOccurs 0 gt lt xs complexType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs complexType name orderLineType gt lt xs sequence gt lt xs element name text type xs string gt lt xs element name nbOflitems type xs int minOccurs 0 gt lt xs sequence gt lt xs complexType gt lt xs complexType name labelsType gt lt xs sequence gt lt xs element name barcodes type barcodeType gt lt xs element ref pdf gt lt xs sequence gt Confidential Copyright 2011 by b
13. Express bpack EXPRESS VISIBLE 10000 bpack BUSINESS bpack World bpack BUSINESS INVISIBLE Parcels depot bpack 24 7 Parcels depot VISIBLE 4500 Pugo bpack bpost Pugo GREYED OUT Regular bpack home Regular VISIBLE 5400 The deliveryMehodsOverrides parameter can be sent multiple times Every variable will be interpreted separately ATTENTION The deliveryMethodOverrides fields must be included in the checksum hash See the table in section 5 1 1 HTTP POST parameters and the explanation of the checksum generation below in section 5 1 2 Checksum The parameters need to be send in alphabetical order within the checksum in order to prevent a 2000 error 5 2 Sending parameters via HTTP POST The link between your web shop and the shipping manager Front End has to be established on the page where you offer the consumer the possibility to choose the delivery method Into that HTML page you need to integrate a form with hidden HTML fields containing the parameters listed above Send the parameters and the checksum to the Front End at the following URL https shippingmanager bpost be ShmFrontEnd start Use an HTML form with a POST method and the URL in the action attribute The following example shows you the HTML code to achieve this form id myForm method POST target shmFrame action https shippingmanager bpost be ShmFrontEnd start gt lt form gt Confidential Copyright 2011 by bpost All rights reserved Ve
14. element name privateAddress type xs boolean gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name internationalLabelinfos gt lt xs complexType gt xs sequence lt xs element maxOccurs unbounded ref internationalLabelInfo gt lt xs element name orderReference type xs string gt lt xs element name returnLabels type xs boolean gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderInternationalLabelInfos gt lt xs complexType gt xs sequence lt xs element maxOccurs unbounded ref internationalLabelInfo gt lt xs element ref order gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderWithBarcodes gt lt xs complexType gt xs sequence lt xs element ref order gt lt xs element maxOccurs unbounded minOccurs 0 name barcode type barcodeType xs sequence xs complexType xs element lt xs schema gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 82 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost 8 APPENDIX Returned service information This chapter contains an overview of all additional informatio
15. emptive Authentication over a secure channel HTTPS This means the server will expect the Authorization header to be sent along with the request The value of this header is the authorization type Basic followed by the e tailer s external Id concatenated with a colon and an at least 128 bits pass phrase that will be communicated upon agreement with the external party This concatenated value must be encoded in base64 before being actually set in the Authorization header Authorization Basic External Id pass phrase Where the underlined value is encoded in Base64 The External Id is the e tailer s Account ID For example the Authorization Header for an e tailer having the following attributes External ID Etaileri Pass Phrase QuiteLongPassPhrase Should generate an Authentication header and value string like Authorization Basic RXRhaWxlcjEGUXVpdGVMb25nUGFzciBocmFzZQ In case the call on the Web Service cannot be authenticated due to a missing or incorrect Authentication header the caller of the Web Service will receive a response having an HTTP code 401 and an HTML body containing information similar to the example below HTTP 1 1 401 Unauthorized Server Apache Coyote 1 1 Pragma No cache Cache Control no cache Expires Thu 01 Jan 1970 01 00 00 CET WWW Authenticate Basic realm rest realm Content Type text html charset utf 8 Content Length 948 Date Wed 27 Apr 2011 14 33 36 GMT Connection close htm
16. http schema post be shm deepintegration v2 gt lt accountId gt 123456 lt accountId gt lt orderReference gt 201106241506 lt orderReference gt lt status gt OPEN lt status gt lt costCenter gt costCenter0 lt costCenter gt lt orderLine gt lt text gt Iphone 4 16GB Black lt text gt lt nbOfiItems gt 1 lt nbOfItems gt lt orderLine gt lt orderLine gt lt text gt Earphones lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt customer gt lt firstName gt Jan lt firstName gt lt lastName gt Peeters lt lastName gt lt deliveryAddress gt lt streetName gt Dorpsstraat lt streetName gt lt number gt 132 lt number gt lt box gt lt box gt lt postalCode gt 1800 lt postalCode gt locality gt Vilvoorde lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt email gt jan peeters provider be lt email gt lt phoneNumber gt 0032499123456 lt phoneNumber gt lt customer gt lt deliveryMethod gt lt atHome gt lt normal gt lt atHome gt lt deliveryMethod gt lt totalPrice gt 66490 lt totalPrice gt lt order gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 42 87 bpost shipping manager Integration Manua
17. the shipping application according to the needs of the organization A3 Activate The customer is activated in the shipping manager B1 Request to show The web shop sends out a secured request to show to front end UI B2 Validate The request is validated based on account ID security key and configuration B3 Show front end The front end is shown to the consumer on the web shop B4 Select shipment The consumer selects the most convenient shipment method B5 Save shipping data All relevant shipping information is automatically saved in the bpost Back End Some information is returned to the web shop B6 Confirm Order WS URL redirection Optional The web shop confirms the order after payment step via web service C1 Finish shipping data The customer logs into the Back End within the portal and adapts the shipping data Labels Track amp Trace etc can be managed C2 Create labels Labels are automatically generated by the bpost systems 3 4 2 Scenario 2 story line Below are the steps describing the process of scenario 2 the deep Front End and easy Back End integration A1 Setup After signing a contract the customer integrates the shipping application in a web shop A2 Configure The customer configures the admin panel of the shipping application according to the needs of the organization A3 Activate The customer is activated in the shipping manager Confidential Copyright 2011 by bpost All rights reserved
18. v2 XML lt xml version 1 0 encoding UTF 8 gt pdf xmlnsz http schema post be shm deepintegration v2 JVBERiOxLjQKJeLjz9MKMyAwIG9iaiA8PC9 GaWxOZXIvRENURGVjb2RILTRBcGUvWESiamVj dC9MZW5ndGggMzAyMS9CaXRzUGVyQ29tcG9uZW 50IDgvSGVpZ2h0IDMxLONvbG9yU3B hY2UvRGV2aWNIUkdCL1N1YnR5cGUvSW1hZ2UvV2lkdGggMzk2Pj5zdHJIYWOK 9j A4AAQS Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 68 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual cl bpost kZJRgABAgAAAQABAAD 2WBDAAgGBgcGBQgHBwcJCQgKDBQNDASLDBKkSEWw8UH RofHhO aHBwgJC4nICIsIxwcKDcpLDAxNDQOHyc5PTgyPC4zNDL 2wBDAQkJCQWLDBgNDRgyIRwh MjlyMjlyMjlyMjlyMjlyMjlyMjlyMjlyMjly MjlyMjlyMjlyMjlyMjlyMjlyMjlyMjL wAARCAAfAYw DASIAAhHEBAXEB 8QAHWAAAQUBAQEBAQEAAAAAAAAAAAECAWOFBgCcICQOL 8QAtRAAAG EDAWIEAWUFBAQAAAF9AQIDAAQRBRIHMUEGE1FhByJxFDKBkaEIIOKxwRVSOfAKM2Jyggk KFhcYGRoUicoKSoONTY3ODk6QORFRkdISUpTVFVWV1hZWmNKkZWZnaGlqc3R1dnd4eXqD hIWGhA4BDipKTIWWl5iZmqKjpKWmpe6ipqrKztLW2t7ibusLDxMXGx8jJytL T1 NXW 19jZ2uHi4 T I5ufo6erx8vP09fb3 Pn6 8QAHWEAAWEBAQEBAQEBAQAAAAAAAAECAWOQFBgcICQoL 8 pdf Depending on the format you specified in the URL the requested labels are printed on an A4 page with up to 4 labels on one page or separately on A5 pages The labels you will recei
19. will be sent regularInfoNextDayNotificationType e mail SMS Type of notification that will be used to send the Info Next Day message regularInfoNextDayNotificationValue String If type SMS gt Phone number If type e mail gt e mail address regularInfoDistributedLanguage EN NL FR DE Language in which the Info Distributed message will be sent regularInfoDistributedNotificationType e mail SMS Type of notification that will be used to send the Info Distributed message regularInfoDistributed NotificationValue String If type SMS gt Phone number If type e mail gt e mail address regularBasicInsurance Integer Value in eurocent of the Basic Insurance cost Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 83 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost Values in bold are values that may be set by the customer while choosing his her delivery method in case the option is set as visible All other values are default values that are set up by using the Delivery method screen in the admin part of the administrative back end They will need to have the value Not visible selected by default This is s
20. 2012 44 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 6 3 Fetch Order Web Service The Fetch Order web service retrieves an order by its orderReference If there are multiple orders that match the provided orderReference only the most recent order that was not cancelled is returned Barcodes that are attached to the requested orderReference will be returned 6 3 1 Operation To use the Fetch Order web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orders orderReference Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Fetch Order URI is GET URI POST PUT GET DELETE serviceEndPoint accountId orders orderReference X X iil X ATTENTION POST PUT and DELETE operations on a Fetch Order URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 3 2 Fetching an order When you want to fetch an order you need to send a request to the server to receive order information using the HTTP GET operation on the URI We will now
21. 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost The HTTP GET request must contain an Accept header field Attribute HTTP Header Accept application vnd bpost shm pdf v2 XML The body of the GET request will be empty because there is no XML code that needs to be sent to the server Attribute Description HTTP Body empty Example The following example shows a valid request to retrieve a barcode as PDF GET shm 123456 labels 323212345659900000001030 pdf Accept application vnd bpost shm pdf v2 XML Server Response If your request to retrieve a barcode as PDF is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server response will contain a Content type header field Attribute HTTP Header Content type application vnd bpost shm pdf v2 XML In the body of the server response you will receive XML code containing the PDF element Attribute Description HTTP Body XML lt pdf gt element Example The following example shows a response by the server giving you the barcode as PDF The PDF file will be encoded in base64 Only a part of the code is shown here as an example HTTP 1 1 200 OK Content type application vnd bpost shm pdf
22. Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 3 3 Four integration solutions bpost offers an easy integration and a deep integration solution for both the Front End and the Back End parts of the shipping manager which makes a total of four integration solutions In Figure 3 an overview of the four integration solutions is provided FRONT END BACK END One page integration Shipping interface URL re direct cfr Visa payment Fulfil orders in the bpost portal Follow up track amp trace Easy print amp barcode generation Allows the consumer to choose the most convenient delivery option 2 i ie o S Front end web services Back end web services 5 Deep integration e shop Deep integration in ERP systems No URL re direct or pop up No portal login Create orders after payment of sell Webservice technology Figure 3 Four integration solutions 3 3 1 Front End easy integration The easy integration of the Front End is implemented via a URL re direct similar to popular payment services On this re direct page the consumer can choose the most convenient delivery option Go to the chapter Front End Easy Integration to read the details of how to implement this integration solution 3 3 2 Back End easy integration The easy integration of the Back End i
23. Integration Manual A bpost array array depotSignature depotAdditionalInsuranceInsuranceRange depotInfoDistributedLanguage depotInfoDistributed NotificationT ype depotInfoDistributedNotificationValue depotBasicInsuranc e elseif _REQUEST deliveryMethod bpack BUSINESS array array businessAdditionallnsuranceInsuranceRange businessBasicInsurance elseif _REQUEST deliveryMethod bpack EXPRESS lt array array expressAdditionalInsuranceInsuranceRange expressBasicInsurance y foreach array as field if isset _REQUEST field if REQUEST field echo field REQUEST field lt br gt selse echo field was selected lt br gt Ex Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 87 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1
24. NFIRM as value in the action field Please refer to 5 1 1 HTTP POST parameters for more information on how to send the parameters It is also possible to confirm or cancel an order by using web services Please refer to chapter 6 4 Modify Order Status Web Service 5 6 Backup solution bpost recommends clients to create a backup solution in order to be able to offer a delivery method to their customers in case the shipping manager fails to respond If the web shop executes an HTTP request but the shipping manager doesn t respond it is recommended that the web shop show a standard form with fields in which the customer can enter the delivery address There will be no loss of information and it is possible to manually insert the information into the bpost systems 5 7 Error codes When the request sent to open the redirect page is invalid an error code will be shown The table below lists the error codes Error Code Refers to Description 1110 orderReference Required Order reference is required but it hasn t been supplied 1140 customerCountry Required Customer country code is required but it hasn t been supplied 1210 orderReference Format error Order reference is too long 1211 orderTotalPrice Format error Order total prince contains invalid integer must be in eurocent 1212 costCenter Format error Order cost center is too long 1220 orderLine Format error Order line has invalid format 1221 orderLine For
25. TF 8 gt lt orderWithLabelAmount xmlnsz http schema post be shm deepintegration v 2 gt lt order gt lt accountId gt 123456 lt accountId gt lt orderReference gt 201106241506 lt orderReference gt status OPEN status lt costCenter gt costCenter0 lt costCenter gt lt orderLine gt lt text gt Iphone 4 16GB Black lt text gt lt nbOfiItems gt 1 lt nbOfItems gt lt orderLine gt lt orderLine gt lt text gt Earphones lt text gt lt nbOfiItems gt 1 lt nbOfItems gt lt orderLine gt lt customer gt lt firstName gt Jan lt firstName gt lt lastName gt Peeters lt lastName gt lt deliveryAddress gt lt streetName gt Dorpsstraat lt streetName gt lt number gt 132 lt number gt lt box gt lt box gt lt postalCode gt 1800 lt postalCode gt lt locality gt Vilvoorde lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt email gt jan peeters provider be lt email gt lt phoneNumber gt 0032499123456 lt phoneNumber gt lt customer gt lt deliveryMethod gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 60 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost atHome atHome lt deliveryMethod gt lt or
26. TP Body XML lt orderRefLabelAmountMap gt element lt orderRefLabelAmountMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info labelAmount Amount of labels withRetour true Flag indicating whether return labels are false included When using the withRetour element set to true the sender address and receiver address are switched This is only possible for home delivery In case the person using the retour label has chosen a delivery method with an address not set as his home address e g shop or Bpack 24 7 the address cannot be used for the retour label Therefore it is currently not possible to generate a retour label for those shipments returnLabels 0 Flag indicating whether labels are returned 1 O no l yes Example The following example shows a valid request to create a national label POST shm 123456 labels Content type application vnd bpost shm nat label v2 XML lt xml version 1 0 encoding UTF 8 gt lt orderRefLabelAmountMap xmlnsz http schema post be shm deepintegration v 2 entry orderReference 201106241506 orderReference lt labelAmount gt 4 lt labelAmount gt withRetour false withRetour lt returnLabels gt 0 lt returnLabels gt lt ent
27. The HTML code below show an iframe with the name shmFrame which is the same as the target we used in the HTML code for the form above Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 24 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt iframe id shmFrame name shmFrame width 790 height 520 style border none gt lt iframe gt The code example below shows one method to implement the iframe in a pop up By using CSS it is also possible to modify the div attributes allowing for instance a lightbox pop up integration The script example only works when the jquery plugin is installed Another solution is to unfold the iFrame when a radio button is selected with the iFrame completely integrated so no pop up div id showme gt iframe id shmIFrame name shmFrame width 0 height 0 gt lt iframe gt lt div gt lt script gt logobpost click function 4 myForm submit shmIFrame attr width 800 shmIFrame attr height 600 shmIFrame css position absolute shmIFrame css z index 500 shmIFrame css width 800px shmIFrame css left 50 shmIFrame css margin left
28. WS Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 14 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost 4 General configuration Setup This chapter describes the general setup configuration that is required to use the bpack Shipping Manager This setup has to be followed for all different types of integrations Before using the bpack Shipping Manager it is required to set up your account in the Back End by logging into the bpost portal and configuring the settings in the Back End Shipping interface For instructions on how to use the Shipping interface please read the bpack Shipping Manager user guide 4 1 Logging in Open an internet browser and go to the bpost portal at the following URL https www bpost be portal login Customer service Help NL FR DE EN G bpost B eShop Access your bpost e services by signing in to the Business Portal New user Discover the bpost e services or get directly started by clicking on one of the links below EE EEE EES r usemame evcccece Choose the language enter your Account ID and password and click the Sign in button to login 4 2 Configuration After logging in all active e services on the bpost portal are show
29. When you want to create an international label you need to send the international label information to the server using the HTTP POST operation on the URI We will now show you how to send a valid request to create an international label and what the response of the server will look like Client Request Use the HTTP POST request method to send the international label information to the server The label information needs to be sent to one of the following URL Attribute VEIG HTTP Operation POST URL https api bpost be services shm accountId labels International labels will be printed on an A4 page One A4 page can fit 4 labels The HTTP POST request must contain a Content type header field Attribute HTTP Header Content type application vnd bpost shm int label v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 55 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost In the body of the HTTP POST request you need to put the XML code containing the international label information Attribute Description HTTP Body XML lt internationalLabelInfos gt element lt internationalLabelInfos gt element tags Name Allowed Values Description internationalLabelInfo F
30. abel and what the response of the server will look like Client Request Use the HTTP POST request method to send the national label information to the server The label information needs to be sent to one of the following URLs HTTP Operation POST URL https api bpost be services shm accountId labels URL https api bpost be services shm accountId labels labelFormat A_4 URL https api bpost be services shm accountId labels labelFormat A_5 By default labels requested using the first URL will be printed on an A4 page Labels requested using the second URL with the labelFormat A_4 specification will also be printed on an A4 page One A4 page can fit 4 labels If you want to print each label separately on its own A5 size page you need to use the labelFormat A_5 specification in the URL Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 52 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual a f bpost The HTTP POST request must contain a Content type header field Attribute HTTP Header Content type application vnd bpost shm nat label v2 XML In the body of the HTTP POST request you need to put the XML code containing the label information Attribute Description HT
31. arcodeMap xmlnsz http schema post be shm deepintegration v 2 entry orderReference 201106241506 orderReference barcode 323212345659900000001030 barcode entry lt orderRefBarcodeMap gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 54 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 6 6 Create International Labels Web Service The Create International Labels web service creates new international labels 6 6 1 Operation To use the Create International Labels web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId labels Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Create International Labels URI is POST URI POST PUT GET DELETE serviceEndPoint accountId labels v X X X ATTENTION PUT GET and DELETE operations on a Create International Labels URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 6 2 Creating an international label
32. as described in the next sections of this document If this is not the case the Web Service will not execute and the same response having HTTP code 401 as the example already provided above will be sent back 6 1 7 Status Codes HTTP based REST leverages the use of standard status codes e 4xx client error status codes are used to map internal Functional Exceptions The request can not be completed due to for example a conflict with the state of the resource trying to confirm an order that has previously been cancelled or trying to open an order referencing a product that doesn t exist in the catalog anymore Another characteristic for these exceptions is that they can usually be solved by changing the content of the request the web service Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 32 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost e 5xx server error status codes are used to map internal Technical Exceptions The request can not be completed due to an unexpected condition on the server side For example a failure connecting to the database or master data not being present in the database can be categorized as technical exceptions Functional Exceptions If the Web Service call encoun
33. ated based on account ID security key and configuration C1 Create Labels WS All relevant information to create a box is sent to the bpost systems via a secured web service The e tailer is able to ask a set of data labels barcode etc C2 Send label If requested automatic generated labels are returned to the e tailer instantly They can be saved or directly printed Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 12 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost 3 4 4 Scenario 4 story line Below are the steps describing the process of scenario 4 the easy Front End and deep Back End integration A1 Setup After signing a contract the customer integrates the shipping application in a web shop A2 Configure The customer configures the admin panel of the shipping application according to the needs of the organization A3 Activate The customer is activated in the shipping manager B1 Request to show The web shop sends out a secured request to show to front end UI B2 Validate The request is validated based on account ID security key and configuration B3 Show front end The front end is shown to the consumer on the web shop B4 Select shipment The consumer selects the most conv
34. aw Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 6 7 Create Order And National Labels Web Service The Create Order And National Labels web service creates an order and a certain amount of national labels in one call 6 7 1 Operation To use the Create Order And National Labels web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orderAndLabels Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Create Order And National Labels URI is POST URI POST PUT GET DELETE serviceEndPoint accountId orderAndLabels I X X X ATTENTION PUT GET and DELETE operations on a Create Order And National Labels URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 7 2 Creating an order and a national label When you want to create an order and a national label you need to send the order and label information to the server using the HTTP POST operation on the URI We will now show you how to send a valid request to create an order and a national label and what the response of the s
35. bpost bpost shipping manager Integration Manual Version 2 0 Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 1 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Table of Contents 1 Application MOGifiCAatiONS ccsssssscecccsssssssssseccecsssssssssssesesssessssssssssnnseeeesessesenas 2 Glossary of TONIMS visissscicscdcccicssicccscccscecisoseescececesssdsosecscocicesevssasaseasisessscesaisesesesescea eas 3 Introduction cr nasasa er ERE IER ER a aaa Anarai apa eraai anaa saiia 3 1 Required knowledge 0sissscecccseececesssesennceosseeessvasenncansiesessvebennnsnescecriesesavenetteeseiaeess 3 2 bpack Shipping Manager solution eeee ecce eene ee eee nnnn Be2ee FROME EMG Rc Bi2e2 BACK EMO m T 3 3 Fourintegration SOLUTIONS 1 scccesssesssnsecerscessvessnnsacevecessvenennnansveesessseserenesnecsesseees 3 3 1 Front Erid easy integrati M s reeeo a y eng nce rene ee EUER Eo ee EEA EEEE 3 3 2 Back End easy integration cccccccssecsscesssecseseecsecseeeeesaeceeeecssecseeesesueceeeeeesaeseeeeseaaeees 3 3 3 FrontEnd deep integration roce e rtr rre ED rss o ex vu Ee Y RR EYE v Eua a 3 3 4 BackEnd deep Integkatloh esoe sia er eert
36. curs 0 type xs boolean gt lt xs sequence gt lt xs complexType gt lt xs element name order gt lt xs annotation gt lt xs documentation gt Comment describing your root element lt xs documentation gt lt xs annotation gt lt xs complexType gt xs sequence lt xs element name accountId type xs string gt lt xs element name orderReference type xs string gt lt xs element namez status type orderStatusType gt lt xs element name costCenter minOccurs 0 type xs string gt lt xs element name orderLine minOccurs 0 maxOccurs unbounded type orderLineType lt xs element name customer gt lt xs complexType gt xs sequence lt xs element name firstName Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 77 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 40 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name lastName gt lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 40 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element namez deli
37. d against the XSD file defined in chapter 7 shm deep integration v2 xsd of this document the service is executed and a response will be sent back to the caller In case the request contains an invalid XML the following response should be expected by the caller of the service HTTP 1 1 400 Bad Request Server Apache Coyote 1 1 Content Type application vnd bpost shmXMLSchemaValidationException v1 XML Content Length 461 Date Wed 27 Apr 2011 14 28 24 GMT Connection close lt xml version 1 0 encoding UTF 8 standalone yes gt lt ns2 xsdValidationException xmlInsz http schema post be common exception v 1 xmins ns2 http schema post be api shm common v1 lt message gt cvc complex type 2 4 a Invalid content was found starting with element tns statusDate One of Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 30 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost amp quot http schema post be api galactic order v1 amp quot statusValue is expected message timestamp 2011 04 27 4 02 00 timestamp lt ns2 xsdValidationException gt 6 1 6 Security Authentication Authentication is performed by the Server hosting the Web Services We use pre
38. d on an A4 page with up to 4 labels on one page or separately on A5 pages The labels you will receive as PDF will look like this Exp diteur Afzender AutoShop Hasseltweg Paquet Pakket Paket 3600 Genk P l 323203690859900000001040 Dany De Backere Elisabethlaan 3 28 2600 Berchem Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 72 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 7 shm deep integration v2 xsd lt xml version 1 0 encoding UTF 8 gt lt edited with XMLSPY v2004 rel 2 U http www xmlspy com by Jan Wilmaers Belgian Post Group gt lt xs schema xmlns xsz http www w3 0rg 2001 XMLSchema elementFormDefault qualified attributeFormDefault unqualified targetNamespace http schema post be shm deepintegration v2 xmins http schema post be shm deepintegration v2 xmins exception http schema post be common exception v1 gt lt xs import schemaLocation Exception xsd namespace http schema post be common exception v1 gt lt xs complexType name SHMBusinessExceptionInfo gt lt xs complexContent gt lt xs extension base exception BusinessExceptionInfo gt lt xs complexContent gt lt xs complexType gt lt xs complexT
39. de real time data transfer between the e tailer back end systems and bpost The web services of the deep integration allow e tailers to integrate all shipping and labelling management in their ERP systems or back office applications It is not required to login into the shipping interface hosted on the bpost portal The same technology as the easy integration is made available as web services which means it is 10096 transparent Go to the chapter Web Services to read the details of how to use the web services to implement the deep integration of the Back End 3 4 Four integration scenarios With the four integration solutions i e easy and deep integration of Font End and Back End bpost offers four combinations of the solutions as possible scenarios you can deploy in your e business Below we list the features and characteristics of each scenario Scenario 1 easy Front End and easy Back End e Show different and up to date delivery methods in the checkout process via the bpost frame perfectly integrated into the look amp feel of the webshop e Information automatically stored in the bpost Back End e Fulfil orders and print labels via the bpost Shipping interface e Optional Confirmation call after payment via Web Service Scenario 2 deep Front End and easy Back End e Only use one delivery method bpack home and create orders directly after payment by consumer via web services e Store information in the bpost Back End e Fulfil o
40. der gt lt labelAmount gt 4 lt labelAmount gt lt orderWithLabelAmount gt Server Response If your request to create an order and a national label is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server response will contain a Content type header field Attribute Value HTTP Header Content type application vnd bpost shm label v2 XML In the body of the server response you will receive XML code containing the order and label element Attribute Description HTTP Body XML lt orderRefBarcodeMap gt element lt orderRefBarcodeMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info barcode Bar code Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 61 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Example The following example shows a response confirming that the label was created successfully HTTP 1 1 200 OK Content type application vnd bpost shm label v2 XML lt xml versio
41. e The Create Order web service creates a new order If an order with the same orderReference already exists this service will act as a Replace Order web service which cancels the existing order and creates a new one with the same orderReference 6 2 1 Operation To use the Create Order web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orders Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Create Order URI is POST URI POST PUT GET DELETE serviceEndPoint accountId orders M X X X ATTENTION PUT GET and DELETE operations on a Create Order URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 2 2 Creating an order When you want to create an order you need to send the order information to the server using the HTTP POST operation on the URI We will now show you how to send a valid request to create an order and what the response of the server will look like Client Request Use the HTTP POST request method to send the order information to the server The order information needs to be sent to the following URL Attribute VELG HTTP Operation POST URL https api bpost be services shm accountId orders
42. e application vnd bpost shm order v2 XML In the body of the server response you will receive XML code containing the orderWithBarcodes element Attribute Description HTTP Body XML lt orderWithBarcodes gt element The lt orderWithBarcodes gt element will contain the order and if they have been created the barcodes attached to the order lt orderWithBarcodes gt element tags Name Allowed Values Description order lt order gt element tags are explained in 6 2 Create or Replace Order Web Service barcode Barcode If barcodes are not yet attached the element will not be included Example The following example shows a response by the server for a Bpback bpost PUGO order HTTP 1 1 200 OK Content type application vnd bpost shm order v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 46 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt xml version 1 0 encoding UTF 8 gt orderWithBarcodes xmlnsz http schema post be shm deepintegration v2 order accountId 123456 accountId orderReference 201106241506 orderReference status OPEN status lt costCenter gt costCenter0 lt costCenter gt
43. e not found 1311 N A Data error Order is not in the correct state must be Pending 1320 customerCountry Data error Customer country code is not correctly configured in back end 2000 N A Security error Access denied authentication failed This can be due to a miscalculation of the checksum value of the required fields a wrong identifier or a wrong password common error usage of bpost portal login instead of Shipping Manager passphrase Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 28 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 6 Web Services In this chapter we discuss the Shipping API that is used to implement the deep integration of the Front End and the Back End This document describes version 2 of the web services For older versions of the web services please read previous versions of this document 6 1 Shipping API implementation 6 1 1 REST REpresentational State Transfer REST software architecture style is used to expose shipping manager resources as services to the external parties of bpost 6 1 2 Protocol Although REST is an architectural style which is not bound to a particular technology in practice the HTTP architecture is used Web Services
44. e teen xeu E E s e ema eee eeu 10 3 4 Four integration scenarios eeeeee eese eee eene eene eene eene nnns nnns nnns nnn 10 341 Scenario T Story linhes a a aiae de FR x p eR KR BUE run REY ERR Re 11 3 442 Scenario 2 story line ia esc sicot eia sero aao eorr HR pd DY anii et Pra R Eon 11 34 3 Scenario 3 Stry lle aciei soci shores eed iier rp aute xr enano a Vk Use FE etre ag Ra 12 34 4 Scenario 4 story lie oisi em irre e vec Ree neo rv da v e a a 13 3 5 JICTlImpact osoesanociodonnOpOO ORI RIEGO RO inem Dn ORE Ire 14 4 General configuration Setup eeeeee seres eene en eene nennen rinse rna sa estas estan sn 15 4 1 Logging Ifc coe oe n rer rn ro koh EEEIEE NEEN EEEIEE ESES 15 4 2 Configuratio m 15 5 Front end integration iieiccccccscscstscoceccccsssesssscscecsecsssesesstecesressersessvessossesssssssssssezesceess 18 5 1 Parameters ener rere rR ER sser EEE aasan sasa asa aaar saraaa easda aro a 18 5 1 1 HIT TP POST parameter Sicer aieeaa tee nean eoru aes eua a Deana 18 b 12 ChecksUlrindveidereeente sade ext vacant A OE E E E AAEE TEE EAS EEEE 21 51 3 Ord r INES PSR 22 5 L4 Deliverymaethodioverrid s i uiis itn fnnt censdevenasasuescees Fus cup cesta cassnapvegeaseevisenes 23 5 2 Sending parameters via HTTP POST esses eee eene eene nenne nnne ene ennn nnne 23 5 3 Showing the Front End POp up
45. ed Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 9 2 Retrieving a PDF label for a box When you want to retrieve a PDF label for a box you need to send a request to the server to receive a PDF file containing the barcode using the HTTP GET operation on the URI We will now show you how to send a valid request to retrieve a barcode as PDF base64 format and what the response of the server will look like Client Request Use the HTTP GET request method to retrieve a barcode as PDF from one of the following URLs HTTP Operation GET URL https api bpost be services shm accountId labels barcode pdf URL https api bpost be services shm accountId labels barcode pdf labelFormat A_4 URL https api bpost be services shm accountId labels barcode pdf labelFormat A_5 By default labels requested using the first URL will be printed on an A4 page Labels requested using the second URL with the labelFormat A_4 specification will also be printed on an A4 page One A4 page can fit 4 labels If you want to print each label separately on its own A5 size page you need to use the labelFormat A_5 specification in the URL The labelFormat parameter doesn t change the format of international labels because only the A4 format is supported for international labels Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 67
46. element name mobilePhone type phoneNumberType lt xs element name fixedPhone type phoneNumberType gt lt xs choice gt xs attribute name language use required gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value EN gt lt xs enumeration value NL gt lt xs enumeration value FR gt lt xs enumeration value DE gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name insuranceType gt lt xs choice gt lt xs element name basicInsurance gt lt xs complexType gt lt xs element gt lt xs element name additionalInsurance gt lt xs complexType gt xs attribute name value use required gt lt xs simpleType gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 75 87 bpost shipping manager Integration Manual c bpost xs restriction base xs integer gt enumeration xS xS xS xS xS xS xS enumeration xS xS XS XS enumeration enumeration enumeration enumeration enumeration enumeration enumeration enumeration enumeration lt xs restriction gt lt xs simpleType gt lt xs attribute gt
47. enient shipment method B5 Save shipping data All relevant shipping information is automatically saved in the bpost Back End Some information is returned to the web shop B6 Confirm Order WS URL redirection Optional The web shop confirms the order after payment step via web service C1 Create Labels WS All relevant information to create a box is send to the bpost systems via a secured web service The e tailer is able to ask a set of data labels barcode etc C2 Send label If requested automatic generated labels are returned to the e tailer instantly They can be saved or directly printed Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 13 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost 3 5 ICT Impact Below we provide an overview of the impact of each possible integration scenario on an ICT level Impact of scenario 1 easy Front End and easy Back End e Integration of iFrame in website e g via lightbox pop up e Send shipping parameters via Front End URL redirection POST parameters e Receive shipment information via return URL POST parameters e Optional Confirm order after payment via web service or URL redirection POST e Labels generated within Back End e LCI IN fi
48. ent orderInternationalLabelInfos element tags Name Allowed Values Description internationalLabelInfo For each label the lt internationalLabelInfo gt tag needs to be present The subtags are explained in lt internationalLabelInfo gt element tags order order element tags are explained in 6 2 Create or Replace Order Web Service internationalLabelInfo element tags Name Allowed Values __ Description parcelValue Value of the parcel in Euro cent parcelWeight Weight of the parcel in grams contentDescription Content description shipmentType SAMPLE Shipment type GIFT OTHER DOCUMENTS parcelReturnInstructions RTA Return instructions ABANDONED RTS privateAddress true Flag indicating whether the address is a false private address true or a business address false Example The following example shows a valid request to create an order and a national label POST shm 123456 orderAndLabels Content type application vnd bpost shm orderAndIntLabels v2 4 XML lt xml version 1 0 encoding UTF 8 gt orderInternationalLabelInfos xmins http schema post be shm deepintegration v2 gt lt internationalLabelInfo gt lt parcelValue gt 66490 lt parcelValue gt lt parcelWeight gt 500 lt parcelWeight gt lt contentDescription gt Iphone 4 16GB Black Earphones lt contentDescription gt lt shipmentType gt OTHER lt shipmentType gt lt parcelReturnInstructions
49. erved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 48 87 bpost shipping manager Integration Manual A f bpost 6 4 Modify Order Status Web Service The Modify Order Status web service modifies the status of an order 6 4 1 Operation To use the Modify Order Status web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orders status Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Modify Order Status URI is PUT URI POST PUT GET DELETE serviceEndPoint accountId orders status X i X X ATTENTION POST GET and DELETE operations on a Modify Order Status URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 4 2 Modifying an order status When you want to modify an order status you need to send the updated order status to the server using the HTTP PUT operation on the URI We will now show you how to send a valid request to modify an order status and what the response of the server will look like ATTENTION Modifying the status of a cancelled orde
50. erver will look like Client Request Use the HTTP POST request method to send the order and label information to the server The order and label information needs to be sent to the following URL Attribute MELTS HTTP Operation POST URL https api bpost be services shm accountId orderAndLabels The HTTP POST request must contain a Content type header field Attribute WETS HTTP Header Content type application vnd bpost shm orderAndNatLabels v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 59 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual ied f bpost In the body of the HTTP POST request you need to put the XML code containing the order and label information Attribute Description HTTP Body XML orderWithLabelAmount element orderWithLabelAmount element tags Name Allowed Values Description order lt order gt element tags are explained in 6 2 Create or Replace Order Web Service labelAmount Amount of labels Example The following example shows a valid request to create an order and a national label POST shm 123456 orderAndLabels Content type application vnd bpost shm orderAndNatLabels v2 XML lt xml version 1 0 encoding U
51. etrieve the information of the returned parameters php echo Chosen delivery method REQUEST deliveryMethod br br if REQUEST deliveryMethod Regular array array regularSignature regularSignaturePlus regularAutomaticSecondPresentation regularAdd itionalInsuranceInsuranceRange regularInfoReminderLanguage regularInfoReminderNotification Type otificationType regularInfoNextDayNotificationValue regularInfoDistributedLanguage regularInf regularInfoReminderNotificationValue regularInfoNextDayLanguage regularInfoNextDayN oDistributedNotificationType regularInfoDistributed NotificationValue regularBasicInsurance elseif _REQUEST deliveryMethod Pugo array array pugoAdditionalInsuranceInsuranceRange pugoInfoDistributedLanguage pugoInfoDistributedNotificationType pugoInfoDistributed NotificationValue pugoKeepMeInformedViaLanguage pugoKeepMeInformedViaNotificationType pugoKeepMeInformedViaNotification Value pugoKeepMeInformedViaPickupPunt pugoBasicInsurance selseif _REQUEST deliveryMethod Parcels depot Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 86 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager
52. gt lt xs choice gt lt xs complexType gt lt xs element gt lt xs element name totalPrice gt lt xs simpleType gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 80 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt xs restriction base xs int gt xs minInclusive value 0 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orders gt lt xs complexType gt xs sequence lt xs element ref order maxOccurs unbounded lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderRefBarcodeMap gt lt xs complexType gt lt xs sequence gt lt xs element name entry type orderRefBarcodeMapEntry minOccurs 1 maxOccurs 1 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderStatusMap gt lt xs complexType gt xs sequence lt xs element name entry type orderStatusMapEntry minOccurs 1 maxOccurs 1 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderRefLabelAmountMap gt lt xs complexType gt xs sequence lt xs e
53. gt RTA lt parcelReturnInstructions gt lt privateAddress gt true lt privateAddress gt lt internationalLabelInfo gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 64 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost order accountId 123456 accountId orderReference 201106241506 orderReference status OPEN status lt costCenter gt costCenter0 lt costCenter gt lt orderLine gt lt text gt Iphone 4 16GB Black lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt orderLine gt lt text gt Earphones lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt customer gt lt firstName gt Jan lt firstName gt lt lastName gt Peeters lt lastName gt lt deliveryAddress gt lt streetName gt Dorpsstraat lt streetName gt lt number gt 132 lt number gt lt box gt lt box gt lt postalCode gt 1800 lt postalCode gt lt locality gt Vilvoorde lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt email gt jan peeters provider be lt email gt lt phoneNumber gt 0032499123456 lt phoneNumber gt lt customer gt lt deliveryMethod gt lt intExpress gt lt intExpress gt lt
54. hown in the screenshot below Delivery method Visibility Product defaults Services Signature Signature Automatic 2nd Presentation Additional Insurance Info Reminder Info Next Day bpack home Visible No defaults to be set Not applicable D n Not applicable bd Not visible selected by default Not applicable ey Notvisible selected by defaut MPO Language EN Type SMS SMS EE 0 p Not applicable B Notvisible optionally Notvisible selected by default gt 0475240937 Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 84 87 bpost shipping manager Integration Manual 8 2 bpack bpost pugo delivery c bpost If the value of deliveryMethod Pugo the following service parameters are returned Information in bold is information that the customer used to complete his choice of delivery method Name pugoAdditionalInsuranceInsuranceRange Possible Values String Description The value of the insurance range that was selected Possible value gt 5 000 EUR pugoInfoDistributedLanguage EN NL FR DE Language in which the Info Distributed message will be sent pugoI
55. hroughout this document the following terms and abbreviations are used They are explained in this table Term WS Definition Web service Describes a standardized way of integrating Web based applications using the XML SOAP WSDL and UDDI open standards over an Internet protocol backbone ERP Enterprise Resource Planning The technology solutions for large companies or other organizations to manage their resources including customers supplies accounting and other back office activities LCI IN OUT Large Customer Interface Information used by bpost to generate labels Lightbox A simple unobtrusive java script used to overlay websites It is easy to setup and works on all modern browsers PUGO Pick up amp Go bpost delivery method For more information please visit www bpost be This name is no longer valid and is replaced by Bpack bpost Bpack 24 7 bpost delivery method For more information please visit www bpost be API Application Programming Interface a particular set of rules and specifications that software programs can follow to communicate with each other REST Representational State Transfer an approach for getting information content from a Web site by reading a designated Web page that contains an XML file that describes and includes the desired content URI Uniform Resource Identifier a string of characters used to identify a name or a res
56. ing HTTP with an XML serialization in conjunction with other Web related standards For an introduction go to the W3 Schools Web Services Tutorial at http w3schools com webservices default asp REMARK The bpack Shipping Manager runs in an HTTPS environment in order to safeguard the communication of private data bpost strongly recommends using https and does not support integrations in http environments Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 6 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost 3 2 bpack Shipping Manager solution The bpack Shipping Manager is a bpost solution available for national and international shipping It allows your business to manage shipping and returns and to print labels The bpack Shipping Manager solution contains a Front End and a Back End solution 3 2 1 Front End The bpack Shipping Manager Front End is an online solution for your e business to offer bpost delivery options to consumers bpost shipping manager Front End Solution Select products Check out Select delivery options Payment Confirmation o SS eL ee Figure 1 bpack Shipping Manager Front End solution The Front End fits seamlessly into the order process which is shown i
57. ion string by placing an ampersand followed by the passphrase itself It is not required to put amp passphrase MyPassPhrase Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 21 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 5 1 3 Order lines c bpost The format of the orderLine parameter consists of the order line description and the number of items piped orderLineDescription numberOfItems e orderLineDescription is a short description This description could be used by the person picking the order to identify the items If available add the item code in front of the description to facilitate the order management e numberOflItems is an integer and represents the number of items Example orderLine 08815 GSM iPhone 3GS 2 The example means that the consumer ordered 2 iPhones of type 3GS product category GSM with item number 08815 The orderLine parameter can be sent multiple times Every variable will be listed as a new order line in the shipping manager Back End see next figure 24_1308679860 x Order Order lines PRODUCT AANTAL ITEMS Iphone3G 2 Iphone3G 3 My product 1 Aantal records 3 Tw m Afdrukken Wh Markeren als verzonden X Annuleren 1 Pakket 1 Retour
58. ities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost xs enumeration value DOCUMENTS gt lt xs restriction gt lt xs simpleType gt lt xs simpleType name orderStatusType gt lt xs restriction base xs string gt lt xs enumeration value OPEN gt lt xs enumeration value PENDING gt lt xs enumeration value CANCELLED gt lt xs enumeration value COMPLETED gt lt xs enumeration value ON HOLD gt lt xs restriction gt lt xs simpleType gt lt xs simpleType name emailAddressType gt lt xs restriction base xs string gt lt xs maxLength value 50 gt lt xs restriction gt lt xs simpleType gt xs simpleType name phoneNumberType gt lt xs restriction base xs string gt lt xs maxLength value 20 gt lt xs restriction gt lt xs simpleType gt lt xs simpleType name pdfType gt lt xs restriction base xs base64Binary gt lt xs simpleType gt lt xs simpleType name barcodeType gt lt xs restriction base xs string gt lt xs simpleType gt xs complexType name addressType gt xs sequence lt xs element name streetName gt lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 40 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name number gt lt xs simpleType gt lt xs restriction base xs stri
59. l head meta content HTML Tidy for Java vers 26 sep 2004 see www w3 org name generator Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 31 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt title gt JBossWeb 2 0 1 GA Error report lt title gt lt style type text css gt ews lt style gt lt head gt lt body gt lt hi gt HTTP Status 401 lt hi gt lt hr noshade noshade size 1 gt lt p gt lt b gt type lt b gt Status report lt p gt lt p gt lt b gt message lt b gt lt p gt lt p gt lt b gt description lt b gt lt u gt This request requires HTTP authentication lt u gt lt p gt lt hr noshade noshade size 1 gt lt h3 gt JBossWeb 2 0 1 GA lt h3 gt lt body gt lt html gt Authorization Authorization is performed at the Web Service Level Each service end point contains the accountId to uniquely identify the resource Prior to the accountId passphrase validation the web service will validate that the accountId found in the basic authentication and the accountId found in the resource are the same This ensures a shop cannot access another shop s data If this is the case the Web Service will execute
60. l A bpost Example 2 shop The following example shows a valid request to create an order with delivery method shop POST shm 123456 orders Content type application vnd bpost shm order v2 XML lt xml version 1 0 encoding UTF 8 gt order xmins http schema post be shm deepintegration v2 gt lt accountId gt 123456 lt accountId gt lt orderReference gt 201106241506 lt orderReference gt lt status gt OPEN lt status gt lt costCenter gt costCenter0 lt costCenter gt lt orderLine gt lt text gt Iphone 4 16GB Black lt text gt lt nbOfiItems gt 1 lt nbOfItems gt lt orderLine gt lt orderLine gt lt text gt Earphones lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt customer gt lt firstName gt Jan lt firstName gt lt lastName gt Peeters lt lastName gt lt deliveryAddress gt lt streetName gt Dorpsstraat lt streetName gt lt number gt 132 lt number gt lt box gt lt box gt lt postalCode gt 1800 lt postalCode gt locality gt Vilvoorde lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt email gt jan peeters provider be lt email gt lt phoneNumber gt 0032499123456 lt phoneNumber gt lt customer gt lt deliveryMethod gt lt atShop gt lt infoPugo gt pugolId pugold0 pugolId lt pugoName gt pugoName0 lt pugoName gt lt emailAddress language NL gt jan peeters provider be lt emailAddress gt lt infoPugo gt
61. le automatically generated within Back End e Track and Trace available in the Back End Impact of scenario 2 deep Front End and easy Back End e Send shipping parameters via web service Create Order WS e Optional Confirm order after payment e Labels generated within Back End e LCI IN file automatically generated within Back End e Track and Trace available in the Back End Impact of scenario 3 deep Front End and deep Back End e Send parameters via web service during checkout in web shop Create Order WS e Send shipping parameters from ERP via web service and request barcode label Create Labels WS e LCI IN and label automatically generated by system e Track amp Trace available upon web service request Tracking WS e Update status of shipment via web service Modify Order Status WS Impact of scenario 4 easy Front End and deep Back End e Integration of iFrame in website e g via lightbox pop up e Send shipping parameters via Front End URL redirection POST parameters e Receive shipment information via return URL POST parameters e Optional Confirm order after payment via web service or URL redirection POST e Send shipping parameters from ERP via web service and request barcode label Create Labels WS e LCI IN and label automatically generated by system e Track amp Trace information available upon web service request Tracking WS e Update status of shipment via web service Modify Order Status
62. lement name entry type orderRefLabelAmountMapEntry minOccurs 1 maxOccurs 1 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name orderWithLabelAmount gt lt xs complexType gt xs sequence lt xs element ref order minOccurs 1 maxOccursz 1 lt xs element name labelAmount minOccurs 1 maxOccurs 1 gt lt xs simpleType gt lt xs restriction base xs int gt lt xs minExclusive value 0 gt lt xs restriction gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 81 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt xs simpleType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name labels type labelsType gt lt xs element name pdf type pdfType gt lt xs element name internationalLabelInfo gt lt xs complexType gt lt xs sequence gt lt xs element name parcelValue type xs int gt lt xs element name parcelWeight type xs int gt lt xs element name contentDescription type xs string gt lt xs element name shipmentType type shipmentType gt lt xs element name parcelReturnInstructions type parcelReturnInstructionsType gt lt xs
63. lt insurance gt lt additionalInsurance value 2 gt lt insurance gt lt infoDistributed gt lt emailAddress language NL gt jan peeters provider be lt emailAddress gt lt infoDistributed gt lt atShop gt lt deliveryMethod gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 43 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual iA f bpost totalPrice 66490 totalPrice order Server Response If your request to create an order is successful the server will respond with an HTTP 200 OK status code Attribute VELG HTTP Status 200 OK The server will give you the location of the order you created as one of the header fields Attribute VEIG HTTP Header Location https api bpost be services shm accountId orders orderReference The body of the response message will be empty because there is no XML code that needs to be sent back Attribute Description HTTP Body empty Example The following example shows a response confirming that the order was created successfully HTTP 1 1 200 OK Location https api bpost be services shm 123456 orders 201106241506 Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08
64. lt orderLine gt lt text gt Iphone 4 16GB Black lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt orderLine gt lt text gt Earphones lt text gt lt nbOfItems gt 1 lt nbOfItems gt lt orderLine gt lt customer gt lt firstName gt Jan lt firstName gt lt lastName gt Peeters lt lastName gt lt deliveryAddress gt lt streetName gt Dorpsstraat lt streetName gt lt number gt 132 lt number gt lt box gt lt box gt lt postalCode gt 1800 lt postalCode gt lt locality gt Vilvoorde lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt email gt jan peeters provider be lt email gt lt phoneNumber gt 0032499123456 lt phoneNumber gt lt customer gt lt deliveryMethod gt lt atShop gt lt infoPugo gt lt pugolId gt pugold0 lt pugold gt lt pugoName gt pugoName0 lt pugoName gt lt emailAddress language NL gt jan peeters provider be lt emailAddress gt lt infoPugo gt lt insurance gt lt additionalInsurance value 1 gt lt insurance gt lt infoDistributed gt lt emailAddress language NL gt jan peeters provider be lt emailAddress gt lt infoDistributed gt lt atShop gt lt deliveryMethod gt lt totalPrice gt 66490 lt totalPrice gt lt order gt lt barcode gt 323212345659900000001030 lt barcode gt lt orderWithBarcodes gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 47 87 bpost limi
65. mat error Order line contains invalid price must be in eurocent 1222 orderWeight Format error Order weight needs to be sent in grams and should not contain decimal limiter or 1230 deliveryMethodOverrides Format error Delivery method overrides has invalid format 1231 deliveryMethodOverrides Format error Delivery method overrides has invalid visibility Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 27 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost 1232 deliveryMethodOverrides Format error Delivery method overrides has invalid price must be eurocent 1240 customerCountry Format error Customer country code is invalid 1251 customerLastName Format error Last name is too long 1252 customerStreet Format error Street name is too long 1253 customerStreetNumber Format error Street number is too long 1254 customerBox Format error Box number is too long 1255 customerCity Format error City name is too long 1256 customerPostalCode Format error Postal code is too long 1257 customerPhoneNumber Format error Invalid phone number 1258 customerEmail Format error Invalid email 1310 orderReference Data error Order referenc
66. n 036908 Sign off Customer service Help NL FR DE EN G bpost B eShop Your active e services Q User management gt 17 05 11 Maintenance work this Sunday May 22 We e Shipper bpost business Inn 05 05 11 User Management Shipping Manager shifted read more Discover now Click on the below links to get more information about the bpost e services e Shipper bpost business gt g G 1 E Click shipping manager to open the Back End Shipping interface Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 15 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost J Quit Shipping Manager Sign off Arvest Dashboard Admin 06 06 2011 15062011 Advanced Search business Click the Admin button Quit Shipping Manager Sign off c bpost business 4 036908 Dashboard 06 06 2011 16 06 2011 Advanced Search Admin CREATED ON 22 02 2011 LAST UPDATED ON 19 05 2011 ACCOUNT ID SHOP NAME AutoShop be Click the pencil icon in front of your Account ID General Settings Sender addresses Delivery methods Layout Accountid 107434 Name Testshop E Confirm url confirm Emorum error Cancel url cancel Passphrase Visibility DEMO_SHM
67. n This chapter describes how to setup the front end integration of the bpack Shipping Manager allowing the integration of the bpack delivery methods into your checkout process 5 1 Parameters When you have configured your account and your delivery methods you are able to use the Front End redirect page You need to perform the following steps to successfully call the Front End application 1 Provide the necessary HTTP POST parameters 2 Calculate a checksum 3 Send the parameters and the checksum via HTTP POST 5 1 1 HTTP POST parameters The web shop needs to send the parameters specific to your account and the order to the following URL https shippingmanager bpost be ShmFrontEnd start The following fields are mandatory and their values are filled if available All values are case sensitive e accountId e action value START e orderReference e customerCountry The value of the action field needs to be START to open the redirect page of the shipping manager The table below lists all the possible hidden parameters you can send to the redirect page of the Front End All values listed are case sensitive Name Required Hashed Allowed Values Description accountId Required Yes Your unique customer ID of bpost P amp E action Required Yes START START opens the redirect CONFIRM page CONFIRM confirms the order lang Optional No NL Language FR NL Dutch EN FR French DE EN English Default language
68. n 1 0 encoding UTF 8 gt orderRefBarcodeMap xmlnsz http schema post be shm deepintegration v 2 entry orderReference 201106241506 orderReference barcode 323212345659900000001030 barcode lt entry gt lt orderRefBarcodeMap gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 62 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 6 8 Create Order And International Labels Web Service The Create Order And International Labels web service creates an order and a certain amount of international labels in one call 6 8 1 Operation To use the Create Order And International Labels web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orderAndLabels Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Create Order And International Labels URI is POST URI POST PUT GET DELETE serviceEndPoint accountId orderAndLabels M X X X ATTENTION PUT GET and DELETE operations on a Create Order And International Labels URI are prohibited Tr
69. n Figure 1 The following steps show how the process works First the consumer selects his desired product s in the web shop Next the consumer enters his credentials and performs a check out During the checkout process when selecting the delivery method address the consumer is redirected via URL POST parameters to the shipping manager Front End In the Front End he selects the appropriate delivery method and options All the information is automatically sent to the bpost systems and all the information is also returned via URL redirect POST parameters to the web shop The consumer then comes back to the web shop to validate and pays the order Afterwards the web shop can send a confirmation to bpost in order to validate the sale after payment via another POST URL redirection or via a REST web service 3 2 2 Back End The bpack Shipping Manager Back End is a web based solution that allows your e business to e Manage shipments e Select additional options e Generate labels e Link web orders to parcel shipping e Access Track amp Trace information e Manage returns Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 7 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost bpost shipping manage
70. n that is returned when using the http iFrame solution This chapter should only be read if you are interested in receiving all detailed information on selected services such as signature notifications This information is required when doing other back end integrations such as LCI The information returned depends on the delivery method that the customer has selected Each of the services linked to the delivery method is listed hereunder 8 1 bpack home regular delivery If the value of deliveryMethod Regular the following service parameters are returned Name Possible Values Description regularSignature Integer If this parameter is returned the Signature option is included for the shipment regularAutomaticSecondPresentation Integer If this parameter is returned the Automatic second presentation option is included for the shipment regularAdditionalInsuranceInsuranceRange String The value of the insurance range that was selected Possible value 5 000 EUR regularInfoReminderLanguage EN NL FR DE Language in which the Reminder message will be sent regularInfoReminderNotificationType e mail SMS Type of notification that will be used to send the Reminder message regularInfoReminderNotificationValue String If type SMS gt Phone number If type e mail gt e mail address regularInfoNextDayLanguage EN NL FR DE Language in which the Info Next day message
71. nfidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 3 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 87 bpost shipping manager Integration Manual A f bpost 1 Document modifications The following modifications have been introduced into the application Document version 2 0 Change Callback URL It is now possible to send the confirm error and cancel URL as parameters when requesting to show the iFrame This will allow efficient multi shop integrations and or usage of different domains during development testing 2 0 Company name It is possible to send through a company name when requesting to show the iFrame This field will be placed on the label REMARK the webservice is not yet updated to include this feature 2 0 Returned parameters More parameters are returned when the iFrame is closed They include notification information and selected options services Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 4 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost 2 Glossary of Terms T
72. nfoDistributedNotificationType String Type of notification that will be used to send the Reminder message pugoInfoDistributedNotificationValue e mail SMS If type SMS gt Phone number If type e mail gt e mail address pugoKeepMeInformedViaLanguage EN NL FR DE Language in which the PUGO message will be sent pugoKeepMeInformedViaNotificationTy pe e mail SMS Type of notification that will be used to send the PUGO message pugoKeepMeInformedViaNotificationVa EN NL FR DE If type SMS gt Phone number lue If type e mail gt e mail address pugoKeepMeInformedViaPickupPunt String Code of the selected pick up point pugoBasicInsurance Integer Value in eurocent of the Basic Insurance cost 8 3 bpack 24 7 Parcels depot delivery If the value of deliveryMethod Parcels depot the following service parameters are returned Name Possible Values Description depotSignature String If this parameter is returned the Signature option is included for the shipment depotAdditionalInsuranceInsuranceRange String The value of the insurance range that was selected Possible value 5 000 EUR depotInfoDistributedLanguage EN NL FR DE Language in which the Info Distributed message will be sent depotInfoDistributedNotificationType String Type of notification that will be used to send the Reminder message depotInfoDistribu
73. ng gt lt xs maxLength value 8 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name box minOccurs 0 gt lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 8 gt lt xs restriction gt lt xs simpleType gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 74 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost lt xs element gt lt xs element name postalCode gt lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 8 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name locality gt lt xs simpleType gt lt xs restriction base xs string gt lt xs maxLength value 40 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name countryCode gt lt xs simpleType gt lt xs restriction base xs string gt lt xs pattern value A Z 2 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs complexType name notificationType gt lt xs choice gt lt xs element name emailAddress type emailAddressType gt lt xs
74. nnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual Fr bpost lt xs element name memberld type xs string gt lt xs element name signature minOccurs 0 gt lt xs complexType gt lt xs element gt lt xs element name insurance type insuranceType minOccurs 0 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name intExpress gt lt xs complexType gt lt xs sequence gt lt xs element name insured minOccurs 0 gt lt xs complexType gt lt xs complexContent gt xs extension base insuranceType gt xs sequence lt xs element name options type optionsType minOccurs 0 gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name intBusiness gt lt xs complexType gt lt xs sequence gt lt xs element name insured minOccurs 0 gt lt xs complexType gt lt xs complexContent gt xs extension base insuranceType lt xs sequence gt lt xs element name options type optionsType minOccurs 0 gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs element gt lt xs sequence gt lt xs complexType gt lt xs element
75. nssoees 62 1 Operatore tease caver anne E epe Ex mU RI attendee muU Re ede Rr I EN UE oy ENG c r brille NASA EEA 6 3 Fetch Order Web Service eeeeee eee ee eese eene ee eene eene nn nnn nnn nnns eennn nanus 6 3 1 OPO AION ee 6 3 2 Fetching anOrQ6t s ior ertt epo EE HER ee FR So EYE REPE e vh FEE CERE E DERE EERT e a Sene e ERA 6 4 Modify Order Status Web Service eeeeeeeeee esee nennen nnne nnn nnno 6 4 1 Operation essea one vaso rene cost otv eva eet sieved basa e uva ee vue vue EEEE eund PP E Edere NEEN 6 4 2 Modifyilig aliorndef STATUS ceo eerte rues rure E Enae kE dac aE 6 5 Create National Labels Web Service eee esee eene eene nnn nnn 6 5 1 TOP Sie OM te P 6 5 2 Creating anational label sicieicccsssvssvecssvstocsecedacvessadsssessvesessnsvtececevicacdesvysen castwesssanenscesinis 6 6 Create International Labels Web Service cssssssssccccssssssssssssssssessessssssssssnseees 6 6 1 Operati Moss cova sicdeuvaesive P 6 6 2 Creating an international label eene nennen nennen nnns 6 7 Create Order And National Labels Web Service eeeee eere eene 6 7 1 Operationen eee ie ie De pra vo voee HER rav exe A EEEE ues eue Un ag 6 7 2 Creating an order and a national label enne 6 8 Create Order And International Labels Web Service eeeeeeee 69 3 ODDO
76. nt tags Name Allowed Values Description infoDistributed Info distributed The subtags are explained in Notification tags infoNextDay Info next day The subtags are explained in Notification tags infoReminder Info reminder The subtags are explained in Notification tags automaticSecondPresentation Automatic second presentation Notification tags Name Attributes Description emailAddress language e mail address if you want to notify by e mail The language attribute is required See Notification language attribute mobilePhone language Mobile phone number if you want to notify by mobile phone The language attribute is required See Notification language attribute fixedPhone language Fixed phone number if you want to notify by fixed phone The language attribute is Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 40 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost required See Notification language attribute Notification language attribute Name language Allowed Values Description The language of the notification EN English NL Dutch FR French DE German lt signatu
77. ntial Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 38 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost explained in Notification tags deliveryMethod lt atShop gt lt infoPugo gt element tags Name Allowed Values Description pugold Pick Up amp Go identifier pugoName Pick Up amp Go name Notification tag One of the notification tags See Notification tags lt deliveryMethod gt lt at24 7 gt element tags Name Allowed Values infoParcelsDepot Description Bpack24 7 Parcels depot tags The subtags are explained in lt deliveryMethod gt lt at24 7 gt lt infoParcelsDepot gt element tags signature Bpack24 7 signature The subtags are explained in lt signature gt element tags insurance Bpack24 7 insurance The subtags are explained in lt insurance gt element tags memberld Bpack24 7 member identifier lt deliveryMethod gt lt at24 7 gt lt infoParcelsDepot gt element tags Name Allowed Values parcelsDepotId Description Parcels depot identifier lt deliveryMethod gt lt intExpress gt element tags Name Allowed Values insured Description International Express
78. offered by the shipping manager are then implemented by sending and or receiving XML documents over the HTTP s Protocol Resources business entities such as the order are addressed by a Uniform Resource Identifier URI These resources can then be manipulated with the standard HTTP operations POST GET PUT and DELETE These requests will map to standard CRUD operations as illustrated in the table below CRUD HTTP Action Create POST Create a sub resource under the given URI The resource representation is passed in the request and the address URI of the newly created resource is returned in the response Read GET Retrieve the current state of the resource at the given URI The resource representation is returned in the response Update PUT Initialize or update the state of a resource at the given URI The complete resource representation is passed in the HTTP request Delete DELETE Delete a resource at a given URI Afterwards the URI is no longer valid 6 1 3 Endpoint Web Services of the shipping manager application are accessible at the following URL https api bpost be services shm Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 29 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bp
79. on v1 xmins ns2 http schema post be api shm v1 gt lt code gt 409 lt code gt lt message gt The order is in CANCELLED state and cannot be modified anymore lt message gt lt ns2 businessException gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 33 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Technical Exceptions If the Web Service call encounters a technical problem a specific response will be sent back to the client The response will be mapped to the most appropriate HTTP status code in the 5xx range If the issue happened while the code of the web service is executed the HTTP status code will always be 500 and XML code will be provided in the content of the response with a generic error message and a unique token used to uniquely identify the problem on our side A specific content type is used to describe the version of the functional exception XML payload The following table summarizes the specific attributes of the functional exception response Attribute Value Description HTTP Status One of 500 Internal Server Error 501 Not Implemented 502 Bad Gateway 503 Service Unavailable 504 Gateway Timeout 505 HTTP Version Not Supported HTTP Header applicati
80. on vnd bpost shmSystemException v1 XML HTTP Body systemException as described in the Common 1 0 xsd Below an example is provided of the response returned by any Web Service encountering a technical problem The 500 Internal Server Error message contains a unique ID UUID that is important for technical support HTTP 1 1 500 Internal Server Error Date Fri 29 Apr 2011 15 37 33 GMT Server Apache Content Length 496 Connection close Content Type application vnd bpost shmSystemException v 1 xml lt xml version 1 0 encoding UTF 8 standalone yes systemException xmins http schema post be api shm common v2 xmins ns2 http schema post be common exception v1 gt lt ns2 message gt An unexpected error occurred while executing the request Please try again in a few moments If the problem persist please contact our support and provide the following token information f35c0f13 538f 41ae 99aa 932bc3141109 lt ns2 message gt lt ns2 timestamp gt 2011 04 29 02 00 lt ns2 timestamp gt lt systemException gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 34 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 6 2 Create or Replace Order Web Servic
81. op Algemene instellingen Verzend adressen Verzendingsmethodes Layout VERZENDINGSMETHODE VISIBILITEIT BPACK 24 7 Zichtbaar BPACK WORLD Zichtbaar BPACK WORLD express Zichtbaar BPACK HOME Zichtbaar BPACK bpost Zichtbaar Configuratie opsiaa Terug naar shop overzicht Make sure you have configured your delivery methods Set the delivery methods you want to show to Visible For more information on the different delivery methods and their usage please refer to our bpack Shipping Manager user manual 3 Click the Sender Address tab The current default value must contain an existing Belgian address If not correctly configured the sent goods will not be returned in case of non delivery and our messaging services will not send messages when the goods are delivered in the bpack bpost location 999033 Demo shipping manager General Settings Sender addresses Delivery methods Layout Add address REFERENCE NAME STREET ne BOX cry COUNTRY PHONE N E MAIL Head quarters bpostHQ Anspachlaan 4 Brussel Belgium 3200000000 noreply bpostbe Back to shop overview Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 17 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 5 Front end integratio
82. or each label the internationalLabelInfo tag needs to be present The subtags are explained in lt internationalLabelInfo gt element tags orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info returnLabels true Flag indicating whether labels are returned false internationalLabelInfo element tags Name Allowed Values Description parcelValue Value of the parcel in Euro cent parcelWeight Weight of the parcel in grams contentDescription Content description shipmentType SAMPLE Shipment type GIFT OTHER DOCUMENTS parcelReturnInstructions RTA Return instructions ABANDONED RTS privateAddress true Flag indicating whether the address is a false private address true or a business address false Example The following example shows a valid request to create international labels In the example there are two internationalLabelInfo blocks which means this code will create two international labels for one order POST shm 123456 labels Content type application vnd bpost shm int label v2 XML lt xml version 1 0 encoding UTF 8 gt internationalLabelInfos xmIns http schema post be shm deepintegration v2 gt lt internationalLabelInfo gt lt parcelValue gt 990 lt parcelValue gt Confiden
83. ost shipping manager Integration Manual 9 f bpost 6 1 4 Versioning The versioning of a web service operation is achieved by sending requests and accepting responses having a specific media type defined by the following examples application vnd bpost servicefamily version 4 format application vnd bpost shmOrderCreation v2 XML application vnd bpost shmOrderChange v1 XML Where the version identifier is a v followed by a whole number We only distinguish between major versions Minor versions have to be backwards compatible or else they are a major version by definition The first version is v1 the next v2 the next v3 and so on This media type value must then be set accordingly on the Accept and Content Type headers of the HTTP operation 6 1 5 XML Validation The structure of the XML request and response messages must be validated against a schema definition The XSD file used to describe the various XML elements exchanged between the external parties and bpost can be found at the end of this document One XSD file contains the definition of one version of the data to be sent in requests and responses Eventually this XSD will import other XSDs for bpost common definitions like addresses names Each version of the data has its own namespace Elements defined in the http schema post be api shm v2 define the API version 2 of the SHM application In case the request contains an XML and that XML is vali
84. ource on the Internet XML eXtensible Markup Language XSD XML Schema Definition BPACK bpost The new name of PUGO a delivery method of bpost Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 5 87 bpost shipping manager Integration Manual A bpost 3 Introduction This document describes the integration procedure of the bpack Shipping Manager Please note that the shipping manager Integration Manual does not explain how to use the Back End of the shipping manager Please read the bpack Shipping Manager user guide if you want to work with the Back End interface 3 1 Required knowledge In order to use this manual you need knowledge of the following topics e XML e Web services e HTTPS XML stands for eXtensible Markup Language For an introduction go the W3 Schools XML Tutorial at http w3schools com xml default asp A Web service is defined by the W3C as a software system designed to support interoperable machine to machine interaction over a network It has an interface described in a machine processable format specifically WSDL Other systems interact with the Web service in a manner prescribed by its description using SOAP messages typically conveyed us
85. pakket B SELECTIE BARCODE SHIPPING METHOD STATUS DATUM rxe OO 323202000059900000961050 Taxipost Easy Retour Taxipost Easy Retour Geprint 28 06 2011 4 r xe o home TxP 24h Pro Nog niet geprint 22 06 2011 rxaooo 323202000059900000948036 home TxP 24h Pro Sluiten Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 Geprint bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 22 08 2041 i Aantal records 8 22 87 bpost shipping manager Integration Manual IA bpost 5 1 4 Delivery method overrides You can use a number of fields of the type deliveryMethodOverrides containing the delivery method name the visibility and the price in Euro cent The following example shows the accepted format of the field and a few examples of values deliveryMethodOverrides 1 Accepted format name visibility priceInEuroCent deliveryMethodOverrides 2 Example Regular VISIBLE 5400 deliveryMethodOverrides 3 Example Regular INVISIBLE deliveryMethodOverrides 4 Example Regular GREYED OUT The table below lists all possible delivery method names you can use as a value in the deliveryMethodOverrides fields and their corresponding labels as bpost delivery services Delivery Method Name Label Example bpack EXPRESS bpack World
86. perations on a Retrieve PDF Labels For Order URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 10 2 Retrieving PDF labels for an order When you want to retrieve PDF labels for an order you need to send a request to the server to receive a PDF file containing all the labels for an order using the HTTP GET operation on the URI We will now show you how to send a valid request to retrieve labels as PDF and what the response of the server will look like Client Request Use the HTTP GET request method to receive the labels as PDF To retrieve the PDF file you need to request it from the following URL HTTP Operation GET URL https api bpost be services shm accountId orders orderReference pdf URL https api bpost be services shm accountId orders orderReference pdf labelFormat A_4 URL https api bpost be services shm accountId orders orderReference pdf labelFormat A_5 By default labels requested using the first URL will be printed on an A4 page Labels requested using the second URL with the labelFormat A_4 specification will also be printed on an A4 page One A4 page can fit 4 labels If you want to print each label separately on its own A5 size page you need to use the labelFormat A_5 specification in the URL The labelFormat parameter doesn t change the format of international labels because only the A4 format is su
87. post All rights reserved Version 2 0 9 08 2012 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 76 87 bpost shipping manager Integration Manual A bpost lt xs complexType gt lt xs complexType name orderRefBarcodeMapEntry gt xs sequence lt xs element name orderReference typez xs string minOccurs 1 maxOccursz 1 lt xs element name barcode type barcodeType minOccurs 1 maxOccurs unbounded gt lt xs element ref pdf minOccurs 0 gt lt xs sequence gt lt xs complexType gt lt xs complexType name orderStatusMapEntry gt xs sequence lt xs element name orderReference typez xs string minOccurs 1 maxOccursz 1 lt xs element name status type orderStatusType minOccurs 1 maxOccurs 1 gt lt xs sequence gt lt xs complexType gt xs complexType name orderRefLabelAmountMapEntry gt lt xs sequence gt lt xs element name orderReference typez xs string minOccurs 1 maxOccurs 1 gt lt xs element name labelAmount minOccurs 1 maxOccurs 1 gt lt xs simpleType gt lt xs restriction base xs int gt lt xs minExclusive value 0 gt lt xs restriction gt lt xs simpleType gt lt xs element gt lt xs element name withRetour minOccurs 0 type xs boolean gt lt xs element name returnLabels minOc
88. post shm int label v2 XML In the body of the server response you will receive XML code containing the barcode element Attribute Description HTTP Body XML lt orderRefBarcodeMap gt element lt orderRefBarcodeMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info barcode Bar code Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 57 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Example The following example shows a response confirming that the label was created successfully HTTP 1 1 200 OK Content type application vnd bpost shm int label v2 XML lt xml version 1 0 encoding UTF 8 gt orderRefBarcodeMap xmlnsz http schema post be shm deepintegration v2 entry orderReference 201108191553 orderReference barcode CD100000016BE lt barcode gt lt entry gt lt orderRefBarcodeMap gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 58 87 bpost limited company under public l
89. pported for international labels Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 70 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost The HTTP GET request must contain an Accept header field Attribute HTTP Header Accept application vnd bpost shm pdf v2 XML The body of the GET request will be empty because there is no XML code that needs to be sent to the server Attribute Description HTTP Body empty Example The following example shows a valid request to retrieve labels as PDF GET shm 123456 orders 201106241506 pdf Accept application vnd bpost shm pdf v2 XML Server Response If your request to fetch an order is successful the server will respond with an HTTP 200 OK status code Attribute VELG HTTP Status 200 OK The server response will contain a Content type header field Attribute HTTP Header Content type application vnd bpost shm pdf v2 XML In the body of the server response you will receive XML code containing the PDF element Attribute Description HTTP Body XML lt pdf gt element Example The following example shows a response by the server giving you the PDF file The PDF file will be encoded in base64 Only a part of the code i
90. put type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden name lang value EN gt name accountId value 999033 gt name action value START gt name orderReference value 12345 Test Order name orderTotalPrice value 66490 gt name customerFirstName value Jan gt name customerLastName value Peeters gt name customerStreet value Dorpsstraat gt name customerStreetNumber value 132 gt name orderLine value Iphone 4 16GB Black 1 gt name orderLine value Earphones 1 gt name customerBox value gt name customerCity value Vilvoorde gt name customerPostalCode value 1800 gt name customerEmail value jan peeters provider be gt name customerPhoneNumber value 0032499123456 gt name customerCountry value BE gt name checksum value 6iddef9ff679508d455a5f9f451c3a2bfe8b721f2812ddb0b1990325a2039bb5 lt form gt 5 3 Showing the Front End pop up In order to show the Front End as a pop up on top of your web shop page you need to include code to create an iframe Create an iframe that has the same name as the target of your HTML form
91. r Back End Solution Shipping Information Manage shipments information storage and options 7 Aare Label printing A ec a m EL Bpost shipping systems Back office order management Figure 2 bpack Shipping Manager Back End solution In Figure 2 we show you the process in which the Back End is placed The following steps show how the process works The shipping information which is returned either by an integrated Front End or by REST web services can be stored in your Back office or ERP system and is automatically stored in the systems of bpost This covers information such as shipping address product client name etc It is possible to manage the information through the shipping manager Back End which is hosted by bpost E tailers can access it via the bpost portal to manage orders select options and generate labels Generated labels can be printed by the shipping manager and can be used to launch the logistic flow It is possible to follow the shipped parcels with the integrated Track amp Trace tool Apart from this solution the bpack Shipping Manager allows the deep integration of its functionalities into ERP or other back office systems This deep integration is thoroughly explained throughout the following sections and in the chapter Web Services Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 8 87 bpost limited company under public law Centre Monnaie 1000
92. r is not allowed Client Request Use the HTTP PUT request method to modify the order status The updated status needs to be sent to the following URL Attribute Value HTTP Operation PUT URL https api bpost be services shm accountId orders status The HTTP PUT request must contain the Content type and X HTTP Method Override header fields Attribute VEIG HTTP Header Content type application vnd bpost shm order status v2 XML HTTP Header X HTTP Method Override PATCH Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 49 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost In the body of the HTTP PUT request you need to put the XML code to update the order status Attribute Description HTTP Body XML orderStatusMap element lt orderStatusMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info status value OPEN value PENDING value CANCELLED value COMPLETED value ON HOLD Example The following example shows a valid
93. rders and print labels in the bpost Shipping interface Scenario 3 deep Front End and deep Back End e Integrate directly in your ERP system and or during check out after payment e Use bpost web services to send and request information e Store labels generated by bpost and auto print in your own ERP system e No need to use bpost applications for the logistic process Scenario 4 easy Front End and deep Back End e Show different and up to date delivery methods in the checkout process via the bpost frame perfectly integrated into the look amp feel of the webshop e Use ERP integration for back end via web services e Use bpost web services to send and request information e Store labels generated by bpost and auto print via own ERP system Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 10 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost We will now have a more in depth look at the scenarios 3 4 1 Scenario 1 story line Below are the steps describing the process of scenario 1 the easy Front End and easy Back End integration A1 Setup After signing a contract the customer integrates the shipping application Front End in a web shop A2 Configure The customer configures the admin panel of
94. re gt element tags Name signature Allowed Values Description Delivery method with signature signaturePlus Delivery method with signature name and date lt insurance gt element tags Name Attributes Description basicInsurance Basic insurance additionalInsurance valuez 1 The range in which the insurance valuez 2 amount is situated valuez 3 1 basic insurance up to 500 EUR valuez 4 2 additional up to 2 500EUR value 5 3 additional up to 5 000 EUR value 6 4 additional up to 7 500 EUR value 7 5 additional up to 10 000 EUR value 8 6 additional up to 12 500 EUR value 9 7 additional up to 15 000 EUR value 10 8 additional up to 17 500 EUR value 11 9 additional up to 20 000 EUR 10 additional up to 22 500 EUR 11 additional up to 25 000 EUR Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 41 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual Example 1 home c bpost The following example shows a valid request to create an order with delivery method home POST shm 123456 orders Content type application vnd bpost shm order v2 XML lt xml version 1 0 encoding UTF 8 gt order xmins
95. request to modify an order PUT shm 123456 orders status Content type application vnd bpost shm order status v2 XML X HTTP Method Override PATCH lt xml version 1 0 encoding UTF 8 gt orderStatusMap xmIns http schema post be shm deepintegration v2 gt lt entry gt lt orderReference gt 201106241506 lt orderReference gt lt status gt PENDING lt status gt lt entry gt lt orderStatusMap gt Server Response If your request to modify an order status is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server will give you the location of the updated order as one of the header fields Attribute RETE HTTP Header Location https api bpost be services shm accountId orders orderReference Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 50 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost The body of the response message will be empty because there is no XML code that needs to be sent back Attribute Description HTTP Body empty Example The following example shows a response confirming that the order status was modified successfully HTTP 1 1 200 OK Location https api bpos
96. rsion 2 0 9 08 2012 23 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost A parameter that you want to send to the Front End needs to be put in a hidden input element between the form form tags The following example shows the accountId parameter in a hidden input element form id myForm method POST target shmFrame action https shippingmanager bpost be ShmFrontEnd start gt lt input type hidden lt form gt name accountId valuez 123456 All the parameters and the checksum need to be placed in separate hidden input elements in the HTML form The HTML code below contains an example of how you can implement the bpost logo the form and the parameters in your web shop to call and open the Front End lt p gt We currently deliver our product with bpost By clicking on the icon below you will be able to define your preferred delivery method lt p gt form id myForm method POST target shmFrame action https shippingmanager bpost be ShmFrontEnd start gt lt input type image id logobpost src http www bpost be site nl residential parcels pickup handle with care 2groot jpg style cursor pointer alt Submit button gt lt input type hidden lt input type hidden lt in
97. ry gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 53 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost lt orderRefLabelAmountMap gt Server Response If your request to create a label is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server response will contain a Content type header field Attribute VEIG HTTP Header Content type application vnd bpost shm nat label v2 XML In the body of the server response you will receive XML code containing the barcode element Attribute Description HTTP Body XML lt orderRefBarcodeMap gt element lt orderRefBarcodeMap gt element tags Name Allowed Values Description orderReference Order reference unique ID used in your web shop to assign to an order The value of this parameter is not managed by bpost If the value already exists it will overwrite current order info barcode Bar code Example The following example shows a response confirming that the label was created successfully HTTP 1 1 200 OK Content type application vnd bpost shm nat label v2 XML lt xml version 1 0 encoding UTF 8 gt orderRefB
98. s accessible as a web based application via the bpost portal The shipping manager Back End allows e tailers to manage shipping and returns generate and print labels and access Track amp Trace information Since the Back End easy integration only involves a login to the bpost portal in order to access the Shipping interface there are no further details to be discussed concerning this integration solution Please read the bpack Shipping Manager user guide if you want to use the easy integration of the Back End 3 3 3 Front End deep integration The deep integration of the Front End is implemented via REST web services that provide real time data transfer between the web shop and bpost This deep integration of the Front End into your e shop doesn t use a URL re direct or pop up but makes the same technology as the easy integration available as web services Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 9 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost Go to the chapter Web Services to read the details of how to use the web services to implement the deep integration of the Front End 3 3 4 Back End deep integration The deep integration of the Back End is implemented as web services that provi
99. s of delivery method for specific order extra Optional No Additional parameters related to your web shop Information not used by bpost and returned in the confirm error cancel URL extraSecure Optional Yes Additional parameters related to your web shop included in the hash Same as the extra parameters but hashed confirmUrl Optional No URL to where the customer is redirected once the iFrame is closed If empty the default value is used cancelUrl Optional No URL to where the customer is redirected if the button back to shopping car is clicked If empty the default value is used errorUrl Optional No URL to where the customer is redirected if an error occurs If empty the default value is used Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 20 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual 9 f bpost The following screenshot shows where the parameters are shown on the Front End pop up Currently selected delivery method home home shop BPACK24 7 orderReference orderTotalPrice 201106241506 customerFirstName customerLastName customerStreet customerStree
100. s shown here as an example HTTP 1 1 200 OK Content type application vnd bpost shm pdf v2 XML lt xml version 1 0 encoding UTF 8 gt pdf xmins http schema post be shm deepintegration v2 gt JVBERiOxLjQKJeLjz9MKMyAwIG9iaiA8PC9 GaWxOZXIvRENURGVjb2RIL1R5cGUVvWE9iamVj dC9MZW5ndGggMzAyMS9CaXxXRzZUGVyQ29tcG9uZW 50IDgvSGVpZ2h0IDMxLONvbG9yU3B hY2UvRGV2aWNIUkdCL1N1YnR5cGUvSW1hZ2UvV2lkdGggMzk2Pj5zdHJIYWOK 9j A4AAQS kZJRgGABAgAAAQABAAD 2wBDAAgGBgcGBQgHBwcJCQgKDBQNDASLDBkSEW8UH RofHhO Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 71 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost aHBwgJC4nICIsIxwcKDcpLDAxNDQOHyc5PTgyPC4zNDL 2wBDAQkJCQWLDBgNDRgyIRwh MjlyMjlyMjlyMjlyMjlyMjlyMjlyMjlyMjly MjlyMjlyMjlyMjlyMjlyMjlyMjly MjL wAARCAAfAYw DASIAAhEBAxEB 8QAHWAAAQUBAQEBAQEAAAAAAAAAAAECAWQFBgCICQOL 8QAtRAAAg EDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEIIOKxwRVSOfAKkM2Jyggk KFhcYGRoUicoKSoONTY3ODk6QORFRkdISUpTVFVWV1hZWmNKkZWZnaGlqc3R1dnd4eXqD hIWGhA4BDipKTIWWl5iZmqKjpKWmpe6ipqrKztLW2t7ibusLDxMXGx8jJytL T1 NXW 19jZ2uHi4 T I5ufo6erx8vP09fb3 Pn6 8QAHWEAAWEBAQEBAQEBAQAAAAAAAAECAWOFBgcICQoL 8 lt pdf gt Depending on the format you specified in the URL the requested labels are printe
101. show you how to send a valid request to fetch an order and what the response of the server will look like Client Request Use the HTTP GET request method to fetch order information To retrieve Order information you need to request it from the following URL Attribute VEIG HTTP Operation GET URL https api bpost be services shm accountId orders orderReference The HTTP GET request must contain an Accept header field Attribute WETS HTTP Header Accept application vnd bpost shm order v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 45 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost The body of the GET request will be empty because there is no XML code that needs to be sent to the server Attribute Description HTTP Body empty Example The following example shows a valid request to fetch an order GET shm 123456 orders 201106241506 Accept application vnd bpost shm order v24 XML Server Response If your request to fetch an order is successful the server will respond with an HTTP 200 OK status code Attribute VELG HTTP Status 200 OK The server response will contain a Content type header field Attribute VELG HTTP Header Content typ
102. t customerLastName Last name of the customer The first name and the last name together should not be longer than 40 characters Only 40 characters are shown on the label customerMemberld Bpack24 7 member identifier customerStreet Max length 40 Street name of the customer customerStreetNumber Max length 8 Street number of the customer customerBox Max length 8 Box number of the customer customerCity Max length 40 City of the customer customerPostalCode Integer Postal code of the customer Max length 32 customerCountry Uppercase 2 character Country of the customer country code customerEmail Max length 50 E mail address of the customer customerPhoneNumber Max length 20 Mobile phone number of the customer customerPostalLocation Name of Post Point or Bpack 24 7 automate in case delivery method BPACK bpost of Bpack 24 7 is selected customerRcCode RC code to identify a Post Point or Bpack 24 7 automate orderLine The items that are included in the order Order lines are shown in the back end of the shipping manager and facilitate the use of the tool Multiple orderLines are available for a single order orderWeight Integer Weight of the order in grams extra Additional parameters related to your web shop Information not used by bpost and returned in the confirm error cancel URL extraSecure Additional parameters related to
103. t be services shm 123456 0rders 201106241506 Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 51 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual IA bpost 6 5 Create National Labels Web Service The Create National Labels web service creates new national labels 6 5 1 Operation To use the Create National Labels web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId labels Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Create National Labels URI is POST URI POST PUT GET DELETE serviceEndPoint accountId labels M X X X ATTENTION PUT GET and DELETE operations on a Create National Labels URI are prohibited Trying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 5 2 Creating a national label When you want to create a national label you need to send the national label information to the server using the HTTP POST operation on the URI We will now show you how to send a valid request to create a national l
104. t xs element name options type optionsType minOccurs 0 gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs element gt lt xs element name dropAtTheDoor gt lt xs complexType gt lt xs element gt lt xs choice gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name atShop gt lt xs complexType gt lt xs sequence gt lt xs element name infoPugo gt lt xs complexType gt lt xs complexContent gt lt xs extension base notificationType gt lt xs sequence gt lt xs element name pugold type xs string gt lt xs element name pugoName type xs string gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs element gt lt xs element name insurance type insuranceType minOccurs 0 gt lt xs element name infoDistributed type notification Type minOccurs 0 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name at24 7 gt lt xs complexType gt lt xs sequence gt lt xs element name infoParcelsDepot gt lt xs complexType gt lt xs sequence gt lt xs element name parcelsDepotId type xs string gt lt xs sequence gt lt xs complexType gt lt xs element gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 79 87 bpost limited company under public law Centre Mo
105. tNumber EU _ Total 08 00 customerBox Bt Jane Miet aps C7 onte cuncta customerCity 4 customerPostalCode customerCountry customerEmail fi customerPhoneNumber jig Re ento shopping 5 1 2 Checksum The checksum is a 256 bit Secure Hash Algorithm SHA 256 in UTF 8 encoding of the following required fields accountId action customerCountry orderReference passphrase All the fields need to be passed in alphabetical order In case one or more of the following optional fields is used in the form they should also be included in the checksum calculation e costCenter e deliveryMethodsOverrides e extraSecure e orderWeight These optional fields need to be inserted into the sequence alphabetically For example if the accountId is 123456 the costCenter is Online Shop the customerCountry is BE the orderReference is 201106161621 and the password is MyPassPhrase you need to generate the checksum of the following string of the fields concatenated by the ampersand 8 accountIid 123456 amp action START amp costCenter Online Shop amp customerCountry BE amp orderReference 201106161621 amp MyPassPhrase This string will give you the following checksum hash f9b5e5ab0fbe6fce786ccbff4ceb763bc125152 6532283dca7a93 4875ef 44 f For more information on how to generate SHA256 please refer to your favourite search engine REMARK As shown in the above example the passphrase is added to the end of the checksum calculat
106. ted company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost Example The following example shows a response by the server for a Bpack 24 7 order lt xml version 1 0 encoding UTF 8 gt lt orderWithBarcodes xmins http schema post be shm deepintegration v2 xmins ns2 http schema post be common exception v1 gt lt order gt lt accountId gt 123456 lt accountId gt lt orderReference gt be lt orderReference gt lt status gt PENDING lt status gt lt customer gt lt firstName gt Ts lt firstName gt lt lastName gt Gs lt lastName gt lt deliveryAddress gt lt streetName gt PB20002 A Groport Zaventem lt streetName gt lt number gt 17 lt number gt lt postalCode gt 1930 lt postalCode gt lt locality gt Zaventem lt locality gt lt countryCode gt BE lt countryCode gt lt deliveryAddress gt lt customer gt lt deliveryMethod gt lt at24 7 gt lt infoParcelsDepot gt lt parcelsDepotId gt 014473 lt parcelsDepotId gt lt infoParcelsDepot gt lt memberlId gt 123456789 lt memberld gt lt at24 7 gt lt deliveryMethod gt lt totalPrice gt 500 lt totalPrice gt lt order gt lt barcode gt 323299901059900000379030 lt barcode gt lt orderWithBarcodes gt Confidential Copyright 2011 by bpost All rights res
107. tedNotificationValue e mail SMS If type SMS gt Phone number If type e mail gt e mail address pugoBasicInsurance Integer Value in eurocent of the Basic Insurance cost Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 85 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost 8 4 bpack business bpack BUSINESS delivery If the value of deliveryMethod bpack BUSINESS the following service parameters are returned Name Possible Values Description businessAdditionalInsuranceInsuranceRange String The value of the insurance range that was selected Possible value 5 000 EUR businessBasicInsurance String Value in eurocent of the Basic Insurance cost 8 5 bpack express bpack EXPRESS delivery If the value of deliveryMethod bpack EXPRESS the following service parameters are returned Name Possible Values Description expressAdditionalInsuranceInsuranceRange String The value of the insurance range that was selected Possible value 5 000 EUR expressBasicInsurance String Value in eurocent of the Basic Insurance cost 8 6 Sample code to retrieve parameters Following php sample code can be used to r
108. ters a functional problem a specific response will be sent back to the client The response will be mapped to the most appropriate HTTP 1 1 status code in the 4xx range as defined here http www w3 org Protocols rfc2616 rfc2616 seci0 html and an XML content will be provided with a distinct error code and error message providing the client with a clear description of what went wrong as well as providing hints on what to change in order to solve the functional issue A specific content type is used to describe the version of the functional exception XML payload The following table summarizes the specific attributes of the functional exception response Attribute Value Description HTTP Status One of 400 Bad Request 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 409 Conflict 410 Gone 411 Length Required 415 Unsupported Media Type 416 Requested Range Not Satisfiable 417 Expectation Failed HTTP Header application vnd bpost shmFunctionalException v1 XML HTTP Body businessException as described in the Common 1 0 xsd Below an example is provided of a response returned by any Web Service encountering a functional problem HTTP 1 1 409 Conflict Server Apache Coyote 1 1 Content Type application vnd bpost shmFunctionalException v1 XML Content Length 379 Date Tue 26 Apr 2011 07 30 20 GMT Connection close ns2 businessException xmlnsz http schema post be common excepti
109. thod gt lt atHome gt signed element tags insured home insurance The subtags are explained in lt deliveryMethod gt lt atHome gt insured element tags dropAtTheDoor Drop parcel at the door of customer lt deliveryMethod gt lt atHome gt lt normal gt element tags Allowed Values Description options For the options subtags see Additional services lt options gt element tags lt deliveryMethod gt lt atHome gt lt signed gt element tags Name Allowed Values Description Signature tag One of the subtags that are used under the lt signature gt tag See lt signature gt element tags options For the options subtags see Additional services lt options gt element tags deliveryMethod lt atHome gt insured element tags Name Allowed Values Description Insurance tag One of the subtags that are used under the lt insurance gt tag See lt insurance gt element tags options For the options subtags see Additional services lt options gt element tags lt deliveryMethod gt lt atShop gt element tags Name Allowed Values Description infoPugo shop Pick Up amp Go tags The subtags are explained in lt infoPugo gt element tags insurance shop insurance The subtags are explained in lt insurance gt element tags infoDistributed Info distributed The subtags are Confide
110. tial Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 56 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost parcelWeight 250 parcelWeight lt contentDescription gt My description contentDescription shipmentType OTHER shipmentType parcelReturnInstructions RTA parcelReturnInstructions lt privateAddress gt true lt privateAddress gt lt internationalLabelInfo gt lt internationalLabelInfo gt lt parcelValue gt 300 lt parcelValue gt lt parcelWeight gt 50 lt parcelWeight gt lt contentDescription gt This is a gift lt contentDescription gt lt shipmentType gt GIFT lt shipmentType gt lt parcelReturnInstructions gt RTA lt parcelReturnInstructions gt lt privateAddress gt false lt privateAddress gt lt internationalLabelInfo gt lt orderReference gt 201108191553 lt orderReference gt lt returnLabels gt true lt returnLabels gt lt internationalLabelInfos gt Server Response If your request to create an international label is successful the server will respond with an HTTP 200 OK status code Attribute VEIG HTTP Status 200 OK The server response will contain a Content type header field Attribute HTTP Header Content type application vnd b
111. tion streetName Max length 40 Street name of the customer number Max length 8 Street number of the customer box Max length 8 Box number of the customer postalCode Max length 40 Postal code of the customer locality Integer City name of the customer Max length 40 countryCode Uppercase 2 character Country of the customer country code lt deliveryMethod gt element tags Name Allowed Values Description atHome home tags The subtags are explained in lt deliveryMethod gt lt atHome gt element tags atShop shop tags The subtags are explained in lt deliveryMethod gt lt atShop gt element tags at24 7 Bpack24 7 tags The subtags are explained in lt deliveryMethod gt lt at24 7 gt element tags intExpress International Express tags intBusiness International Business tags lt deliveryMethod gt lt atHome gt element tags Allowed Values Description normal Normal home The subtags are explained in lt deliveryMethod gt lt atHome gt lt normal gt element tags Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 37 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual iA f bpost signed home signature The subtags are explained in lt deliveryMe
112. tional No Max length 40 Street name of the customer customerStreetNumber Optional No Max length Street number of the customer customerBox Optional No Max length Box number of the customer customerCity Optional No Max length 40 City of the customer customerPostalCode Optional No Max length 32 Postal code of the customer customerCountry Required Yes Uppercase 2 character country ISO code Country of the customer customerEmail Optional No Max length 50 E mail address of the customer customerPhoneNumber Optional No Max length 20 Mobile phone number of the customer orderLine Optional No The items that are included in the order Order lines are shown in Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 19 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual c bpost the back end of the shipping manager and facilitate the use of the tool Multiple orderLines are available for a single order orderWeight Optional Yes Integer Weight of the order in grams deliveryMethodOverrides Optional Yes Override
113. ustomer tags The subtags are explained in lt customer gt element tags deliveryMethod Delivery method tags The subtags are explained in lt deliveryMethod gt element tags totalPrice Total price of the basket order in Euro cents excluding shipping costs lt orderLine gt element tags Name Allowed Values Description text Text describing the ordered item nbOfItems Number of items lt customer gt element tags Name Allowed Values Description firstName First name of the customer lastName Last name of the customer The first name and the last name Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 36 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual iA f bpost together should not be longer than 40 characters Only 40 characters are shown on the label deliveryAddress Delivery address tags The subtags are explained in customer deliveryAddress element tags email Max length 50 e mail of the customer phoneNumber Max length 20 Phone number of the customer customer deliveryAddress element tags Name Allowed Values Descrip
114. ve as PDF will look like this Exp diteur Afzender AutoShop Hasseltweg Paquet Pakket Paket 3600 Genk P l 323203690859900000001040 Dany De Backere Elisabethlaan 3 28 2600 Berchem For more information on how to decode base 64 please refer to your favourite search engine Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 69 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost 6 10 Retrieve PDF Labels For Order Web Service The Retrieve PDF Labels For Order web service retrieves all the labels of an existing order as one PDF This web service will retrieve both national and international labels 6 10 1 Operation To use the Retrieve PDF Labels For Order web service you need to perform an HTTP operation on a URI that is constructed as follows URI serviceEndPoint accountId orders orderReference pdf Where serviceEndPoint is https api bpost be services shm and accountId is the same account number you use for authentication The only HTTP operation that is allowed on the Retrieve PDF Labels For Order URI is GET URI POST PUT GET DELETE serviceEndPoint accountId orders orderReference X X v X ATTENTION POST PUT and DELETE o
115. veryAddress type addressType gt lt xs element name email minOccurs 0 type emailAddressType gt lt xs element name phoneNumber minOccurs 0 type phoneNumberType xs sequence lt xs complexType gt lt xs element gt lt xs element name deliveryMethod gt lt xs complexType gt lt xs choice gt lt xs element name atHome gt lt xs complexType gt lt xs sequence gt lt xs choice gt lt xs element name normal gt lt xs complexType gt lt xs sequence gt lt xs element name options type optionsType minOccurs 0 gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs element name signed gt lt xs complexType gt lt xs complexContent gt xs extension base signatureType gt lt xs sequence gt lt xs element name options type optionsType minOccurs 0 gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs element gt lt xs element name insured gt lt xs complexType gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 78 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A bpost lt xs complexContent gt xs extension base insuranceType gt xs sequence l
116. ying to perform these operations will always return a response with HTTP status code 405 Method Not Allowed 6 8 2 Creating an order and an international label When you want to create an order and a international label you need to send the order and label information to the server using the HTTP POST operation on the URI We will now show you how to send a valid request to create an order and a international label and what the response of the server will look like Client Request Use the HTTP POST request method to send the order and label information to the server The order and label information needs to be sent to the following URL Attribute VEIG HTTP Operation POST URL https api bpost be services shm accountId orderAndLabels The HTTP POST request must contain a Content type header field Attribute HTTP Header Content type application vnd bpost shm orderAndIntLabels v2 XML Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 63 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Entities Register Brussels Postal Current Account IBAN BE94 0000 0000 1414 BIC BPOTBEB1 bpost shipping manager Integration Manual A f bpost In the body of the HTTP POST request you need to put the XML code containing the order and label information Attribute Description HTTP Body XML orderInternationalLabelInfos elem
117. ype name SHMTechnicalExceptionInfo gt lt xs complexContent gt xs extension base exception TechnicalExceptionInfo gt lt xs complexContent gt lt xs complexType gt xs complexType name SHMValidationExceptionInfo gt lt xs complexContent gt lt xs extension base exception ValidationExceptionInfo gt lt xs complexContent gt lt xs complexType gt lt xs element name businessException type SHMBusinessExceptionInfo gt lt xs element name technicalException type SHMTechnicalExceptionInfo gt lt xs element name validationException type SHMValidationExceptionInfo gt lt xs simpleType name labelFormatType gt lt xs restriction base xs string gt lt xs enumeration value A4 gt lt xs enumeration value A5 gt lt xs restriction gt lt xs simpleType gt xs simpleType name parcelReturnInstructionsType gt lt xs restriction base xs string gt xs enumeration value ABANDONED gt lt xs enumeration value RTA gt xs enumeration value RTS gt lt xs restriction gt lt xs simpleType gt lt xs simpleType name shipmentType gt lt xs restriction base xs string gt lt xs enumeration value SAMPLE gt lt xs enumeration value GIFT gt lt xs enumeration value OTHER gt Confidential Copyright 2011 by bpost All rights reserved Version 2 0 9 08 2012 73 87 bpost limited company under public law Centre Monnaie 1000 Brussels VAT BE 0214 596 464 Legal Ent

Integration Manual

Contents

Download Pdf Manuals

Related Search

Related Contents