EliShptoService
EliShptoService.asmx
This is a web service to add, change, delete or search an existing COP Ship-To record on file:
- AddShipTo
- ChangeShipTo
- DeleteShipTo
- SearchShipTo
The
original design background is to handle the requirement of the firearms industry’s
drop ship for a certain customer. All drop ship orders for the firearms industry
require valid ship-to setup in order to properly track FFL (Federal Firearms License) numbers.
An eCommerce site may wish to create a drop ship order by passing the firearms
dealer address and FFL information. If you wish to allow this drop ship, you
have to first determine if a valid ship-to already exists based on FFL number by
using SearchShipTo method. If it already exists, then we can proceed to create
the order based on the ship-to number found. If it does not exist, then we
should add the ship-to record by using AddShipTo method.
You
can certainly use this web services for more generic purposes.
A configuration switch controls whether only FFL the expiration date should be validated against the FFL Extension file. This is set through the ValidateFFLExtensionWhenInShipTo key. If the key value is “N”, then there’s no change to the behavior of ship to web services. If the key value is “Y”, then the web service will ignore the passing in Ship To FFL Expiration Date. The web service will look up the FFL Extension table for the FFL number provided, and if record is found, it use the expiration date in extension table to update the ship to. If record is not found, the web service will use zeroes date for ship to FFL expiration date.
This method adds a record to Ship-To file.
Generally speaking, you will leave the
ShipToNo blank when adding a ship-to. This will cause the system to sequentially assign ship-tos from 0001 to 9999, then from A000 – Z999. That is to say, this
web services can create up to a maximum of 45,999 ship-to records per customer. The system
determines the next ship-to number to assign by looking at the last ship-to
assigned for the customer and then adding one. If you should manually assign
ship-to numbers, or add ship-tos in Elliott that disrupt this sequence, then you
may potentially reduce the maximum number of ship-to numbers this web service can
create for you.
If you manually assign a ship-to number where the last 3 digits are not numbers or spaces, the result will be that this method will no longer be able to
auto assign new ship-to numbers. For example, if you manually add a
ship-to number “TEST,” then when you use this web service to add a ship-to for
the same customer, you will get error code 14, which means it cannot auto generate
a new ship-to number. You may resolve this problem by adding ship-to number
“U000” or delete ship-to number “TEST.”
Usage:
AddShipToResult = A.AddShipTo(UserName, UserPassword, AddShipToInput, ExtraInput)
Parameters UserID, Password and ExtraInput are not used at this moment.
AddShipToInput Structure
The data type of AddShipToInput is shipToRecord, which includes the following properties:
|
Property Name |
Length |
Type |
Upper |
Detail |
|
ShipToCustomerNo |
6 |
String |
Y |
Required. System will not pad leading zeroes to numeric customer number. Make sure to pad the leading zeroes for numeric customer (e.g., for customer number “100”, please pass it as “000100”). |
|
ShipToNo |
4 |
String |
Y |
If not provided, system will sequentially assign between 0001 – 9999, then A000 – Z999, based on the last ship-to number found for the customer. |
|
ShipToName |
30 |
String |
|
If not provided, default value is customer’s name. |
|
ShipToAddress1 |
30 |
String |
|
|
|
ShipToAddress2 |
30 |
String |
|
|
|
ShipToCity |
15 |
String |
|
|
|
ShipToState |
2 |
String |
Y |
|
|
ShipToZipCode |
10 |
String |
Y |
If “Allow Invalid Zip-code” is “N” or “W” in Elliot Global Setup, invalid zip code will return an error or warning code. |
|
ShipToCountry |
10 |
String |
|
|
|
ShipToExemptReasonCode |
1 |
String |
Y |
For Vertex only. |
|
ShipToOutsideCityLimit |
1 |
String |
Y |
For Vertex only, if not “Y” or “N”, default value is “N.” |
|
ShipToShipViaCode |
2 |
String |
Y |
Blank ship to ship-via code means same as customer ship via code. |
|
ShipToSalesmanNo |
3 |
String |
Y |
Blank salesman no. means same as customer salesman no. |
|
ShipToExemptExpireDate |
8 |
Date |
|
For Vertex only. Time portion is not used |
|
ShipToUpsZone |
2 |
String |
|
|
|
ShipToTaxCode1 |
3 |
String |
Y |
ShipToTaxCode1, 2 and 3 work as a group. If not provided, system will set these values to customer’s tax codes. If Elliott “auto assign tax code” is turned on in Global setup, then system will set default tax codes accordingly. Note: If using the Avalara Integration, you will have to pass the ship-to state + "1" for tax code 1, the ship-to state + "2" for tax code 2 and the ship-to-state + "3" for tax code 3. For example, if the ship-to state is Missouri, pass MO1 for tax code 1, MO2, for tax code 2, and MO3 for tax code 3.
|
|
ShipToTaxCode2 |
3 |
String |
Y |
See ShipToTaxCode1 |
|
ShipToTaxCode3 |
3 |
String |
Y |
See ShipToTaxCode1 |
|
ShipToFreeFormFlag |
1 |
String |
Y |
This value must be blank or “N”. “Y” is not supported at this moment. |
|
ShipToGeoCode |
9 |
String |
Y |
For Vertex only |
|
ShipToTaxableFlag |
1 |
String |
Y |
If not “Y” or “N,” default value is customer’s taxable flag. |
|
ShipToFFLNo |
15 |
String |
Y |
For Firearms industry only. Depending on Company Specific Control in Elliott Global Setup, this value can be used to validate against ARFFLFIL table. If not found, it can be either a warning or error. Support both 8 digits and 15 digits FFL No. |
|
ShipToFFLExpDate |
8 |
Date |
|
For Firearms industry only. Time portion is not used. |
|
ShipToXrefNo |
17 |
String |
|
This field is for EDI purposes. It is often used for cross-referencing. For example, it can be used for GLN (Global Locator Number). Please discuss with your EDI coordinator for more information. |
|
ShipToDeliveryLeadTime |
3 |
Double |
|
This field is mostly used for EDI purposes. |
|
ShipToOrderLocation |
2 |
String |
|
For those who have multiple warehouses across the country, this represents the default warehouse locations where we should ship from. It is usually the closest warehouse location to the ship-to address. If this field is not provided, system will try to determine the order location based on the ship to state and zip code. If no default can be found based on the ship to state and zip code, the order location will default to customer’s order location. |
* Upper = Y indicates the value of the property will be converted to upper case.
AddShipToResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK; for other return codes, please see “EliShptoService Return Code” section. |
|
ReturnMsg |
String |
This is description of return code. For example, if return code is zero, you can expect “OK” in this field. |
|
ExtraOutput |
String |
Not used for now. |
|
ShipToRecord() |
ShipToRecord |
This arrary contains the record added by this method. The structure of ShipToRecord is the same as the structure of AddShipToInput. Since this method only supports adding one ship-to, only the first element of this array is used. |
Code Example (VB)
The following sample codes assume ShipToFFLNo “12345678” does not exist in ship to for customer# “011845” (you can find out through SearchShipTo method). It will add a ship-to record and let the system automatically assign the next ship-to number.
Dim Service As New webServicesShpto.ElishptoService
Dim Input As New webServicesShpto.shipToRecord
Dim Result As New webServicesShpto.AddShipToResult
Input.ShipToCustomerNo = "011845"
Input.ShipToName = "NETcellent Walnut Store”
Input.ShipToAddress1 = “4030 Valley Blvd. #100”
Input.ShipToCity = “Walnut”
Input.ShipToState = “CA”
Input.ShipToZipCode = “91789”
Input.ShipToXrefNo = “12345678”
Input.ShipToFFLNo = “12345678”
Input.ShipToFFLExpDate = Date.Parse(“12/01/2016”)
Result = Service.AddShipTo("","",Input, "")
If Result.ReturnCode = 0 Then
lblResult.Text = “Ship To ” + Result.ShipToRecord(0).ShipToNo _
+ “ Added Successfully”
Else
lblResult.Text = Result.ReturnMsg
lblReturnCd.Text = Result.ReturnCode.ToString
End If
This method changes the value of an existing Ship-To record. If an input field is not assigned to any value, the original value of this field will keep unchanged. The exception is Address1 & 2 are working as a group. So are Tax Code 1, 2 and 3.
Usage:
ChangeShipToResult = A.ChangeShipTo(UserName, UserPassword, ChangeShipToInput, ExtraInput)
Parameters UserID, Password and ExtraInput are not used at this moment.
ChangeShipToInput Structure
The data type of ChangeShipToInput is shipToRecord.
|
Property Name |
Length |
Type |
Upper |
Detail |
|
ShipToCustomerNo |
6 |
String |
Y |
Required. This is the key field to locate ship-to record. |
|
ShipToNo |
4 |
String |
Y |
Required. This is the key field to locate ship-to record. |
|
ShipToName |
30 |
String |
|
|
|
ShipToAddress1 |
30 |
String |
|
Address 1 & 2 are working as group. |
|
ShipToAddress2 |
30 |
String |
|
See ShipToAddress1 |
|
ShipToCity |
15 |
String |
|
|
|
ShipToState |
2 |
String |
Y |
|
|
ShipToZipCode |
10 |
String |
Y |
If “Allow Invalid Zip-code” is “N” or “W” in Elliot Global Setup, invalid zip code will return an error or warning code. |
|
ShipToCountry |
10 |
String |
|
|
|
ShipToExemptReasonCode |
1 |
String |
Y |
For Vertex only |
|
ShipToOutsideCityLimit |
1 |
String |
Y |
For Vertex only |
|
ShipToShipViaCode |
2 |
String |
Y |
|
|
ShipToSalesmanNo |
3 |
String |
Y |
|
|
ShipToExemptExpireDate |
8 |
Date |
|
For Vertex only. Time portion is not used |
|
ShipToUpsZone |
2 |
String |
|
|
|
ShipToTaxCode1 |
3 |
String |
Y |
ShipToTaxCode1, 2 and 3 are working as a group. |
|
ShipToTaxCode2 |
3 |
String |
Y |
See ShipToTaxCode1 |
|
ShipToTaxCode3 |
3 |
String |
Y |
See ShipToTaxCode1 |
|
ShipToFreeFormFlag |
1 |
String |
Y |
“Y” is not supported. |
|
ShipToGeoCode |
9 |
String |
Y |
For Vertex only |
|
ShipToTaxableFlag |
1 |
String |
Y |
|
|
ShipToFFLNo |
15 |
String |
Y |
For Firearms industry only. Depending on Company Specific Control in Elliott Global Setup, this value can be used to validate against ARFFLFIL table. If not found, it can be either a warning or error. Support both 8 digits and 15 digits FFL No. |
|
ShipToFFLExpDate |
8 |
Date |
|
For Firearms industry only. Time portion is not used. |
|
ShipToXrefNo |
17 |
String |
|
See AddShipToInput for more details |
|
ShipToDeliveryLeadTime |
3 |
Double |
|
See AddShipToInput for more details |
|
ShipToOrderLocation |
2 |
String |
|
See AddShipToInput for more details |
* Upper = Y indicates the value of the property will be converted to upper case.
ChangeShipToResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK; for other return codes, please see “EliShptoService Return Code” section. |
|
ReturnMsg |
String |
This is description of return code. For example, if return code is zero, you can expect “OK” in this field. |
|
ExtraOutput |
String |
Not used for now. |
|
ShipToRecord() |
ShipToRecord |
Contains the record changed by this method. The structure of ShipToRecord is the same as the structure of AddShipToInput. Since this method only supports changing one ship-to, only the first element of this array is used. |
Code Example (VB)
The following sample codes will locate the ship-to record that customer = “011845” and ship-to number = “0001,” then change its ship-via to “FX.”
Dim Service As New webServicesShpto.ElishptoService
Dim Input As New webServicesShpto.shipToRecord
Dim Result As New webServicesShpto.ChangeShipToResult
Input.ShipToCustomerNo = "011845"
Input.ShipToNo = "0001"
Input.ShipToShipViaCode = "FX"
Result = Service.ChangeShipTo("","",Input, "")
If Result.ReturnCode = 0 Then
lblResult.Text = "Successful"
Else
lblResult.Text = Result.ReturnMsg
lblReturnCd.Text = Result.ReturnCode.ToString
End If
This method deletes a record from Ship-To file. If the ship-to is being referenced by existing sales order, then you should not delete this ship-to record. It is up to you to determine if this ship-to is currently being referenced by existing order. If you don’t know how to do this, then we suggest that you not allow your end users to delete ship-to numbers.
Usage:
DeleteShipToResult = A.DeleteShipTo(UserName, UserPassword, DeleteShipToInput, ExtraInput)
Parameters UserID, Password and ExtraInput are not used at this moment.
DeleteShipToInput Structure
|
Property Name |
Required |
Length |
Type |
Upper |
Detail |
|
ShipToCustomerNo |
Y |
6 |
String |
Y |
This the key field to locate the ship-to record. |
|
ShipToNo |
Y |
4 |
String |
Y |
This the key field to locate the ship-to record. |
* Upper = Y indicates the value of the property will be converted to upper case.
DeleteShipToResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK; for other return codes, please see “EliShptoService Return Code” section. |
|
ReturnMsg |
String |
This is description of return code. For example, if return code is zero, you can expect “OK” in this field. |
|
ExtraOutput |
String |
Not used for now. |
|
ShipToRecord() |
ShipToRecord |
Contains the record deleted by this method. The structure of ShipToRecord is the same as the structure of AddShipToInput. Since this method only supports deleteing one ship-to, only the first element of this array is used. |
Code Example (VB)
The following sample codes will delete the ship-to record that customer = “011845” and ship-to number = “0001.”
Dim Service As New webServicesShpto.ElishptoService
Dim Input As New webServicesShpto.DeleteShipToInput
Dim Result As New webServicesShpto.DeleteShipToResult
Input.ShipToCustomerNo = "011845"
Input.ShipToNo = "0001"
Result = Service.DeleteShipTo("","",Input, "")
If Result.ReturnCode = 0 Then
lblResult.Text = "Ship-To Deleted"
Else
lblResult.Text = Result.ReturnMsg
lblReturnCd.Text = Result.ReturnCode.ToString
End If
This method allows users to perform searching of a ship-to record for a particular customer. Customer No must be provided. If you use “start” search, a maximum of 50 records can be returned to the ShipToRecord() array. Depending on whether the ship-to record is found or not found, you may proceed with AddShipTo, ChangeShipTo or DeleteShipTo method. For example, you don’t want to add a ship-to record that already existed.
Usage:
SearchShipToResult = A.SearchShipTo(UserName,
UserPassword, SearchShipToInput, ExtraInput)
Parameters UserID, Password and ExtraInput are not used at this moment.
SearchShipToInput Structure
|
Property Name |
Length |
Type |
Upper |
Detail |
|
SearchCustomerNo |
6 |
String |
Y |
Required. |
|
SearchFieldName |
30 |
String |
Y |
The value of this field can be:
Searchable fields depend on additional search keys in Elliott Global Setup. If you pass a SearchFieldName that is not turned on in Elliott Global Setup, then you will receive an error. If you wish to search by FFL Number, we recommend that you update FFL Number to both the FFL Number and XREF field and make these two fields always identical. The reason for this is because XREF is a searchable user-definable index, but FFL Number is not. |
|
SearchValue |
30 |
String |
|
If value is not provided and the SearchType = “S” (Start Search), then it will return the top 50 records of the SearchFieldName. |
|
SearchType |
1 |
String |
Y |
“S”: Start search – meaning record’s search field value is greater than or equal to the Search Value. “M” (default): Exact Match search. |
* Upper = Y indicates the value of the property will be converted to upper case.
SearchShipToResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK; for other return codes, please see “EliShptoService Return Code” section. |
|
ReturnMsg |
String |
This is the description of the return code. For example, if return code is 0, then you can expect “OK” in this field. |
|
ExtraOutput |
String |
Not used for now. |
|
NoOfSearchResult |
Integer |
This is the number of records returned in the SearchResult. If the value is zero, it means no search result found. If the value is 50, it does not mean only 50 records match the result since the maximum SearchResult size is 50. |
|
ShipToRecord () |
ShipToRecord |
Contains up to 50 Ship-To records. The structure of ShipToRecord is the same as the structure of AddShipToInput. |
Code Example (VB)
The following sample codes will return all ship-to records matching ship-to customer “011845” and ship-to Xref Number = “12345678.” Normally, finding more than one matching record is not an error condition. But in this case, the example is to use the Xref Number as FFL so we expect there should be no duplicate ship-to FFL number exists. So if we found two or more records, it indicates there was some type of procedure error when adding the ship-to records in the past.
Dim Service As New webServicesShpto.ElishptoService
Dim Input As New webServicesShpto.SearchShipToInput
Dim Result As New webServicesShpto.SearchShipToResult
Input.SearchCustomerNo = "011845"
Input.SearchFieldName = "XREF"
Input.SearchValue = "12345678"
Input.SearchType = "M"
Result = Service.SearchShipTo("","",Input, "")
If Result.ReturnCode = 0 Then
If Result.NoOfSearchResult > 0 Then
lblResult.Text = Result.NoOfSearchResult.ToString _
& " Records Found"
Else
lblResult.Text = “No Record Found”
End If
Else
lblResult.Text = Result.ReturnMsg
lblReturnCd.Text = Result.ReturnCode.ToString
End If
EliShptoService Return Code
Be aware that some none zero codes below are not necessarily errors. They may just be warnings based on your Global Setup:
0 = OK
1 = File Error
2 = Customer Not Found
3 = Ship-To Already On File
4 = Ship-To Not Found
5 = Ship-To Record Locked
6 = Tax Code Not Found
7 = Order Location Not Found
8 = Invalid SearchFieldName
9 = Invalid SearchType. Must be: Blank, "M" Or "S"
10 = Ship Via Code Not Found
11 = Salesman No. Not Found
12 = Search Key Is Not Turned on in Elliott Global Setup
13 = ShipToNo Missing & Must Be Provided
14 = Cannot Auto Generate Ship-To No, Please Assign Manually
15 = Ship-To FFL No Not Found (This can be either an error or warning)
16 = Ship-To FFL No Can Only Be 8 Or 15 Digits (This can be either an error or warning)
17 = Invalid ShipToZipCode (This can be either an error or warning)
18 = Zip Code & Address Do Not Match FFL File (This can be either an error or warning)
19 = Customer No. Missing & Must Be Provided
CLS