Ship/FX API Management (Developer Resources)
NOTE: For information on the eFORMz API, consult the following: eFORMz API Management (Developer Resources)
NOTE: For more information on implementing Ship/FX, consult the following: Ship/FX
Standard elements to get a shipping label
The basic data structure to retrieve a shipping label with Ship/FX is presented in both XML and JSON formats below, along with a sample Postman collection. The collection shows both short form and long form URLs. The URL ‘shortcuts’ are stored in the file translate/WebServerURLTranslations.xml. The elements present in the sample include blank values for elements not required by the sample carrier/service combination. The OutputFormat and Name in the request will determine the size and format of the shipping label.
XML: ShipBasicXML
JSON: ShipBasicJSON
<Shipment> – Everything pertaining to the shipping label that is generated
<Document> – The properties of the label, including <Profile>, <Name> and <OutputFormat>
<Account> – The customer-specific collection of profiles used in their shipping environment
<Profile> – This is a category of shipment types, a collection of providers. For example, the shipment type Domestic could include several providers
<Provider> – This is the API
<Carrier> – The carrier delivering the package
<Service> – Packaging and rating details
<PaymentType> – This is for billing. Examples include SENDER, THIRD_PARTY, COLLECT, etc.)
<Debug> – This is a full dump of the returned XML or JSON from the carrier. It is a useful place to look in case an API error is returned
<ShipDateTime> – The <DateTime> declaration includes: <Year>, <Month>, <Day>, <Hour>, <Minute>, <Second>, <TimezoneHour> and <TimezoneMinute>
<Recipient> – The <Address> of the recipient, including: <ContactId>, <PersonName>, <CompanyName>, <PhoneNumber>, <EMail>, <AddressLine1> (1-5), <City>, <StateOrProvince>, <PostalCode>, <CountryCode>, <CountryName>, <IsResidential>, <TaxId1>, <TaxId2>, <Validate> and <UseCorrectedAddress>
<Shipper> – The <Address> of the sender, that is, the ship to company, including: <ContactId>, <PersonName>, <CompanyName>, <PhoneNumber>, <EMail>, <AddressLine1> (1-5), <City>, <StateOrProvince>, <PostalCode>, <CountryCode>, <CountryName>, <IsResidential>, <TaxId1>, <TaxId2>, <Validate> and <UseCorrectedAddress>
<Packages> – Specifies the <DropoffType> and all aspects of the <Package>, including: <PackagingType>, <WeightUOM>, <Weight>, <DimUOM>, <DimLength>, <DimWidth>, <DimHeight> and references, such as <Reference1>, which includes <Type> and <Value>. For example, <Type>PO</Type><Value>PONUMBER</Value>. Finally, <Insurance>, which contains <Currency> and <Amount>
<Options> – Special delivery configuration, including: <SaturdayDelivery>, <IndirectSignatureRequired>, <SignatureRequired> and <AdultSignatureRequired>
<Labels> – The specifications of the <ShippingLabel>, including all aspects of the <Label>: <Format>, <Size>, which contains <Width> and <Height>, and <IsReturn>, which defines if the label is a return or not
<CarrierOptions> – The <Option> tag includes: <Provider>, <Carrier>, <Name> and <Value>
Sample Postman collection (XML/JSON)
Download the sample Postman collection here: ShipFX.postman_collection
ShipFX ShipmentDocumentsXMLWS
<?xml version="1.0" encoding="UTF-8"?> <Shipment> <Document> <Profile>eSHIP_DocumentProducer_Projects</Profile> <Name>4x6SimplexLabel</Name> <OutputFormat>PDF</OutputFormat> </Document> <Account>000001</Account> <Profile>Domestic</Profile> <Provider>UPS API</Provider> <Carrier>UPS</Carrier> <Service>02</Service> <PaymentType>SENDER</PaymentType> <Debug>true</Debug> <ShipDateTime> <DateTime> <Year>2020</Year> <Month>09</Month> <Day>22</Day> <Hour>10</Hour> <Minute>00</Minute> <Second>00</Second> <TimezoneHour>-08</TimezoneHour> <TimezoneMinute>00</TimezoneMinute> </DateTime> </ShipDateTime> <Recipient> <Address> <ContactId /> <PersonName>John Doe</PersonName> <CompanyName /> <PhoneNumber>978-335-3273</PhoneNumber> <EMail /> <AddressLine1>2300 Bonita Canyon Dr</AddressLine1> <AddressLine2>#1050</AddressLine2> <AddressLine3 /> <AddressLine4 /> <AddressLine5 /> <City>Newport Beach</City> <StateOrProvince>CA</StateOrProvince> <PostalCode>92660</PostalCode> <CountryCode>US</CountryCode> <CountryName /> <IsResidential>true</IsResidential> <TaxId1 /> <TaxId2 /> <Validate /> <UseCorrectedAddress /> </Address> </Recipient> <Shipper> <Address> <ContactId /> <PersonName>SHIPPING</PersonName> <CompanyName>Just Food for Dogs</CompanyName> <PhoneNumber>123-233-2670</PhoneNumber> <EMail>hknickerbocker@minisoft.com</EMail> <AddressLine1>103 E 17th St</AddressLine1> <AddressLine2>Apt 123</AddressLine2> <AddressLine3 /> <AddressLine4 /> <AddressLine5 /> <City>Costa Mesa</City> <StateOrProvince>CA</StateOrProvince> <PostalCode>92626</PostalCode> <CountryCode>US</CountryCode> <CountryName /> <IsResidential /> <TaxId1 /> <TaxId2 /> <Validate /> <UseCorrectedAddress /> </Address> </Shipper> <Packages> <DropoffType>REGULAR_PICKUP</DropoffType> <Package> <PackagingType>CUSTOM_PACKAGE</PackagingType> <WeightUOM>LB</WeightUOM> <Weight>1.5</Weight> <DimUOM>IN</DimUOM> <DimLength>10</DimLength> <DimWidth>10</DimWidth> <DimHeight>4</DimHeight> <Reference1> <Type>PO</Type> <Value>PONUMBER</Value> </Reference1> <Reference2> <Type>DEP</Type> <Value>DEPTNUMBER</Value> </Reference2> <Reference3> <Type>RMA</Type> <Value>RMANUMBER</Value> </Reference3> <Reference4> <Type>INV</Type> <Value>INVOICENUMBER</Value> </Reference4> <Reference5> <Type>URL</Type> <Value>https://www.minisoft.com</Value> </Reference5> <Insurance> <Currency>USD</Currency> <Amount>40</Amount> </Insurance> </Package> </Packages> <Options> <SaturdayDelivery /> <IndirectSignatureRequired/> <SignatureRequired>false</SignatureRequired> <AdultSignatureRequired>true</AdultSignatureRequired> </Options> <Labels> <ShippingLabel> <Label> <Format>ZPL</Format> <Size> <Width>4</Width> <Height>6</Height> </Size> <IsReturn /> </Label> </ShippingLabel> </Labels> <CarrierOptions> <Option> <Provider>FEDEX Sameday</Provider> <Carrier>FEDEX</Carrier> <Name>SAME_DAY_RETURN_TO_SENDER</Name> <Value /> </Option> </CarrierOptions> </Shipment>
ShipFX ShipmentDocumentsJSON
{
"Shipment": {
"Account": "000001",
"Options": {
"SaturdayDelivery": "",
"AdultSignatureRequired": true,
"SignatureRequired": false,
"IndirectSignatureRequired": ""
},
"Service": "02",
"Recipient": {
"Address": {
"PersonName": "John Doe",
"CountryName": "",
"StateOrProvince": "CA",
"PostalCode": 92660,
"TaxId2": "",
"ContactId": "",
"City": "Newport Beach",
"EMail": "",
"TaxId1": "",
"AddressLine3": "",
"CompanyName": "",
"AddressLine2": "#1050",
"IsResidential": true,
"AddressLine1": "2300 Bonita Canyon Dr",
"UseCorrectedAddress": "",
"Validate": "",
"AddressLine5": "",
"AddressLine4": "",
"PhoneNumber": "978-335-3273",
"CountryCode": "US"
}
},
"Labels": {
"ShippingLabel": {
"Label": {
"Format": "ZPL",
"Size": {
"Height": 6,
"Width": 4
},
"IsReturn": ""
}
}
},
"Document": {
"OutputFormat": "PDF",
"Profile": "eSHIP_DocumentProducer_Projects",
"Name": "4x6SimplexLabel"
},
"Profile": "Domestic",
"CarrierOptions": {
"Option": {
"Value": "",
"Carrier": "FEDEX",
"Provider": "FEDEX Sameday",
"Name": "SAME_DAY_RETURN_TO_SENDER"
}
},
"Provider": "UPS API",
"ShipDateTime": {
"DateTime": {
"Month": "09",
"Year": 2020,
"Minute": "00",
"Second": "00",
"Hour": 10,
"TimezoneMinute": "00",
"TimezoneHour": "-08",
"Day": 22
}
},
"Packages": {
"DropoffType": "REGULAR_PICKUP",
"Package": {
"WeightUOM": "LB",
"DimHeight": 4,
"DimWidth": 10,
"DimLength": 10,
"Weight": 1.5,
"DimUOM": "IN",
"Reference5": {
"Type": "URL",
"Value": "https://www.minisoft.com"
},
"Reference3": {
"Type": "RMA",
"Value": "RMANUMBER"
},
"Insurance": {
"Currency": "USD",
"Amount": 40
},
"Reference4": {
"Type": "INV",
"Value": "INVOICENUMBER"
},
"Reference1": {
"Type": "PO",
"Value": "PONUMBER"
},
"Reference2": {
"Type": "DEP",
"Value": "DEPTNUMBER"
},
"PackagingType": "CUSTOM_PACKAGE"
}
},
"Shipper": {
"Address": {
"PersonName": "SHIPPING",
"CountryName": "",
"StateOrProvince": "CA",
"PostalCode": 92626,
"TaxId2": "",
"ContactId": "",
"City": "Costa Mesa",
"EMail": "hknickerbocker@minisoft.com",
"TaxId1": "",
"AddressLine3": "",
"CompanyName": "Just Food for Dogs",
"AddressLine2": "Apt 123",
"IsResidential": "",
"AddressLine1": "103 E 17th St",
"UseCorrectedAddress": "",
"Validate": "",
"AddressLine5": "",
"AddressLine4": "",
"PhoneNumber": "123-456-2670",
"CountryCode": "US"
}
},
"PaymentType": "SENDER",
"Carrier": "UPS",
"Debug": true
}
}
ShipFX AddressValidationXMLWS
<Root> <Account> <![CDATA[000001]]> </Account> <Profile> <![CDATA[Domestic]]> </Profile> <Provider> <![CDATA[FEDEX API]]> </Provider> <Carrier> <![CDATA[FEDEX]]> </Carrier> <ShipToAddress> <ShipToName> <![CDATA[Ben Hirayama]]> </ShipToName> <ShipToCompanyName/> <ShipToAddressLine1> <![CDATA[1024 First St]]> </ShipToAddressLine1> <ShipToAddressLine2/> <ShipToAddressLine3/> <ShipToCity> <![CDATA[Snohomish]]> </ShipToCity> <ShipToState> <![CDATA[WA]]> </ShipToState> <ShipToZip> <![CDATA[98290]]> </ShipToZip> <ShipToCountryCode/> <ShipToCountryName/> <ShipToPhone/> </ShipToAddress> </Root>
ShipFX AddressValidationJSONWS
{
"Shipment": {
"Account": "000001",
"Options": {
"SaturdayDelivery": "",
"AdultSignatureRequired": true,
"SignatureRequired": false,
"IndirectSignatureRequired": ""
},
"Service": "02",
"Recipient": {
"Address": {
"PersonName": "John Doe",
"CountryName": "",
"StateOrProvince": "CA",
"PostalCode": 92660,
"TaxId2": "",
"ContactId": "",
"City": "Newport Beach",
"EMail": "",
"TaxId1": "",
"AddressLine3": "",
"CompanyName": "",
"AddressLine2": "#1050",
"IsResidential": true,
"AddressLine1": "2300 Bonita Canyon Dr",
"UseCorrectedAddress": "",
"Validate": "",
"AddressLine5": "",
"AddressLine4": "",
"PhoneNumber": "978-335-3273",
"CountryCode": "US"
}
},
"Labels": {
"ShippingLabel": {
"Label": {
"Format": "ZPL",
"Size": {
"Height": 6,
"Width": 4
},
"IsReturn": ""
}
}
},
"Document": {
"OutputFormat": "PDF",
"Profile": "eSHIP_DocumentProducer_Projects",
"Name": "4x6SimplexLabel"
},
"Profile": "Domestic",
"CarrierOptions": {
"Option": {
"Value": "",
"Carrier": "FEDEX",
"Provider": "FEDEX Sameday",
"Name": "SAME_DAY_RETURN_TO_SENDER"
}
},
"Provider": "UPS API",
"ShipDateTime": {
"DateTime": {
"Month": "09",
"Year": 2020,
"Minute": "00",
"Second": "00",
"Hour": 10,
"TimezoneMinute": "00",
"TimezoneHour": "-08",
"Day": 22
}
},
"Packages": {
"DropoffType": "REGULAR_PICKUP",
"Package": {
"WeightUOM": "LB",
"DimHeight": 4,
"DimWidth": 10,
"DimLength": 10,
"Weight": 1.5,
"DimUOM": "IN",
"Reference5": {
"Type": "URL",
"Value": "https://www.minisoft.com"
},
"Reference3": {
"Type": "RMA",
"Value": "RMANUMBER"
},
"Insurance": {
"Currency": "USD",
"Amount": 40
},
"Reference4": {
"Type": "INV",
"Value": "INVOICENUMBER"
},
"Reference1": {
"Type": "PO",
"Value": "PONUMBER"
},
"Reference2": {
"Type": "DEP",
"Value": "DEPTNUMBER"
},
"PackagingType": "CUSTOM_PACKAGE"
}
},
"Shipper": {
"Address": {
"PersonName": "SHIPPING",
"CountryName": "",
"StateOrProvince": "CA",
"PostalCode": 92626,
"TaxId2": "",
"ContactId": "",
"City": "Costa Mesa",
"EMail": "hknickerbocker@minisoft.com",
"TaxId1": "",
"AddressLine3": "",
"CompanyName": "Just Food for Dogs",
"AddressLine2": "Apt 123",
"IsResidential": "",
"AddressLine1": "103 E 17th St",
"UseCorrectedAddress": "",
"Validate": "",
"AddressLine5": "",
"AddressLine4": "",
"PhoneNumber": "123-456-2670",
"CountryCode": "US"
}
},
"PaymentType": "SENDER",
"Carrier": "UPS",
"Debug": true
}
}
Call ShipFX Void (XML)
<ShipmentDeleterRequest> <Account>000001</Account> <Profile>Domestic</Profile> <ShipmentId>123456789</ShipmentId> </ShipmentDeleterRequest>
Call ShipFX Get Rates (XML)
<GetRatesRequest> <Account>000001</Account> <Profile>Domestic</Profile> <RateGroup>RateShopAll</RateGroup> <SelectedProvider /> <SelectedCarrier /> <SelectedService /> <ShipDateTime /> <DeliveryByDateTime /> <ShipperObject> <Address> <ContactId /> <PersonName /> <CompanyName>Minisoft, Inc</CompanyName> <PhoneNumber>3605686602</PhoneNumber> <EMail>sales@minisoft.com</EMail> <AddressLine1>1024 First Street</AddressLine1> <AddressLine2 /> <AddressLine3 /> <AddressLine4 /> <AddressLine5 /> <City>Snohomish</City> <StateOrProvince>WA</StateOrProvince> <PostalCode>98290</PostalCode> <CountryCode>US</CountryCode> <CountryName /> <IsResidential /> <TaxId1 /> <TaxId2 /> <Validate /> <UseCorrectedAddress /> </Address> </ShipperObject> <RecipientObject> <Address> <ContactId /> <PersonName>Joe Grimm</PersonName> <CompanyName /> <PhoneNumber>4258837851</PhoneNumber> <EMail /> <AddressLine1>4062 N Black Rock Dr</AddressLine1> <AddressLine2 /> <AddressLine3 /> <AddressLine4 /> <AddressLine5 /> <City>Tucson</City> <StateOrProvince>AZ</StateOrProvince> <PostalCode>85750</PostalCode> <CountryCode>US</CountryCode> <CountryName /> <IsResidential /> <TaxId1 /> <TaxId2 /> <Validate /> <UseCorrectedAddress /> </Address> </RecipientObject> <PackagesObject> <Packages> <DropoffType>REGULAR_PICKUP</DropoffType> <DropoffLocation /> <Package> <CartonId /> <PackagingType>CUSTOM_PACKAGE</PackagingType> <WeightUOM>LB</WeightUOM> <Weight>1</Weight> <DimUOM>IN</DimUOM> <DimLength>6</DimLength> <DimWidth>6</DimWidth> <DimHeight>1</DimHeight> <Reference1> <Type /> <Value>Clothing</Value> </Reference1> <Insurance> <Currency>USD</Currency> <Amount>0</Amount> </Insurance> </Package> </Packages> </PackagesObject> <PaymentType>SENDER</PaymentType> <PayorAccountNumber /> <PayorObject /> <CustomsObject> <Customs> <Certify /> <Signer /> <Contents /> <RestrictionType /> <EEC_PFC /> <CommercialInvoiceNumber /> <TermsOfSale /> </Customs> </CustomsObject> <OptionsObject> <Options> <SaturdayDelivery /> <IndirectSignatureRequired /> <SignatureRequired /> <AdultSignatureRequired /> </Options> </OptionsObject> <CarrierOptionsObject> <CarrierOptions /> </CarrierOptionsObject> <Debug>false</Debug> </GetRatesRequest>
Call ShipFX Shipper (XML)
<ShipperRequest>
<Account>000001</Account>
<Profile>Domestic</Profile>
<RateGroup></RateGroup>
<Provider>AmazonMWS</Provider>
<Carrier>FEDEX</Carrier>
<Service>FEDEX_PTP_PRIORITY_OVERNIGHT</Service>
<OrderId>111-4660096-5601032</OrderId>
<Reference>111-4660096-5601032</Reference>
<ShipperObject>
<Address>
<ContactId />
<PersonName />
<CompanyName>Minisoft, Inc</CompanyName>
<PhoneNumber>3605686602</PhoneNumber>
<EMail>sales@minisoft.com</EMail>
<AddressLine1>1024 First Street</AddressLine1>
<AddressLine2 />
<AddressLine3 />
<AddressLine4 />
<AddressLine5 />
<City>Snohomish</City>
<StateOrProvince>WA</StateOrProvince>
<PostalCode>98290</PostalCode>
<CountryCode>US</CountryCode>
<CountryName />
<IsResidential />
<TaxId1 />
<TaxId2 />
<Validate />
<UseCorrectedAddress />
</Address>
</ShipperObject>
<RecipientObject>
<Address>
<ContactId />
<PersonName>Joe Grimm</PersonName>
<CompanyName />
<PhoneNumber>4258837851</PhoneNumber>
<EMail />
<AddressLine1>4062 N Black Rock Dr</AddressLine1>
<AddressLine2 />
<AddressLine3 />
<AddressLine4 />
<AddressLine5 />
<City>Tucson</City>
<StateOrProvince>AZ</StateOrProvince>
<PostalCode>85750</PostalCode>
<CountryCode>US</CountryCode>
<CountryName />
<IsResidential />
<TaxId1 />
<TaxId2 />
<Validate />
<UseCorrectedAddress />
</Address>
</RecipientObject>
<PackagesObject>
<Packages>
<DropoffType/>
<DropoffLocation />
<Package>
<CartonId />
<PackagingType>CUSTOM_PACKAGE</PackagingType>
<WeightUOM>LB</WeightUOM>
<Weight>1</Weight>
<DimUOM>IN</DimUOM>
<DimLength>6</DimLength>
<DimWidth>6</DimWidth>
<DimHeight>1</DimHeight>
<Reference1>
<Type />
<Value>Clothing</Value>
</Reference1>
<Insurance>
<Currency>USD</Currency>
<Amount>0</Amount>
</Insurance>
</Package>
</Packages>
</PackagesObject>
<PaymentType>SENDER</PaymentType>
<PayorAccountNumber />
<PayorObject />
<CustomsObject>
<Customs>
<Certify />
<Signer />
<Contents />
<RestrictionType />
<EEC_PFC />
<CommercialInvoiceNumber />
<TermsOfSale />
</Customs>
</CustomsObject>
<OptionsObject>
<Options>
<SaturdayDelivery />
<IndirectSignatureRequired />
<SignatureRequired />
<AdultSignatureRequired />
</Options>
</OptionsObject>
<CarrierOptionsObject>
<CarrierOptions />
</CarrierOptionsObject>
<Debug>false</Debug>
</ShipperRequest>
Call ShipFX TrackingWS (XML)
<Root> <Account> <![CDATA[000001]]></Account> <Profile> <![CDATA[Domestic]]></Profile> <Provider> <![CDATA[AmazonMWS]]></Provider> <Carrier> <![CDATA[FEDEX]]></Carrier> <TrackingNumber> <![CDATA[282463613453]]></TrackingNumber> </Root>
Tag: Make an API call; Address validation; Address verification