Creating your first Request to a Service

  1. Open the project set up in Creating a SOAP Project from a Service. We will assume, for the purposes of this exercise, that AllocationService.xml has been used to create the project.

  2. Right-click on the method to which the new request is to be sent (e.g. createAndAllocateConsignmentsWithBookingCode):

    New_API_Request.png
  3. Select New request, and, when prompted, enter a name for the request.

  4. Each XML method request starts with the SOAP envelope in the left hand request pane, followed by an automatically generated skeleton of the Body. This contains the name of the method and any mandatory tags, e.g.

    New-SOAP-Project_7_.png

    Note

    The SOAP endpoint is the URL at the top of the window incorporating the full path to the service, e.g.

    https://dm-delta.metapack.com/dm/services/AllocationService

    The process is as follows:

    1. Submit the authorisation (step 5) in the bottom left of the window,

    2. Complete the Body (step 6) in the left hand pane,

    3. Submit and validate the request by clicking the run button Arrow.png in the top left hand corner (step 7).

    4. The results of the request are displayed in the right hand pane.

  5. Select the Auth option in the bottom left of the window and then:

    1. Select Add New Authorization,

      Add_Authorization.png
    2. Allow the Type to default to Basic and click OK:

    3. Complete the Username and Password in the resultant dialog:

      New-Soap-Project-4.png

      Note

      Typically, the authentication details would be for the API user set up in Creating your API User.

      Tip

      It is highly recommended, for reasons of traceability, that there should be a separate user account dedicated to each person using the Shipping API. These accounts should not be locked to a warehouse and, as such, should be distinct from the other user accounts set up in the Shipping Configuration.

    4. Reselect Auth to collapse the Authorization window.

  6. You can now complete the XML tags in accordance with the instructions for the selected method (e.g. createAndAllocateConsignmentsWithBookingCode),

    The following example creates and allocates a consignment using the minimum parameters:

    <soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="urn:DeliveryManager/services" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
       <soapenv:Header/>
       <soapenv:Body>
          <ser:createAndAllocateConsignmentsWithBookingCode soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
             <consignment xsi:type="typ:Consignment" xmlns:typ="urn:DeliveryManager/types">
                <consignmentWeight xsi:type="xsd:double">0.1</consignmentWeight>
                   <orderNumber xsi:type="soapenc:string">test01234</orderNumber>
                   <parcelCount xsi:type="xsd:int">1</parcelCount>
                   <parcels soapenc:arrayType="ns2:Parcel[1]" xsi:type="soapenc:Array">
                      <parcels xsi:type="ns2:Parcel">
                      </parcels>
                  </parcels>
                   <recipientAddress xsi:type="ns2:Address">
                      <countryCode xsi:type="soapenc:string">GBR</countryCode>
                      <line1 xsi:type="soapenc:string">200 Gray’s Inn Road</line1>
                      <line2 xsi:type="soapenc:string">LONDON</line2>
                      <postCode xsi:type="soapenc:string">WC1X 8XZ</postCode>
                   </recipientAddress>
                   <recipientName xsi:type="soapenc:string">TEST PARCEL</recipientName>
                     <senderAddress xsi:type="ns2:Address">
                      <countryCode xsi:type="soapenc:string">GBR</countryCode>
                      <line1 xsi:type="soapenc:string">900 LONGWATER AVENUE</line1>
                      <line2 xsi:type="soapenc:string">READING</line2>
                      <postCode xsi:type="soapenc:string">RG2 6GE</postCode>
                   </senderAddress>
                   <senderCode xsi:type="soapenc:string">READING1</senderCode>
                   <senderName xsi:type="soapenc:string">Reading Warehouse</senderName>
             </consignment>
             <bookingCode xsi:type="soapenc:string">@NEXT</bookingCode>
             <calculateTaxAndDuty xsi:type="xsd:boolean">false</calculateTaxAndDuty>
          </ser:createAndAllocateConsignmentsWithBookingCode>
       </soapenv:Body>
    </soapenv:Envelope>

    Note

    You need to substitute your own warehouse code (senderCode) and carrier 'service group' (used in the bookingCode field). These must have previously been set up during the Shipping Configuration. The other details can be modified in any way you see fit.

    Set calculateTaxAndDuty to false.

  7. To test that the API integration is working correctly, click Arrow.png in the top left hand corner of the request window, to submit and validate the request. The results are displayed in the right hand pane of the request window.

  8. If there are no authentication errors, and the requested XML tags are returned in some form, then you know that the integration is working correctly. For some expected results, refer to the example response in createAndAllocateConsignmentsWithBookingCode.