Shipping a Package

So you've displayed estimated shipping costs to your customer, they've selected an option, confirmed their order, and completed payment. Now it's time to actually ship the package. This call requires a little more detail than the rate requests (a full address is required, including contact information), but other than that, they look quite similar:

 $request = <<< XMLREQUEST <?xml version="1.0" encoding="UTF-8" ?>   <FDXShipRequest xmlns:api="http://www.fedex.com/fsmapi"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xsi:noNamespaceSchemaLocation="FDXShipRequest.xsd">   <RequestHeader>     <CustomerTransactionIdentifier>1</CustomerTransactionIdentifier>     <AccountNumber>$accountNumber</AccountNumber>     <MeterNumber>$meterNumber</MeterNumber>     <CarrierCode>$carrier</CarrierCode>   </RequestHeader>   <DropoffType>REGULARPICKUP</DropoffType>   <Service>PRIORITYOVERNIGHT</Service>   <Packaging>FEDEXBOX</Packaging>   <WeightUnits>LBS</WeightUnits>   <Weight>4.0</Weight>   <Origin>     <Contact>       <PersonName>Paul Reinheimer</PersonName>       <CompanyName>Wrox</CompanyName>       <PhoneNumber>5191234567</PhoneNumber>       <E-MailAddress>[e-mail]</E-MailAddress>     </Contact>     <Address>       <Line1>564 Elm Street</Line1>       <Line2>Little Nook under the stairs</Line2>       <City>NowhereVille</City>       <StateOrProvinceCode>TN</StateOrProvinceCode>       <PostalCode>38017</PostalCode>       <CountryCode>US</CountryCode>     </Address>   </Origin>   <Destination>     <Contact>       <PersonName>Chris Shiflett</PersonName>       <CompanyName>Wrox</CompanyName>       <PhoneNumber>6121234567</PhoneNumber>       <E-MailAddress>[e-mail]</E-MailAddress>     </Contact>     <Address>       <Line1>37 East 14th St</Line1>       <Line2>Suite 204</Line2>       <City>New York</City>       <StateOrProvinceCode>NY</StateOrProvinceCode>       <PostalCode>10011</PostalCode>       <CountryCode>US</CountryCode>     </Address>   </Destination>   <SpecialServices>     <EMailNotification>       <Shipper>         <ShipAlert>1</ShipAlert>         <DeliveryNotification>1</DeliveryNotification>         <LanguageCode>EN</LanguageCode>       </Shipper>       <Recipient>         <ShipAlert>1</ShipAlert>         <DeliveryNotification>1</DeliveryNotification>         <LanguageCode>EN</LanguageCode>       </Recipient>     </EMailNotification>   </SpecialServices>   <Payment>     <PayorType>SENDER</PayorType>   </Payment>   <ReferenceInfo>     <CustomerReference>Order 6541325</CustomerReference>   </ReferenceInfo>   <Label>     <Type>2DCOMMON</Type>     <ImageType>PNG</ImageType>   </Label>   </FDXShipRequest> XMLREQUEST; 

Apart from the familiar elements, and the ones with obvious use (the address information), there are a few new elements here worthy of note:

• SpecialServices - EMailNotification — Here you can specify up to four parties to be notified by email when the package is shipped and delivered. The first two shown in this example, the sender and receiver, have already had their email addresses set in the Contact portion of the request. If a Broker is also included with the request (for international shipments requiring a customs broker, when you have chosen to use a broker other than FedEx), they can also be included here for email notification. Finally, you can also add an Other tree, with the same elements as shown in the preceding code (ShipAlert, DeliveryNotification, LanguageCode) as well as E-MailAddress.

• SpecialServices - Other — FedEx provides the ability to include a large number of special services with your shipment such as dry ice, hazardous materials shipment, alcohol shipment, and so on. Please see the API's documentation for more information on these options.

• ReferenceInfo — This allows you to specify an extra piece of information that will be printed on the shipping label. The customer's order number would be a great choice.

