Create Pickup Request

General Operation Information

This web service operation allows you to submit a request for Estes to pick up freight from a provided shipper location.

The pickup web service provides an interface to the pre-existing Pickup System API used by the external Estes website. All business rules related to creating and updating a pickup request are applied to web service-created pickups (just as they are for website-created pickups).

• Communication Pattern
• Preconditions
• Postconditions
• Input
• Example Input
• Output
• Example Output
• Errors & Exceptions

Communication Pattern

Request/Reply – This is a communication pattern in which the service requester sends a request to the service provider. The service provider processes the request and sends a reply back to the requester. This is an on-time operation, meaning that there are no (long) time intervals between sending the request, the processing of the request and sending the reply.

Preconditions

1. A requester must have a valid My Estes user account and that account must have the appropriate privileges to call the pickup web service.
2. Minimal information required to create a pickup request must be provided in the SOAP request to prevent the service from responding with errors.

Postconditions

1. A general error is provided indicating that the service is not responding (offline) at the time.
2. A pickup request was successfully recorded and the assigned pickup request number is returned in the response.
3. Business validation errors are returned in a list with a code and description for each.

Input

Date elements are expecting ISO date format (2013-12-25). Time elements are expecting a four-position HHMM format as a number with no delimiter. (Example: 1500 would be 3:00 p.m.). All times are interpreted as Eastern Standard Time. If the request number is passed in upon create, it will be ignored.

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:est="https://estespickup.base.ws.provider.soapws.pickupRequest">
   <soapenv:Header/>
   <soapenv:Body>
      <est:createPickupRequestWS>
        <pickupRequestInput>
            <!--Optional:-->
            <requestNumber>?</requestNumber>
            <shipper>
               <shipperName>?</shipperName>
               <!--Optional:-->
               <accountCode>?</accountCode>
               <!--Optional:-->
               <shipperAddress>
                  <!--Optional:-->
                  <addressInfo>
                     <addressLine1>?</addressLine1>
                     <!--Optional:-->
                     <addressLine2>?</addressLine2>
                     <city>?</city>
                     <stateProvince>?</stateProvince>
                     <postalCode>?</postalCode>
                     <!--Optional:-->
                     <postalCode4>?</postalCode4>
                     <countryAbbrev>?</countryAbbrev>
                  </addressInfo>
               </shipperAddress>
               <!--Optional:-->
               <shipperContacts>
                  <!--1 or more repetitions:-->
                  <shipperContact>
                     <!--Optional:-->
                     <id>?</id>
                     <!--Optional:-->
                     <operation>
                        <operationType>?</operationType>
                     </operation>
                     <!--Optional:-->
                     <contactInfo>
                        <name>
                           <!--Optional:-->
                           <firstName>?</firstName>
                           <!--Optional:-->
                           <middleName>?</middleName>
                           <!--Optional:-->
                           <lastName>?</lastName>
                        </name>
                        <!--Optional:-->
                        <email>?</email>
                        <phone>
                           <areaCode>?</areaCode>
                           <number>?</number>
                           <!--Optional:-->
                           <extension>?</extension>
                        </phone>
                        <!--Optional:-->
                        <fax>
                           <areaCode>?</areaCode>
                           <number>?</number>
                        </fax>
                        <!--Optional:-->
                        <receiveNotifications>?</receiveNotifications>
                        <!--Optional:-->
                        <notificationMethod>?</notificationMethod>
                     </contactInfo>
                  </shipperContact>
               </shipperContacts>
            </shipper>
            <!--Optional:-->
            <requestAction>?</requestAction>
            <!--Optional:-->
            <paymentTerms>?</paymentTerms>
            <pickupDate>?</pickupDate>
            <!--Optional:-->
            <pickupStartTime>?</pickupStartTime>
            <!--Optional:-->
            <pickupEndTime>?</pickupEndTime>
            <!--Optional:-->
            <totalPieces>?</totalPieces>
            <!--Optional:-->
            <totalWeight>?</totalWeight>
            <!--Optional:-->
            <totalHandlingUnits>?</totalHandlingUnits>
            <!--Optional:-->
            <hazmatFlag>?</hazmatFlag>
            <!--Optional:-->
            <expeditedCode>?</expeditedCode>
            <!--Optional:-->
            <whoRequested>?</whoRequested>
            <!--Optional:-->
            <trailer>
               <!--Optional:-->
               <trailerInfo>
                  <id>?</id>
                  <!--Optional:-->
                  <length>?</length>
                  <!--Optional:-->
                  <type>?</type>
               </trailerInfo>
            </trailer>
            <!--Optional:-->
            <referenceNumbers>
               <!--1 or more repetitions:-->
               <referenceNumber>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <referenceInfo>
                     <type>?</type>
                     <value>?</value>
                     <required>?</required>
                     <!--Optional:-->
                     <totalPieces>?</totalPieces>
                     <!--Optional:-->
                     <totalWeight>?</totalWeight>
                  </referenceInfo>
               </referenceNumber>
            </referenceNumbers>
            <!--Optional:-->
            <commodities>
               <!--1 or more repetitions:-->
               <commodity>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <commodityInfo>
                     <!--Optional:-->
                     <code>?</code>
                     <!--Optional:-->
                     <packageCode>?</packageCode>
                     <description>?</description>
                     <!--Optional:-->
                     <hazmat>
                        <!--Optional:-->
                        <hazmatCode>?</hazmatCode>
                        <!--Optional:-->
                        <hazmatFlag>?</hazmatFlag>
                     </hazmat>
                     <!--Optional:-->
                     <pieces>?</pieces>
                     <!--Optional:-->
                     <weight>?</weight>
                     <!--Optional:-->
                     <nmfcNumber>?</nmfcNumber>
                     <!--Optional:-->
                     <nmfcSubNumber>?</nmfcSubNumber>
                  </commodityInfo>
               </commodity>
            </commodities>
            <!--Optional:-->
            <comments>
               <!--1 or more repetitions:-->
               <comment>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <commentInfo>
                     <type>?</type>
                     <commentText>?</commentText>
                  </commentInfo>
               </comment>
            </comments>
            <!--Optional:-->
            <addresses>
               <!--1 or more repetitions:-->
               <address>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <addressInfo>
                     <addressType>?</addressType>
                     <addressLine1>?</addressLine1>
                     <!--Optional:-->
                     <addressLine2>?</addressLine2>
                     <city>?</city>
                     <stateProvince>?</stateProvince>
                     <postalCode>?</postalCode>
                     <!--Optional:-->
                     <postalCode4>?</postalCode4>
                     <countryAbbrev>?</countryAbbrev>
                  </addressInfo>
               </address>
            </addresses>
            <!--Optional:-->
            <contacts>
               <!--1 or more repetitions:-->
               <contact>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <contactInfo>
                     <contactType>?</contactType>
                     <name>
                        <!--Optional:-->
                        <firstName>?</firstName>
                        <!--Optional:-->
                        <middleName>?</middleName>
                        <!--Optional:-->
                        <lastName>?</lastName>
                     </name>
                     <!--Optional:-->
                     <email>?</email>
                     <phone>
                        <areaCode>?</areaCode>
                        <number>?</number>
                        <!--Optional:-->
                        <extension>?</extension>
                     </phone>
                     <!--Optional:-->
                     <fax>
                        <areaCode>?</areaCode>
                        <number>?</number>
                     </fax>
                     <!--Optional:-->
                     <receiveNotifications>?</receiveNotifications>
                     <!--Optional:-->
                     <notificationMethod>?</notificationMethod>
                  </contactInfo>
               </contact>
            </contacts>
            <!--Optional:-->
            <notifications>
               <!--1 or more repetitions:-->
               <notification>
                  <!--Optional:-->
                  <id>?</id>
                  <!--Optional:-->
                  <operation>
                     <operationType>?</operationType>
                  </operation>
                  <!--Optional:-->
                  <notificationInfo>
                     <type>?</type>
                  </notificationInfo>
               </notification>
            </notifications>
         </pickupRequestInput>
      </est:createPickupRequestWS>
   </soapenv:Body>
