This document specifies how to call the XML HTTP POST method of generating automated bills of lading and pickup requests via XML. This is useful for allowing your customers to create bills of lading and pickup requests online via your website.
Please strip out all non-standard or special characters from text fields. Including such characters in text fields will cause requests to fail.
To call the FACTS XML Bill of Lading Request API, an XML document containing the appropriate variables should be posted to the tbolnav4.xml function as variable name xmlreq.
www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/tbolentry4.xml%3fxmlreq=some xml
Alternatively, variables can be posted directly to the function as arguments of the xmlv=yes argument is included:
https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1tbolentry4.xml?xmlv=yes&var1=a&var2=b
The list of variables is as follows:
| Variable Name | Required | Contents |
|---|---|---|
| xmluser or UserName | Yes | Username |
| xmlpass or Password | Yes | Password |
| ShipIDm or shipaddrno | No | Shipper Address No |
| shipname | No � defaults to location | Shipper Name |
| shipaddr | No � defaults to location | Shipper Address |
| shipaddr2 | No � defaults to location | Shipper Address 2 |
| shipcity | No � defaults to location | Shipper City |
| shipst | No � defaults to location | Shipper State |
| shipzip | No � defaults to location | Shipper Zip |
| shipcont | No � defaults to location | Shipper Contact |
| shipphone | No � defaults to location | Shipper Phone |
| shipemail | No � defaults to location | Shipper Email |
| ConsID or consaddrno | No | Consignee Address No |
| consname | Required if consignee ID not provided | Consignee Name |
| consaddr | Required if consignee ID not provided | Consignee Address |
| consaddr2 | No | Consignee Address 2 |
| conscity | Required if consignee ID not provided | Consignee City |
| consst | Required if consignee ID not provided | Consignee State |
| conszip | Required if consignee ID not provided | ConsigneeZip |
| conscont | Required if consignee ID not provided | Consignee Contact |
| consphone | Required if consignee ID not provided | Consignee Phone |
| conssecphone | No | Consignee Second Phone |
| consemail | No | Consignee Email |
| bolno | No | Bill of Lading Number |
| pono | No | Purchase Order Number |
| billref | No | Debtor Account Number |
| declval | No | Declared Value |
| codamt | No | COD Amount |
| codcert | No | Yes or No Are certified funds required |
| codto | No | COD Payable To |
| hazphone | Yes if any line items are hazardous | HazMat contact phone number |
| spcinstr | No | Special Instructions |
| bolmails | No | Yes or No Email the BOL to the shipper |
| shipmails | No | Yes or No Send a shipment notification email to the shipper |
| apptmails | No | Yes or No Send an appointment notification email to the shipper |
| ofdmails | No | Yes or No. Send an ofd notification email to the shipper |
| delmails | No | Yes or No. Send a delivery notification email to the shipper |
| bolmailc | No | Yes or No. Email the BOL to the consignee |
| shipmailc | No | Yes or No. Send a shipment notification email to the consignee |
| apptmailc | No | Yes or No. Send an appointment notification email to the consignee |
| ofdmailc | No | Yes or No. Send an ofd notification email to the consignee |
| delmailc | No | Yesor No. Send a delivery notification email to the consignee |
| email1 | No | Extra email address 1 |
| bolmail1 | No | Yes or No. Email the BOL to extra email address 1 |
| shipmail1 | No | Yes or No. Send a shipment notification email to extra email address 1 |
| apptmail1 | No | Yes or No. Send an appointment notification email to extra email address 1 |
| ofdmail1 | No | Yes or No. Send an ofd notification email to extra email address 1 |
| delmail1 | No | Yes or No. Send a delivery notification email to extra email address 1 |
| email2 | No | Extra email address 2 |
| bolmail2 | No | Yes or No. Email the BOL to extra email address 2 |
| shipmail2 | No | Yes or No, Send a shipment notification email to extra email address 2 |
| apptmail2 | No | Yes or No, Send an appointment notification email to extra email address 2 |
| ofdmail2 | No | Yes or No, Send an ofd notification email to extra email address 2 |
| delmail2 | No | Yes or No, Send a delivery notification email to extra email address 2 |
| pieces1 | Yes | Pieces count for line 1 |
| pallets1 | No | Pallets count for line 1 |
| hazmat1 | No | Yes or No, Is line 1 hazardous |
| descr1 | Yes | Description for line 1 |
| weight1 | Yes | Weight for line 1 in pounds |
| density1 | No | Density for line 1 in pcf |
| model1 or MFNC1 or modelno1 | No | Model number for line 1 |
| length1 | No1 | Length for line1 in inches |
| width1 | No1 | Width for line1 in inches |
| height1 | No1 | Height for line 1 in inches |
|
Note: the pieces, pallets, hazmat, descr, weight, density, model, length, width, height and packytype fields can be repeated for lines 2 through 8 |
||
| pucontact | Yes | Pickup Contact |
| puphone | No | Pickup contact phone number |
| pudate | No | Pickup Date |
| putime | No | Pickup Time (HHMM) |
| puemail | No | Pickup Contact email |
| closetime | Yes | Close Time (HHMM) |
| punotes | No | Pickup Notes |
| accessoriallist or ExtraSvcList2 | No | Comma separated list of accessorial codes to be included. |
|
1Note: If one dimension is supplied for a line item, all three dimensions must be supplied |
||
|
2Note: extra services can also be specified by including the service code as a variable with as value of YES, or by including an ExtraSvc section in the xml. See the examples below |
||
Consider the following simple example:
| Variable | Value |
|---|---|
| UserName | Testuser |
| Password | Testpass |
| ConsID | AAA (note: must match a valid consignee record) |
| pieces1 | 1 |
| weight1 | 350 |
| descr1 | Steel Parts |
| closetime | 2100 (9:00 pm) |
These variables can be arranged into an xml document as follows:
<bol>
<UserName>testuser</UserName>
<Password>testpass</Password>
<ConsID>aaa</ConsID>
<pieces1>1</pieces1>
<weight1>350</weight1>
<descr1>Steel Parts</descr1>
<class1>085</class1>
<closetime>2100</closetime>
</bol>
Note that the order of the variables within the XML document does not matter.
The HTTPS request would be:
https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/tbolentry4.xml?xmlreq=<bol><UserName>testuser</UserName><Password>testpass</Password><ConsID>AAA</ConsID><pieces1>1</pieces1><weight1>350</weight1><descr1>Steel_Parts</descr1><closetime>2100</closetime></bol>
Or, the variables can be added to the URL as arguments:
https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/tbolentry4.xml?xmlv=yes&UserName=testuser&Password=testpass&ConsID=AAA&pieces1=1&weight1=350&descr1=Steel_Parts&closetime=2100
Here is a more complex example:
| Variable | Value |
|---|---|
| UserName | Testuser |
| Password | Testpass |
| shipname | CHM Industries |
| Shipaddr | 1010 Florida Ave |
| Shipcity | Chicago |
| Shipst | IL |
| Shipzip | 60067 |
| shipphone | 800-123-4567 |
| Shipcont | Mike Jones |
| shipemail | mike@test.com |
| consname | AAA Manufacturing |
| Consaddr | 100 Main Street |
| Conscity | Crystal Lake |
| Consst | IL |
| Conszip | 60012 |
| Conscont | Chris |
| conphone | 800-222-3333 |
| consemail | chris@aaamanuf.com |
| Pono | PO1234 |
| Billref | 003700 |
| Declval | 400 |
| Bolmails | Yes |
| Delmails | Yes |
| Ofdmailc | Yes |
| pieces1 | 1 |
| pallets1 | 1 |
| weight1 | 10 |
| model1 | 0742216G |
| pieces2 | 1 |
| pallets2 | 1 |
| weight2 | 800 |
| descr2 | Engine block |
| accessoriallist | LIFT, INSIDE |
| pucontact | Sam Spade |
| Puphone | 800-111-2222 |
| Puemail | dock@test.com |
| Putime | 1100 |
| Closetime | 2100 |
Note that a list of accessorial codes can be obtained by running the keywordlist function:
https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/keywordlist.xml
The XML for the above list of variables would be:
<bol>
<UserName>testuser</UserName>
<Password>testpass</Password>
<shipname>CHM Industries</shipname>
<shipaddr>1010 Florida Ave</shipaddr>
<shipcity>Chicago</shipcity>
<shipst>IL</shipst>
<shipzip>60067</shipzip>
<shipphone>800-123-4567</shipphone>
<shipcont>Mike Jones</shipcont>
<shipemail>mike@test.com</shipemail>
<consname>AAA Manufacturing</consname>
<consaddr>100 Main Street</consaddr>
<conscity>Crystal Lake</conscity>
<consst>IL</consst>
<conszip>60012</conszip>
<conscont>Chris</conscont>
<consphone>800-222-3333</consphone>
<consemail>chris@aaamanuf.com</consemail>
<pono>PO1234</pono>
<billref>003700</billref>
<declval>400</declval>
<bolmails>yes</bolmails>
<delmails>Yes</delmails>
<ofdmailc>yes</ofdmailc>
<pieces1>1</pieces1>
<pallets1>1</pallets1>
<weight1>10</weight1>
<model1>0742216G</model1>
<pieces2>1</pieces2>
<weight2>800</weight2>
<descr2>Engine block</descr2>
<accessoriallist>LIFT,INSIDE</accessoriallist>
<pucontact>Sam Spade</pucontact>
<puphone>800-111-2222</puphone>
<puemail>dock@test.com</puemail>
<putime>1100</putime>
<closetime>2100</closetime>
</bol>
Note that there are alternative ways to submit the accessorial codes.
Instead of
<accessoriallist>LIFT,INSIDE</accessorallist>
The XML could contain:
<LIFT>yes</LIFT>
<INSIDE>yes</INSIDE>
Or
<accessorials>
<accessorial>LIFT</accessorial>
<accessorial>INSIDE</accessorial>
</accessorials>
Or
<ExtraSvc>
<ExtraSvcType>LIFT</ExtraSvcType>
<ExtraSvcType>INSIDE</ExtraSvcType>
</ExtraSvc>
The URL for the above example would be:
https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/tbolentry4.xml?xmlreq=<bol><UserName>testuser</UserName><Password>testpass</Password><shipname>CHM%20Industries</shipname><shipaddr>1010%20Florida%20Ave</shipaddr><shipcity>Chicago</shipcity><shipst>IL</shipst><shipzip>60067</shipzip><shipphone>800-123-4567</shipphone><shipcont>Mike%20Jones</shipcont><shipemail>mike@test.com</shipemail><consname>AAA%20Manufacturing</consname><consaddr>100%20Main%20Street</consaddr><conscity>Crystal%20Lake</conscity><consst>IL</consst><conszip>60012</conszip><conscont>Chris</conscont><consphone>800-222-3333</consphone><consemail>chris@aaamanuf.com</consemail><pono>PO1234</pono><billref>003700</billref><declval>400</declval><bolmails>yes</bolmails><delmails>Yes</delmails><ofdmailc>yes</ofdmailc><pieces1>1</pieces1><pallets1>1</pallets1><weight1>10</weight1><model1>0742216G</model1><pieces2>1</pieces2><weight2>800</weight2><descr2>Engine%20block</descr2><accessoriallist>LIFT,INSIDE</accessoriallist><pucontact>Sam%20Spade</pucontact><puphone>800-111-2222</puphone><puemail>dock@test.com</puemail><putime>1100</putime><closetime>2100</closetime></bol>
Responses will be in XML format. There are two possible response types, a successful response and a failure response.
The success response will contain some of the shipment details as well as links to the bill of lading and shipping labels for the shipment.
For Example:
<response>
<responsetype>BOL and Pickup Entry</responsetype>
<success>Yes</success>
<bol>
<pronumber>1082603</pronumber>
<trackingnumber>1082603</trackingnumber>
<referencenumber>CLITEST</referencenumber>
<shippername>CLI TEST ONLY</shippername>
<shipperaddress>123 TEST STREET</shipperaddress>
<shippercity>Brooklyn</shippercity>
<shipperstate>NY</shipperstate>
<shipperzip>11232</shipperzip>
<consigneename>TEST TEST TEST</consigneename>
<consigneeaddress>1835 Test St</consigneeaddress>
<consigneecity>San Diego</consigneecity>
<consigneestate>CA</consigneestate>
<consigneezip>92114</consigneezip>
<debtor>CARRIER LOGISTICS</debtor>
<ponumber></ponumber>
<servicetypecode>S</servicetypecode>
<servicetypedesc>NORMAL SERVICE</servicetypedesc>
<bolline>
<lineno>1</lineno>
<pieces>1</pieces>
<weight>60</weight>
<class>sml</class>
<description>[SMH9187W] 1.8 cu. ft. Over-the-</description>
<keyword></keyword>
</bolline>
<bolline>
<bolline>
<lineno>2</lineno>
<pieces>0</pieces>
<weight>0</weight>
<class></class>
<description>Range Microwave with 400 CFM</description>
<keyword></keyword>
</bolline>
<bolline>
<lineno>3</lineno>
<pieces>0</pieces>
<weight>0</weight>
<class></class>
<description>VentingSystem, 1100 Co</description>
<keyword></keyword>
</bolline>
<bollink>https://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1bolentry3.pdf?pronumb=0x0000000000000000</bollink>
<labellink>http://www.standardforwarding.com/scripts/cgiip.exe/WService=wsbroker1/shiplabelsm.pdf?pronumb=0x0000000000000000</labellink>
<quotetotal>115.00</quotetotal>
<quotenumber>1082603</quotenumber>
<quoteversion>tbolentry4-20110330</quoteversion>
<quotedatetime>11/10/2011 12:16:15.095-05:00</quotedatetime>
</bol>
</response>
The failure response will contain one or more error messages explaining why the shipment request could not be processed. For example:
<response>
<responsetype>BOL and Pickup Entry</responsetype>
<success>No</success>
<errors>
<errormessage>Invalid Username/Password</errormessage>
</errors>
</response>