• Label — This allows you to specify how FedEx should return label information to you. Your options are 2DCOMMON and PNG as shown here, which are to be used with a laser printer (inkjets or deskjets are not acceptable) or one of several thermal printer options. For more information on the thermal printing options, please see the API's documentation.

The response will look like this:

 <?xml version="1.0" encoding="UTF-8"?> <FDXShipReply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FDXShipReply.xsd">   <ReplyHeader>     <CustomerTransactionIdentifier>1</CustomerTransactionIdentifier>   </ReplyHeader>   <Tracking>     <TrackingNumber>470034028693</TrackingNumber>     <FormID>0201</FormID>     <CodReturnTrackingNumber></CodReturnTrackingNumber>   </Tracking>   <ServiceTypeDescription>PRIORITY OVERNIGHT</ServiceTypeDescription>   <PackagingDescription>BOX</PackagingDescription>   <EstimatedCharges>     <DimWeightUsed>false</DimWeightUsed>     <RateScale>01552</RateScale>     <RateZone>5</RateZone>     <CurrencyCode>USD</CurrencyCode>     <BilledWeight>4.0</BilledWeight>     <DimWeight>0.0</DimWeight>     <DiscountedCharges>       <BaseCharge>38.20</BaseCharge>       <TotalDiscount>0.00</TotalDiscount>       <Surcharges>        <Fuel>4.39</Fuel>       </Surcharges>       <TotalSurcharge>4.39</TotalSurcharge>       <NetCharge>42.59</NetCharge>       <TotalRebate>0.00</TotalRebate>     </DiscountedCharges>     <ListCharges>      <Surcharges/>     </ListCharges>   </EstimatedCharges>   <Routing>   <UrsaRoutingCode>XAKLLA</UrsaRoutingCode>   <ServiceCommitment>A1</ServiceCommitment>   <DeliveryDay>TUE</DeliveryDay>   <DestinationStationID>EWR</DestinationStationID>   <DeliveryDate>14FEB06</DeliveryDate>   <UrsaPrefixCode>XA</UrsaPrefixCode>   </Routing>   <Labels>     <OutboundLabel>XXXX</OutboundLabel>   </Labels>   <SignatureOption>NONE</SignatureOption> </FDXShipReply> 

Particular items to note here include the TrackingNumber, DeliveryDate, and OutboundLabel. The tracking number is the useful little number customers can enter into the FedEx website to obtain information on the current status of their package. DeliveryDate is the estimated delivery date for the package. Finally, OutboundLabel includes a Base64-encoded .png image of the shipping label that needs to be printed off (this is covered shortly) and attached to the package (likely in a FedEx-provided pouch).

Here is the code used to execute the request and save the shipping label:

 echo "<h3>Request</h3>\n"; echo "<pre>\n"; print_r(simplexml_load_string($request)); echo "</pre>\n"; echo "<h3>Response</h3>\n"; $response = callFedEx($request); echo "Shipment Confirmed, your tracking number is: " .     $response->Tracking->TrackingNumber; echo "<pre>"; print_r($response); $label = base64_decode($response->Labels->OutboundLabel); file_put_contents("/str/label/{$response->Tracking->TrackingNumber}.png", $label); echo "</pre>"; 

As you can see, extracting the shipping label is as easy as using the base64_decode() function, then saving the output to a file. I've used the tracking number from the order as a filename; you may wish to use the customer's order number or the like instead. The shipping label itself should look somewhat similar to Figure 8-2.

Figure 8-2

Both your address and the address of the recipient are clearly shown, and on the right-hand side of the label you can also see the contents of the CustomerReference field. The API documentation includes a 13-page document specifying exactly how labels are to be printed. In short, this .png file is going to be printed on a standard 8.5-×-11-inch piece of paper (portrait mode) so that the resulting image is 7 × 4.5 inches (that's a 3/4-inch margin on each side of the paper). This works out perfectly for the page to be folded in half and then placed inside the document pouch attached to the package.