</soapenv:Envelope>
			    

Example Input

Here is an example of a Create Pickup Request.

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:pic="https://www.estes-express.com/tools/pickup">
   <soapenv:Header/>
   <soapenv:Body>
      <pic:createPickupRequestWS>
         <pickupRequestInput>
            <!--Optional:-->
            <requestNumber>2016-05-26</requestNumber>
            <shipper>
               <shipperName>Al</shipperName>
               <!--Optional:-->
               <accountCode>1234567</accountCode>
               <!--Optional:-->
               <shipperAddress>
                  <!--Optional:-->
                  <addressInfo>
                     <addressLine1>5307 Appleseed Lane</addressLine1>
                     <!--Optional:-->
                     <addressLine2>?</addressLine2>
                     <city>Portland</city>
                     <stateProvince>OR</stateProvince>
                     <postalCode>97086</postalCode>
                     <!--Optional:-->
                     <countryAbbrev>US</countryAbbrev>
                  </addressInfo>
               </shipperAddress>
               <!--Optional:-->
            </shipper>
            <!--Optional:-->
            <requestAction>LL</requestAction>
            <pickupDate>2016-05-25</pickupDate>
            <!--Optional:-->
            <pickupStartTime>0800</pickupStartTime>
            <!--Optional:-->
            <pickupEndTime>1500</pickupEndTime>
            <!--Optional:-->
            <totalPieces>1</totalPieces>
            <!--Optional:-->
            <totalWeight>100</totalWeight>
            <!--Optional:-->
            <totalHandlingUnits>1</totalHandlingUnits>
            <!--Optional:-->
            <hazmatFlag>N</hazmatFlag>
            <!--Optional:-->
            <whoRequested>S</whoRequested>
            <!--Optional:-->
         </pickupRequestInput>
      </pic:createPickupRequestWS>
   </soapenv:Body>
</soapenv:Envelope>
            

Output

This operation will respond with the following format if all validations are passed, and the pickup request is created in the Estes Pickup System.

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ser-root:createPickupRequestWSResponse xmlns:ser-root="https://estespickup.base.ws.provider.soapws.pickupRequest" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <requestNumber>50666</requestNumber>
        <infoMessages/>
        </ser-root:createPickupRequestWSResponse>
    </soapenv:Body>
</soapenv:Envelope>
		    	

Example Output

Here is an example of a Create Pickup Request Response.

<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ser-root:createPickupRequestWSResponse xmlns:ser-root="https://www.estes-express.com/tools/pickup" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <requestNumber>36321343</requestNumber>
         <infoMessages/>
      </ser-root:createPickupRequestWSResponse>
   </soapenv:Body>
</soapenv:Envelope>
            

Errors & Exceptions

The web service authentication will fail if the user is not authorized. Authentication will also fail if the username and password are not from a valid and active My Estes profile.

If a business validation rule is violated, an error code and description will be returned to the user in the following format:

<error>
    <elementName/>
    <code>PKE2050</code>
    <description>Shipper state must be a valid state abbreviation.</description>
    <badData></badData>
</error>

NOTE: Business validation error codes have three letters followed by four numbers.				

Exceptions

Several error conditions will cause exceptions (faults) in the web service. You can view these error codes and their associated descriptions as a PDF or downloaded as a CSV.