WS Reference Guide 2-0-13

Web Services Reference Guide

V2.0.13

Last Updated: January 8, 2013 Revision: 2.0.13

Copyright 2005-2011 Six88 Solutions. All rights reserved.


January 8, 2013 SIX88 SOLUTIONS PROPRIETARY AND CONFIDENTIAL Page 2 of 160

Table of Contents Table of Contents ........................................................................................................................... 2 1 Revision History.......................................................................................................................... 13 2 Introduction ................................................................................................................................. 18 2.1 Overview .............................................................................................................................. 18 2.2 Getting Started ................................................................................................................... 18 2.3 Current Version ................................................................................................................. 19 2.4 Versioning and Services ................................................................................................. 19 2.5 Web Service API User Portal ........................................................................................ 20 2.6 ShipCompliant Partner Keys ........................................................................................ 21 2.7 Partner Portal ..................................................................................................................... 22 2.7.1 Introduction .............................................................................................................. 22 2.7.2 Instructions................................................................................................................ 23 2.7.3 Tools Real-Time Shipment Status Report .................................................. 23 2.7.4 Tools Shipment Summary Report ................................................................. 24 2.7.5 Tools Partner API Activity Summary ........................................................... 25 2.7.6 API Activity Log ........................................................................................................ 26 2.8 Single Sign On ..................................................................................................................... 26 2.8.1 Introduction .............................................................................................................. 26 2.8.2 User Configuration .................................................................................................. 26 2.8.3 Implementation ....................................................................................................... 27 3 Order Lifecycle ............................................................................................................................ 29 3.1 Shipment Status Types ................................................................................................... 29 InProcess ....................................................................................................................................... 29 PaymentAccepted ....................................................................................................................... 29 SentToFulfillment ....................................................................................................................... 29 Shipped ........................................................................................................................................... 29 Delivered........................................................................................................................................ 29 Voided ............................................................................................................................................. 30 3.2 Compliance Status Types ............................................................................................... 30 Compliant ...................................................................................................................................... 30 NotCompliant ............................................................................................................................... 30 CompliantCommitted ................................................................................................................ 30 LegacyCommitted ....................................................................................................................... 30 4 Rules ................................................................................................................................................ 30 4.1 Age Verification Required ............................................................................................. 31 4.2 Aggregate Volume Limit ................................................................................................. 31 4.3 Brand Registration Required ....................................................................................... 31 4.4 Bypass Compliance Checks ........................................................................................... 31 4.5 Can not also be a Wholesaler........................................................................................ 31 4.6 Carrier Prohibited ............................................................................................................ 31 4.7 Carrier Service Prohibited ............................................................................................. 31 4.8 Consumer License Required ......................................................................................... 31 4.9 Control State ....................................................................................................................... 31



4.10 Customer Aggregate Volume Limit ............................................................................ 31 4.11 Date of Birth Required .................................................................................................... 31 4.12 Direct Shipping License Required .............................................................................. 32 4.13 Direct Shipping Prohibited ............................................................................................ 32 4.14 Distributor Appointment Notice Required (Wholesale) ................................... 32 4.15 Distribution Change Notice Required (Wholesale) ............................................. 32 4.16 Distribution Territory Change Notice Required (Wholesale) ......................... 32 4.17 Distribution Territory Designation Required (Wholesale) .............................. 32 4.18 Distributor Prohibited .................................................................................................... 32 4.19 Distributor Required ....................................................................................................... 32 4.20 Franchise State ................................................................................................................... 32 4.21 Label Registration Required ......................................................................................... 32 4.22 Multiple Distributors Per Brand (Wholesale) ....................................................... 32 4.23 Multiple Distributors Per Territory Prohibited (Wholesale) .......................... 33 4.24 Per Bottle Volume Limit ................................................................................................. 33 4.25 Per Shipment Volume Limit .......................................................................................... 33 4.26 Previous Visit Required .................................................................................................. 33 4.27 Price Posting On New Products Required (Wholesale) ..................................... 33 4.28 Price Posting On Periodically Required (Wholesale) ......................................... 33 4.29 Price Posting On Price Decrease Required (Wholesale) ................................... 33 4.30 Price Posting On Price Increase Required (Wholesale) ..................................... 33 4.31 Price Posting Required (Wholesale) ......................................................................... 33 4.32 Producer Consent Required.......................................................................................... 33 4.33 Product Registration Renewal Required (Wholesale) ....................................... 33 4.34 Product Registration Required (Wholesale) .......................................................... 33 4.35 Product Registration Revision Required for ABV Changes (Wholesale) .... 34 4.36 Product Registration Revision Required for Additional Size (Wholesale) . 34 4.37 Product Registration Revision Required for New Case Size (Wholesale) .. 34 4.38 Product Registration Revision Required for New Vintage (Wholesale) ..... 34 4.39 Product Type Not Supported ....................................................................................... 34 4.40 Sales Person Registration Required (Wholesale) ................................................ 34 4.41 Samples Prohibited .......................................................................................................... 34 4.42 Solicitation Limit ............................................................................................................... 34 4.43 Special Shipping Label Required ................................................................................ 34 4.44 Tax Required ...................................................................................................................... 34 4.45 Valid COLA Required (Wholesale) ............................................................................. 34 4.46 Valid Product Types Required ..................................................................................... 35 4.47 Valid Region Required .................................................................................................... 35 4.48 Wholesale License Required (Wholesale) ............................................................... 35 4.49 Wines Not of Our Own Production Prohibited ...................................................... 35 4.50 Null ......................................................................................................................................... 35 5 Method Summary ....................................................................................................................... 35 5.1 SalesOrderService Methods .......................................................................................... 35 5.1.1 AddExternalClubKey .............................................................................................. 35 5.1.2 AddExternalOfferKey ............................................................................................. 36 5.1.3 AddOrRemoveTag ................................................................................................... 36



5.1.4 PersistSalesOrder .................................................................................................... 36 5.1.5 CheckComplianceOfSalesOrder ......................................................................... 36 5.1.6 CommitSalesOrder .................................................................................................. 36 5.1.7 CheckComplianceOfAndCommitSalesOrder ................................................. 37 5.1.8 AddTrackingNumber ............................................................................................. 37 5.1.9 AddPackageCost ...................................................................................................... 37 5.1.10 GetSalesOrder ........................................................................................................... 38 5.1.11 GetSalesOrderStatus .............................................................................................. 38 5.1.12 VoidSalesOrder......................................................................................................... 38 5.1.13 UpdateShipmentStatus ......................................................................................... 38 5.1.14 CommitSalesOrderUpdateKey ........................................................................... 38 5.1.15 SearchSalesOrders .................................................................................................. 39 5.1.16 SearchMoreSalesOrders ....................................................................................... 39 5.1.17 SetExternalClubKeys .............................................................................................. 39 5.1.18 SetExternalCustomerKey ..................................................................................... 39 5.1.19 SetExternalOfferKeys ............................................................................................. 39 5.1.20 SetExternalSalesOrderKey ................................................................................... 40 5.1.21 SetFulfillmentException ....................................................................................... 40 5.1.22 ClearFulfillmentException ................................................................................... 40 5.1.23 GetPossibleFulfillmentHouses ........................................................................... 40 5.1.24 GetPossibeRuleTypes ............................................................................................ 40 5.1.25 GetPossibleShippingService ................................................................................ 41 5.2 Brand Service Methods ................................................................................................... 41 5.2.1 AddUpdateBrand ..................................................................................................... 41 5.2.2 AddUpdateBrandInGroup .................................................................................... 41 5.3 ProductService Methods ................................................................................................ 41 5.3.1 AddUpdateProduct ................................................................................................. 41 5.3.2 GetProduct ................................................................................................................. 42 5.3.3 DeleteProduct ........................................................................................................... 42 5.3.4 GetInventoryDetails ............................................................................................... 42 5.3.5 AdjustInventory ....................................................................................................... 42 5.3.6 SetInventory .............................................................................................................. 42 5.3.7 ChangeProductKey ................................................................................................. 42 5.3.8 UpdateProductWholesalePrices ........................................................................ 43 5.3.9 GetProductWholesalePrices ................................................................................ 43 5.3.10 SearchProducts ........................................................................................................ 43 5.3.11 SearchMoreProducts .............................................................................................. 43 5.3.12 AddUpdateProductInGroup ................................................................................ 43 5.3.13 AllocateToMarkeplace ........................................................................................... 44 5.3.14 ClearAllPrices ............................................................................................................ 44 5.3.15 ClearFuturePrices ................................................................................................... 44 5.4 AddressService Methods ................................................................................................ 44 5.4.1 ValidateAddress ....................................................................................................... 44 5.4.2 CheckTemperatureForecast ................................................................................ 44 5.5 AgeService Methods ......................................................................................................... 44 5.5.1 CheckAgeOfPerson .................................................................................................. 44



5.5.2 VerifyAgeOfPerson ................................................................................................. 45 5.6 TaxService Methods ......................................................................................................... 45 5.6.1 GetTaxRate ................................................................................................................. 45 5.6.2 GetSalesTaxRatesByAddress .............................................................................. 45 5.6.3 CalculateSalesTaxDueForOrder ......................................................................... 45 5.7 SupplierService Methods ............................................................................................... 46 5.7.1 GetShippingPreferences ....................................................................................... 46 5.7.2 IsShippingAvailable ................................................................................................ 46 5.7.3 IsProductCompliant ............................................................................................... 46 5.8 WholesaleService Methods ........................................................................................... 46 5.8.1 AddBrandDistribution ........................................................................................... 46 5.8.2 AddDistributionTerritories ................................................................................. 47 5.8.3 AddUpdateDistributor ........................................................................................... 47 5.8.4 GetAvailableTerritories ........................................................................................ 47 5.8.5 GetDistributor ........................................................................................................... 47 5.8.6 RemoveBrandDistribution .................................................................................. 47 5.8.7 RemoveDistributionTerritories ......................................................................... 47 5.8.8 CheckComplianceOfInvoice ................................................................................. 48 5.8.9 CheckComplianceOfSalesOrder ......................................................................... 48 5.8.10 CommitSalesOrder .................................................................................................. 48 5.8.11 GetAllAvailableProductsInState ........................................................................ 48 5.8.12 GetProductAvailabilityByState .......................................................................... 48 5.8.13 GetProductAvailabilityInAllStates .................................................................... 49 5.8.14 PersistInvoice ........................................................................................................... 49 5.8.15 VoidInvoice ................................................................................................................ 49 5.9 FulfillmentService Methods .......................................................................................... 49 5.9.1 AddTrackingNumber ............................................................................................. 49 5.9.2 AddPackageCost ...................................................................................................... 50 5.9.3 GetClubShipmentsByBatch .................................................................................. 50 5.9.4 GetClubShipmentsReadyForInHouseFulfillment........................................ 50 5.9.5 GetDailyShipmentsByOrderNumber ............................................................... 50 5.9.6 GetDailyShipmentsReadyForInHouseFulfillment ...................................... 50 5.9.7 GetMoreShipments ................................................................................................. 51 5.9.8 GetShipmentsByBatch ........................................................................................... 51 5.9.9 GetShipmentsByFulfillmentKey ........................................................................ 51 5.9.10 RemoveTrackingNumber ..................................................................................... 51 5.9.11 SetFulfillmentExceptionByFulfillmentOrderKey ........................................ 51 5.9.12 ClearFulfillmentExceptionByFulfillmentOrderKey .................................... 52 5.9.13 GetDailyShipmentsReadyForWarehouseFulfillment ................................ 52 5.9.14 GetClubShipmentsReadyForWarehouseFulfillment ................................. 52 5.10 SSOService Methods ........................................................................................................ 52 5.10.1 GetSSOUrl ................................................................................................................... 52 5.11 All Service Methods .......................................................................................................... 52 5.11.1 GetVersion .................................................................................................................. 52 6 Method Details ............................................................................................................................. 53 6.1 AddExternalClubKeys ..................................................................................................... 53



6.1.1 Request............................................................................................................................. 53 6.2 AddExternalOfferKeys .................................................................................................... 53 6.2.1 Request ........................................................................................................................ 53 6.3 AddOrRemoveTag ............................................................................................................ 53 6.3.1 Request ........................................................................................................................ 54 6.4 PersistSalesOrder ............................................................................................................. 54 6.4.1 Request ........................................................................................................................ 54 6.5 CheckComplianceOfSalesOrder ................................................................................... 56 6.5.1 Request............................................................................................................................. 56 6.6 CheckComplianceOfAndCommitSalesOrder .......................................................... 58 6.6.1 Request ........................................................................................................................ 58 6.7 CommitSalesOrder ........................................................................................................... 60 6.7.1 Request............................................................................................................................. 60 6.8 CommitSalesOrderUpdateKey ..................................................................................... 60 6.8.1 Request ........................................................................................................................ 61 6.9 AddTrackingNumber ....................................................................................................... 61 6.10 GetSalesOrder ..................................................................................................................... 61 6.10.1 Request ........................................................................................................................ 61 6.11 GetSalesOrderStatus ........................................................................................................ 62 6.11.1 Request ........................................................................................................................ 62 6.12 VoidSalesOrder .................................................................................................................. 62 6.12.1 Request ........................................................................................................................ 62 6.13 UpdateShipmentStatus ................................................................................................... 62 6.13.1 Request ........................................................................................................................ 62 6.14 AddUpdateProduct ........................................................................................................... 62 6.14.1 Request ........................................................................................................................ 63 6.15 AddUpdateProductInGroup .......................................................................................... 63 6.15.1 Request ........................................................................................................................ 64 6.16 DeleteProduct ..................................................................................................................... 64 6.16.1 Request ........................................................................................................................ 64 6.17 GetProduct ........................................................................................................................... 65 6.17.1 Request ........................................................................................................................ 65 6.18 GetInventoryDetails ......................................................................................................... 65 6.18.1 Request ........................................................................................................................ 65 6.19 AdjustInventory................................................................................................................. 65 6.19.1 Request ........................................................................................................................ 65 6.20 SetInventory ....................................................................................................................... 66 6.20.1 Request ........................................................................................................................ 66 6.21 ChangeProductKey ........................................................................................................... 66 6.21.1 Request ........................................................................................................................ 66 6.22 ClearAllPrices ..................................................................................................................... 66 6.22.1 Request ........................................................................................................................ 67 6.23 ClearFuturePrices ............................................................................................................. 67 6.23.1 Request ........................................................................................................................ 67 6.24 UpdateProductWholesalePrices ................................................................................. 67 6.24.1 Request ........................................................................................................................ 67



6.25 GetProductWholesalePrices ......................................................................................... 68 6.25.1 Request ........................................................................................................................ 68 6.26 SearchProducts .................................................................................................................. 68 6.26.1 Request ........................................................................................................................ 68 6.27 AddUpdateBrand .............................................................................................................. 69 6.27.1 Request ........................................................................................................................ 69 6.28 AddUpdateBrandInGroup ............................................................................................. 69 6.28.1 Request ........................................................................................................................ 69 6.29 SetFulfillmentException ................................................................................................. 70 6.29.1 Request ........................................................................................................................ 70 6.30 ClearFulfillmentException ............................................................................................. 70 6.30.1 Request ........................................................................................................................ 70 6.31 GetPossibleFulfillmentHouses ..................................................................................... 70 6.31.1 Request ........................................................................................................................ 71 6.32 GetPossibleRuleTypes ..................................................................................................... 71 6.32.1 Request ........................................................................................................................ 71 6.33 GetPossibleShippingService ......................................................................................... 71 6.33.1 Request ........................................................................................................................ 71 6.34 ValidateAddress ................................................................................................................ 71 6.34.1 Request ........................................................................................................................ 73 6.35 CheckTemperatureForecast ......................................................................................... 73 6.35.1 Request ........................................................................................................................ 73 6.36 CheckAgeOfPerson ........................................................................................................... 73 6.36.1 Request ........................................................................................................................ 74 6.37 VerifyAgeOfPerson ........................................................................................................... 74 6.37.1 Request ........................................................................................................................ 75 6.38 GetTaxRate .......................................................................................................................... 75 6.38.1 Request ........................................................................................................................ 76 6.39 GetSalesTaxRatesByAddress ........................................................................................ 76 6.39.1 Request ........................................................................................................................ 76 6.40 CalculateSalesTaxDueForOrder .................................................................................. 77 6.40.1 Request ........................................................................................................................ 77 6.41 IsShippingAvailable ......................................................................................................... 77 6.41.1 Request ........................................................................................................................ 77 6.42 GetShippingPreferences ................................................................................................. 78 6.42.1 Request ........................................................................................................................ 78 6.43 IsProductCompliant ......................................................................................................... 78 6.43.1 Request ........................................................................................................................ 78 6.44 SearchSalesOrders ............................................................................................................ 78 6.44.1 Request ........................................................................................................................ 79 6.45 SearchMoreSalesOrders ................................................................................................. 80 6.45.1 Request ........................................................................................................................ 80 6.46 SetExternalClubKeys ....................................................................................................... 80 6.46.1 Request ........................................................................................................................ 80 6.47 SetExternalCustomerKey ............................................................................................... 81 6.47.1 Request ........................................................................................................................ 81



6.48 SetExternalOfferKeys ...................................................................................................... 81 6.48.1 Request ........................................................................................................................ 81 6.49 SetExternalSalesOrderKey ............................................................................................ 81 6.49.1 Request ........................................................................................................................ 81 6.50 AddBrandDistribution .................................................................................................... 81 6.50.1 Request ........................................................................................................................ 82 6.51 AddDistributionTerritories........................................................................................... 82 6.51.1 Request ........................................................................................................................ 82 6.52 AddUpdateDistributor .................................................................................................... 82 6.52.1 Request ........................................................................................................................ 82 6.53 GetDistributor .................................................................................................................... 83 6.53.1 Request ........................................................................................................................ 83 6.54 RemoveBrandDistribution ............................................................................................ 83 6.54.1 Request ........................................................................................................................ 83 6.55 RemoveDistributionTerritories .................................................................................. 84 6.55.1 Request ........................................................................................................................ 84 6.56 CheckComplianceOfInvoice .......................................................................................... 84 6.56.1 Request ........................................................................................................................ 84 6.57 CheckComplianceOfSalesOrder ................................................................................... 85 6.57.1 Request ........................................................................................................................ 85 6.58 CommitSalesOrder ........................................................................................................... 85 6.58.1 Request ........................................................................................................................ 86 6.59 GetAllAvailableProductsInState .................................................................................. 86 6.59.1 Request ........................................................................................................................ 86 6.60 GetProductAvailabilityByState .................................................................................... 86 6.60.1 Request ........................................................................................................................ 87 6.61 GetProductAvailabilityInAllStates.............................................................................. 87 6.61.1 Request ........................................................................................................................ 87 6.62 PersistInvoice ..................................................................................................................... 87 6.62.1 Request ........................................................................................................................ 87 6.63 VoidInvoice.......................................................................................................................... 88 6.63.1 Request ........................................................................................................................ 88 6.64 AddTrackingNumber ....................................................................................................... 88 6.64.1 Request ........................................................................................................................ 88 6.65 AddPackageCost ................................................................................................................ 89 6.65.1 Request ........................................................................................................................ 89 6.66 GetClubShipmentsByBatch ........................................................................................... 89 6.66.1 Request ........................................................................................................................ 89 6.67 GetClubShipmentsReadyForInHouseFulfillment ................................................. 89 6.67.1 Request ........................................................................................................................ 89 6.68 GetDailyShipmentsByOrderNumber ......................................................................... 90 6.68.1 Request ........................................................................................................................ 90 6.69 GetDailyShipmentsReadyForInHouseFulfillment ................................................ 90 6.69.1 Request ........................................................................................................................ 90 6.70 GetMoreShipments ........................................................................................................... 90 6.70.1 Request ........................................................................................................................ 90



6.71 GetShipmentsByBatch .................................................................................................... 91 6.71.1 Request ........................................................................................................................ 91 6.72 GetShipmentsByFulfillmentKey .................................................................................. 91 6.72.1 Request ........................................................................................................................ 91 6.73 RemoveTrackingNumber .............................................................................................. 91 6.73.1 Request ........................................................................................................................ 91 6.74 SetFulfillmentExceptionByFulfillmentOrderKey ................................................. 91 6.74.1 Request ........................................................................................................................ 92 6.75 ClearFulfillmentExceptionByFulfillmentOrderKey ............................................. 92 6.75.1 Request ........................................................................................................................ 92 6.76 GetClubShipmentsReadyForWarehouseFulfillment ........................................... 92 6.76.1 Request ........................................................................................................................ 92 6.77 GetDailyShipmentsReadyForWarehouseFulfillment .......................................... 92 6.77.1 Request ........................................................................................................................ 93 6.78 GetSSOUrl ............................................................................................................................. 93 6.78.1 Request ........................................................................................................................ 93 6.79 GetVersion ........................................................................................................................... 93 6.79.1 Request ........................................................................................................................ 93 6.80 Input Tags ............................................................................................................................ 94 6.80.1 ................................................................ 94 6.80.2 .......................................................................................... 94 6.80.3 ............................................................................................................... 94 6.80.4 ........................................................................................................... 94 6.80.5 ........................................................................................................................... 94 6.80.6 .................................................................................... 95 6.80.7 .............................................................................................................. 95 6.80.8 ..................................................................................................... 95 6.80.9 ................................................................................................................ 95 6.80.10 .......................................................................................... 95 6.80.11 .............................................................................................................. 96 6.80.12 ................................................................................................................ 96 6.80.13 ...................................................................................................... 96 6.80.14 ...................................................................................................... 96 6.80.15 ........................................................................................ 98 6.80.16 ....................................................................................................... 98 6.80.17 ....................................................................................... 98 6.80.18 ................................................................................................... 98 6.80.19 ................................................................................................................... 99 6.80.20 ............................................................................... 99 6.80.21 ....................................................................................................................... 99 6.80.22 ......................................................................................................... 99 6.80.23 .................................................................................................... 99 6.80.24 ............................................................................................................... 99 6.80.25 ..................................................................................... 100 6.80.26 ....................................................................... 100 6.80.27 ......................................................................................... 100



6.80.28 .................................................................................. 101 6.80.29 ......................................................................................... 101 6.80.30 ............................................................................................ 102 6.80.31 ........................................................................................................... 102 6.80.32 .................................................................................. 102 6.80.33 .......................................................................... 102 6.80.34 ............................................................................................ 103 6.80.35 .............................................................................................. 103 6.80.36 ................................................................................................ 103 6.80.37 ........................................................................................................ 103 6.80.38 ................................................................................... 104 6.80.39 ................................................................................................. 104 6.80.40 ................................................................................................. 104 6.80.41 ................................................................................................. 105 6.80.42 ......................................................................................... 105 6.80.43 ....................................................................................... 105 6.80.44 ............................................................................................... 105 6.80.45 ............................................................................................. 105 6.80.46 ...................................................................................................... 106 6.80.47 ................................................................................................. 106 6.80.48 ........................................................................................................ 106 6.80.49 ......................................................................................... 106 6.80.50 ........................................................................................ 106 6.80.51 ...................................................................................... 107 6.80.52 ................................................................................................ 107 6.80.53 ............................................................................................................... 107 6.80.54 .................................................................................................... 107 6.80.55 .......................................................................................... 107 6.80.56 .................................................................................................. 108 6.80.57 ......................................................................................... 108 6.80.58 ................................................................................................ 108 6.80.59 ........................................................................................................... 109 6.80.60 ................................................................................... 109 6.80.61 ................................................................................................ 109 6.80.62 ............................................................................................................. 109 6.80.63 ....................................................................................... 109 6.80.64 ........................................................................ 110 6.80.65 ....................................................................................................... 110 6.80.66 ....................................................................... 110 6.80.67 ......................................................................................................... 110 6.80.68 ..................................................................................... 111 6.80.69 .............................................................................................. 112 6.80.70 ...................................................................................... 112 6.80.71 ...................................................................................... 112 6.80.72 ............................................................................................ 112 6.80.73 ........................................................................................................ 113



6.80.74 ........................................................................................................... 113 6.80.75 .......................................................................................................... 113 6.80.76 .................................................................................................. 113 6.80.77 ................................................................................................. 113 6.80.78 ................................................................................................. 114 6.80.79 ...................................................................................... 114 6.80.80 ............................................................................................ 114 6.80.81 ............................................................................... 114 6.80.82 ........................................................................................... 114 6.80.83 ..................................................................................... 116 6.80.84 .................................................................................................................. 116 6.80.85 ............................................................................................................. 117 6.80.86 ............................................................................................................. 117 6.80.87 ..................................................................................................................... 117 6.80.88 ................................................................................................ 117 6.80.89 ......................................................................................... 117 6.80.90 .......................................................................................... 118 6.80.91 ......................................................................................................... 118 6.80.92 .................................................................................................. 118 6.80.93 ........................................................................................................ 118 6.80.94 ............................................................................................................ 118 6.80.95 ........................................................................................... 119 6.80.96 ..................................................................................... 119 6.80.97 ....................................................................................................... 119 6.80.98 ............................................................................................................. 119 6.80.99 ............................................................................................ 119 6.80.100 .................................................................................................... 120 6.80.101 ..................................................................................... 120 6.80.102 ................................................................................................................... 120 6.80.103 ................................................................................................................... 120 7 Submitting a Request .............................................................................................................. 121 7.1 Security ............................................................................................................................... 121 7.2 Single Supplier ................................................................................................................. 122 7.3 Super Supplier .................................................................................................................. 122 8 Interpreting Responses .......................................................................................................... 122 8.1 Error Types ....................................................................................................................... 122 8.2 Handling Errors ............................................................................................................... 123 9 Using ShipCompliant as a Gateway to Fulfillment ....................................................... 126 9.1 Conditions for Fulfillment ........................................................................................... 126 9.2 Automatic vs. Batch Mode ........................................................................................... 126 9.2.1 Batch ........................................................................................................................... 126 9.2.2 Automatic ................................................................................................................. 126 9.3 Fulfillment Status Types .............................................................................................. 126 9.4 Overwriting SalesOrders .............................................................................................. 127 9.5 Custom Service Types ................................................................................................... 127 9.6 Sample Workflow ........................................................................................................... 127



9.7 Using ShipCompliant as a Gateway to Fulfillment for Level 1 Customers 128 9.8 Getting Shipment Status and Tracking Numbers ............................................... 128 10 Integration .................................................................................................................................. 130 10.1 Handling Enumerations ............................................................................................... 130 11 Timing and Performance ....................................................................................................... 130 12 Address Validation ................................................................................................................... 130 13 Age Verification ......................................................................................................................... 134 13.1 Age Verification Response Types ............................................................................. 134 13.2 Age Checks Not Enabled ............................................................................................... 134 13.3 Age Cannot be Confirmed ............................................................................................ 135 13.4 Is Not of Age ...................................................................................................................... 135 13.5 Is Of Age .............................................................................................................................. 135 14 Sample Workflows ................................................................................................................... 136 14.1 E-Commerce Order Real-Time Check .................................................................. 136 14.2 E-Commerce Order Pre-Fulfillment Check ........................................................ 138 15 Appendix A: Sample XML Requests and Responses ................................................... 139 15.1 CalculateSalesTaxDueForOrderRequest ................................................................ 139 15.2 CalculateSalesTaxDueForOrderResponse ............................................................. 139 15.3 GetTaxRateResponse ..................................................................................................... 140 15.4 GetTaxRateByAddressRequest .................................................................................. 141 15.5 GetTaxRateByAddressResponse ............................................................................... 141 15.6 CheckComplianceOfSalesOrderResponse (Sample 1) ...................................... 142 15.7 CheckComplianceOfSalesOrderResponse (Sample 2 Bypassed compliance checks)............................................................................................................................................... 143 15.8 CheckTemperatureForecastResponse .................................................................... 144 15.9 CheckComplianceOfSalesOrder (Sample v1.2 SalesTax Response) ............ 145 15.10 GetInventoryDetails Response ............................................................................. 146 16 Appendix B: Development Tips & Tricks ........................................................................ 147 16.1 Use a Packet Sniffer to monitor SOAP requests and responses. ................... 147 16.2 SoapUI ................................................................................................................................. 147 17 Appendix C: List of Values for Standard Fields ............................................................. 149 18 Appendix D: Version 1.2 Highlights .................................................................................. 151 19 Appendix E: WSDL Documentation ................................................................................... 158 20 Appendix F: Technical Notes about DateTime .............................................................. 159 21 Glossary ........................................................................................................................................ 159 22 Copyright ................................................................................................................................ 160 23 Trademarks ............................................................................................................................ 160



1 Revision History Date Revision Description Author 1/20/2006 1.0.0 First release Jeff Carroll

2/19/2006 1.0.1 Added address validation description Jeff Carroll

1/10/2007 1.0.2 Update section 3.1, Shipment Status Types (added PaymentAccepted).

Added four new rule types (Can Not also be a Wholesaler, Per Bottle Volume Limit, Producer Consent Required, Samples Prohibited).

Added AddTrackingNumber method.

Jeff Carroll

3/30/2007 1.0.3 Updated sample workflows. Jeff Carroll

5/21/2007 1.0.4 Added IgnoreStreetLevelErrors detail

Added FulfillmentType detail Added FulfillmentHouse detail Added Account Credentialing

section Added GetTaxRate Method Added CheckAgeOfPerson

Method Added ValidateAddress Method

Jeff Carroll

11/28/2007 1.0.5 Added CommitSalesOrderUpdateKey method

Jeff Carroll

2/18/2008 1.0.6 Added new response details to ValidateAddress method

Jeff Carroll

3/13/08 1.0.7 Added tag details to Sales Order methods

Updated dev. server URLs

Pawel Smolarkiewicz

4/14/08 1.0.8 Added Default license relationship to Sales Order requests

Added license relationship value to compliance response

Updated available fulfillment house options

Pawel Smolarkiewicz

6/5/2008 1.0.9 Added IsShippingAvailable method

Added SearchSalesOrders method Added SearchMoreSalesOrders

method Added section for Using

ShipCompliant as a Gateway to Fulfillment

Jeff Carroll



6/27/2008 1.0.10 Added section for Using Tax Service

Clarified Fulfillment Statuses

Pawel Smolarkiewicz

8/05/2008 1.0.11 Added FulfillmentAcount support Updated request parameters for

SearchSalesOrders method Added section for Using

ShipCompliant as a Gateway to Fulfillment for Level 1 Customers

Updated list of Fulfillment Houses

Added FulfillmentExceptionType Added Null RuleType Updated list of supported

ShippingService types Updated Account Credentialing

section with authentication options

Added description of node

Updated sample responses

Jeff Carroll, Pawel Smolarkiewicz

9/11/2008 1.0.12 Added BrandService description Removed ComplianceCheckMode Updated description of

AddUpdateProduct method Added appendix 18

development tips and tricks

Pawel Smolarkiewicz

10/28/2008 1.0.13 Add Label Registration Required Rule Type

Add GetInventoryDetails Method Added SetFulfillmentException

method Added WithZipPlus4TaxRates

field Added BrandService description


1/2/2009 1.0.14 Added Getting Started section Added Appendix C: List of Values

for Standard Fields Appendix E: WSDL

Documentation Added Custom Service Types Updated SearchSalesOrder

request parameters to include a SalesOrderKeys list

Updated section 12, Address Validation

Updated Error codes Clarifications in Security section


3/16/2009 1.0.15 Added VerifyAgeOfPerson method

Defined support for international addresses

Updated list of valid product types

Updated description of




GetTaxRate by destination address.

Added description for staging and demo servers

Added tips for using enumerations

8/19/2009 1.0.16 Added GetShippingPreferences method

Updated staging reference URLs to reflect stable maintenance environment

Refined definition of support for international addresses.

Added improved definition of handling different response types

Ryan Cook

1/20/2011 1.1.0 Added AddTrackingNumber method in SalesOrderService

Added details for web service portal login

Added details for PartnerKey Added description for Partner

Portal Added description for Single Sign

On Updated fields that were changed

from Enumerations to Strings Added new fields available under

CheckComplianceOfAndCommitSalesOrder method

Added new fields available under CheckComplianceOfSalesOrder method

Added new fields available under PersistSalesOrder method

Added new fields available under AddUpdateProduct method

Added details for Wholesale Services

Added details for GetSalesTaxRatesByAddress method

Added the AdjustInventory method

Added the SetInventory method Added

CheckTemperatureForecast method

Added WholesaleService methods Added FulfillmentService

methods Removed the WSDL Description

section and replaced it with links to online documentation

Updated FulfillmentHouse values Updated ShippingService values Added RuleType values

Mark Hayes



4/1/2011 1.16 x Updated Fulfillment House Values

x Added Get Possible methods x Added additional Age Service

information/samples

Sam Sexson

5/24/2011 2.0 x Added UpdateProductWholesalePrices method

x Added GetProductWholesalePrices x Added "List of Values for Standard

Fields x Added New Shipping Services x Added Sample Tax Rate .XML

Response x Added new fields available under

SalesOrderMethods x Added new fields available under

Brand Methods x Added new fields available under

Product Methods x Added new fields available under

Supplier Methods x Added new fields available under

Wholesale Methods x Updated WSDL links x Added Appendix: V1.2

Enhancements x Updated Fields for V1.2

Sam Sexson

6/9/2011 2.0.1 x Updated DOB Requirements x Added Appendix F: Technical Notes

about DateTime

Sam Sexson

7/12/2011 2.0.5 Added Method Descriptions for: x AddExternalClubKey x AddExternalOfferKey x SetExternalClubKeys x SetExternalOfferKey x SetExternalCustomerKey x SetExternalSalesOrderKey x SearchProducts x SearchMoreProducts x ClearFulfillmentException x GetPossibleFulfillmentHouses x GetPossibleRuleTypes x GetPossibleShippingService x ChangeProductKey x UpdateProductWholesalePrices x GetProductWholesalePrices x SearchProducts x IsProductCompliant

Sam Sexson

7/25/2011 2.0.6 Added Sample XML Response for: x GetTaxRatesByAddress x CheckTemperatureForecast x Added the following

Sam Sexson



WholesaleService methods: x AddBrandDistribution x AddDistributionTerritories x AddUpdateDistributor" x GetAvailableTerritories x GetDistributor x RemoveBrandDistribution x RemoveDistributionTerritories

8/19/2011 2.0.7 x Added to

x Added to

Sam Sexson

9/12/2011 2.0.8 x Updated Fulfillment Location VintageLogistics to WineShippingSantaMaria for API V1.1 and 1.2

Sam Sexson

9/29/2011 2.0.9 x CalculateSalesTaxDueForOrder x Added .XML sample requests and

responses for and

Sam Sexson

7/15/2012 2.0.10 x Added WineDirect as a possible Fulfillment House

x Updated Input Tags x Added enhancements for Wholesale

Service x Added enhancements for Product

Service x Added enhancements for Brand

Service x Added Each x Updated Ignore and Reject Defaults

in AddressOptions

Sam Sexson

10/18/2012 2.0.11 x Added and fields to SearchSalesOrders method

Sam Sexson

12/18/2012 2.0.12 x Refinements to existing information and additional clarifications

Sam Sexson

1/8/2012 2.0.13 x Added API Method

Sam Sexson



2 Introduction Dear Integrator, I would like to personally welcome you to Six88 Solutions and ShipCompliant. ShipCompliant offers a full spectrum of compliance management tools from real-time compliance checks on orders from any channel to state reports that are ready to sign and send. This functionality is available for clients shipping alcohol directly to consumers as well as through wholesale channels. Our goal for ShipCompliant Web Services is to provide a complete suite of flexible, easy to use compliance methods that allow you to create a seamless integration with your solution. I encourage you to provide any feedback that you have throughout the integration process. We welcome all comments and suggestions and will use them to make the experience better for you. Best Regards, Sam Sexson ShipCompliant Partner Services

2.1 Overview By using ShipCompliant Web Services, third party integrators (hereafter Integrators) can take advantage of a full suite of methods to manage shipping compliance from any order system of record in real time.

2.2 Getting Started In addition to this reference guide, ShipCompliant has a development environment that can be used to develop and test your integration. If you are interested in receiving credentials to the development environment, please contact ShipCompliant at 303-449-5285 and ask to speak to the person responsible for managing partner integrations. Once you obtain credentials to the development environment, it is critical that you log into the portal to do some initial setup. From the Development Portal, you can also check the status of your requests and verify that your data is set up as you expected. We recommend that you walk through the Compliance Wizard (https://portal-dev.shipcompliant.com/Web/QuickStartWizard/BasicInformation.aspx) , which is an eleven-step wizard that helps wineries get setup and compliant in each state. You can setup a few states to test your sales order requests. To do this, select a few states under Step 2 Shipping Preferences for offsite and onsite sales, then follow the rest of the steps, entering test data to make each step have a Completed status.



We also have a series of training videos and help materials under the Help tab in the main navigation that you may find helpful in understanding how ShipCompliant works. To search for sales orders to review your data, you can go to the Orders tab, then Search Orders within the development portal (or go directly to https://portal-dev.shipcompliant.com/Web/ViewPastOrders/SearchOrders.aspx).

2.3 Current Version The current version of the ShipCompliant Web Services is 1.2 At the end of May 2011, ShipCompliant released version 1.2 of web services. This section outlines all the changes that have been made to the ShipCompliant Web Services API between versions 1.0 , 1.1, and 1.2. ShipCompliant strongly encourages partners that are currently using version 1.0 or 1.1 of the web services to upgrade to version 1.2 of the web services. When designing version 1.2, ShipCompliant made an effort to minimize the amount of effort needed to upgrade. Most changes made between versions 1.0 and 1.1 involve changing parameters from type Enum to String. Updating the parameters from enumerations to strings increases the flexibility of the API. For instance, a new fulfillment house, product type or rule type can now be added without causing issues to existing integrations. ShipCompliant recommends that any integration based on version 1.2 takes into consideration that new string values for existing fields may be added in the future. Please refer to Section 0 for a list of all possible values for each field supported in version 1.2 of the API. Other noteworthy updates under version 1.2 include enhancements to the TaxService to support sales tax rates on additional product types and a new WholesaleService to support wholesale orders in the API. ShipCompliant has also added support for Single Sign On into ShipCompliant from external systems. Version 1.2 also includes the addition of new fields to support the same level of functionality that is currently available through the web portal. For those partners who elect not to upgrade to version 1.2, ShipCompliant plans to continue to support version 1.0 and 1.1 indefinitely.

2.4 Versioning and Services The production URL follows this format: https://[DomainName]/Services/[Version]/[ServiceName].asmx



The development URL follows this format: https://ws-dev.shipcompliant.com/Services/[Version]/ [ServiceName].asmx For example, the 1.2 development product services are located here: https://ws-dev.shipcompliant.com/Services/1.2/ProductService.asmx To access the field request and response formal definitions, append ?WSDL to the end of the URL. For example: https://ws-dev.shipcompliant.com/Services/1.2/ProductService.asmx?WSDL To access the ShipCompliant Portal on the development server, where you can setup your development account and view the data that you have inserted via web services, you can login to https://portal-dev.shipcompliant.com. We will give you separate sets of credentials to access the web services and portal. The maintenance URL follows this format: https://ws-maint.shipcompliant.com/Services/[Version]/ [ServiceName].asmx The maintenance server always replicates the production database. Typically, the maintenance database will be restored from production at the beginning of each month, immedietly following a production update deployment. Therefore, maintenance is a good way to test on real client data without affecting the production database. Since the entire database is restored from production, the usernames and passwords on maintenance will be the same as production. The URL for the maintenance server portal is https://portal-maint.shipcompliant.com . We also have a "demo" environment available at https://ws-demo.shipcompliant.com. This environment is "production grade"(stable) and is available for you to run sales and marketing demonstrations. Please contact us if you need access to a demo account. Note: all communications must be via HTTPS (port 443); requests via HTTP (port 80) will not be accepted. The versions start at 1.0 and will continue up from there as the web service API is updated with non-backwards compatible changes, (currently version 1.2 is the latest available). The methods exposed via the web services are divided into logical units, similar to a set of domain objects. These are: BrandService, ProductService, SalesOrderService, TaxService, AgeService, AddressService, SupplierService, WholesaleService, FulfillmentService, and SSOService.

2.5 Web Service API User Portal A web service user has the ability to log into the ShipCompliant Web Service API User Portal by using the existing web service username and password setup for your account. This portal is available on the development server by going to https://portal-dev.shipcompliant.com, and is available on the production server



by going to https://portal.shipcompliant.com. The portal will provide information regarding all the API requests and responses made by the corresponding web service user. This portal can be used to monitor current API activity and can also act as a debug tool if any issues have been encountered with web services requests. Users have the ability to search for past requests based on specified date ranges, activity type, and keyword. Users will also be able to view XML formatted requests and responses. The web service portal also has links to all the current Web Service Reference Guide and WSDLs for each service and method. Below is a screen shot outlining the features available.

Figure 1 Web Service API User Portal

2.6 ShipCompliant Partner Keys ShipCompliant supports the use of a PartnerKey for all API requests for a specific integrator. This is a unique key provided by ShipCompliant to each partner. It should be kept confidential. There are many benefits to using the partner key such as improved support from ShipCompliant, increased security for requests, and the possibility to track and display all requests made by a specific partner across all ShipCompliant accounts that use the integration on a specific



ShipCompliant instance such as the development or production server. The PartnerKey is under the Security area, and is an alpha-numeric code that matches the format displayed below.

login password XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

ShipCompliant requests that Partners include their assigned PartnerKey in all requests. Please contact ShipCompliant for more information about obtaining and using a partner key.

2.7 Partner Portal 2.7.1 Introduction The ShipCompliant Partner Portal is designed to give partners visibility to all accounts using an integration on a particular ShipCompliant server. This portal allows partners to log into a single ShipCompliant account and view API requests and responses for each installation (client) using the integration. The partner portal also includes usage reports and statistics. To fully leverage the partner portal, partners should include their assigned PartnerKey in all API communications. This section includes instructions on how to use the partner portal.



2.7.2 Instructions Please contact ShipCompliant to receive credentials for logging into the partner portal. To access the partner portal on the development server, go to https://portal-dev.shipcompliant.com. To access the partner portal on the production server, go to https://portal.shipcompliant.com. Enter your Partner username and password to log in.

The partner portal page contains two sections: Tools (1) and API Activity Log (2). The Tools section contains links to analytics reports which are designed to help you monitor the status of orders and activity across all accounts. The API Activity Log allows you to view the XML requests and responses as seen by ShipCompliant. Each of these resources is designed to give you insight into how your systems are communicating with ShipCompliant.

2.7.3 Tools Real-Time Shipment Status Report The Real-Time Shipment Status Report provides an up to date view of the shipment status for orders that were recently committed to ShipCompliant.



2.7.4 Tools Shipment Summary Report The Shipment Summary Report provides a summary of all committed, non-voided shipments within an account within a specific date range. This report will give you a better idea of how many shipments have been processed for a given account.



2.7.5 Tools Partner API Activity Summary The API Activity Summary allows you to view a report of the API methods processed by ShipCompliant over a specific date range.



2.7.6 API Activity Log This log displays information for each XML request/response processed by ShipCompliant. It will display details such as the method name, version of the API used, as well as the results of the request. ShipCompliant will also have the XML request and response available for download for any methods which result in an error or non-compliant result.

2.8 Single Sign On

2.8.1 Introduction ShipCompliant Single-Sign-On has been designed to allow partners with API access to authenticate ShipCompliant Portal end users (with the users permission). This enables a seamless user experience when navigating from your system to ShipCompliant. In addition, it allows ShipCompliant UI components to be embedded within the user interface of your application.

2.8.2 User Configuration The user must authorize your system to sign them in to ShipCompliant. This only needs to be configured once (per user) and can be one of several ways:

x by the account administrator when the user is created (My Account > Manage Users > Add User)

x by the account administrator by editing the user (My Account > Manage Users > Edit)

x by the user themselves (My Account > My Settings > Single Sign On Settings)



Figure 2 Enabling SSO for a User

x Note: For testing and development purposes, all partners are available in

the Authorize SSO select list on the development environment (https://ws-dev.shipcompliant.com, https://portal-dev.shipcompliant.com). Partners will only be added to this list in production environments after their single-sign on support is certified by ShipCompliant.

2.8.3 Implementation x The following code demonstrates the usage of the ShipCompliant API to execute a

single sign on to the development environment. Please create a web service reference to:

https://ws-dev.shipcompliant.com/Services/1.1/SsoService.asmx WSDL: https://ws-dev.shipcompliant.com/Services/1.1/SsoService.asmx?wsdl The corresponding portal is: https://portal-dev.shipcompliant.com

x Sample Code (C# 4.0):

//construct the web service ShipCompliant API request var req = new SSOUrlRequest { Security = new Security() { Username = "[email protected]", Password = "yourPassword",



PartnerKey = 00000000-0000-0000-0000-000000000000 //Important! your partner key }, UserEmail = [email protected], //user to "sign on" to ShipCompliant NavigationToken = "analytics" //(optional) specify the function to navigate to }; //make the call to ShipCompliant (dev. server) var proxy = new SSOServiceSoapClient(); proxy.Endpoint.Address = new EndpointAddress("https://ws-dev.shipcompliant.com/Services/1.1/SsoService.asmx"); var ssoResponse = proxy.GetSSOUrl(req); //interpret the result if (ssoResponse.ResponseStatus == ResponseStatus.Success) { //it worked! just redirect browser (or point iFrame) to the Url in the response Response.Redirect(ssoResponse.Url); } else { //Oops there was a problem your system should handle this, it likely means the user has not //authorized SSO in ShipCompliant as described var ssoErrorMsg = ssoResponse.Errors[0].Message; }

x SSO requires that your PartnerKey is passed with every request. In general we ask that all web service requests originating from your system (across all clients) include your Partner Key in the Security Node. The Partner Key is supported in all versions of the ShipCompliant API. The partner key will enable you to quickly view and analyze your API traffic using the Partner Portal. Please contact ShipCompliant for questions regarding your Partner Key or the Partner Portal.

x The NavigationToken is an optional parameter which may be passed in a SSO request. It allows ShipCompliant to bring up a specific screen/function upon successful sign on. If not specified the users home page in ShipCompliant is loaded. The following options are supported:

o Orders : brings up the search orders function in ShipCompliant o Fulfillment: opens fulfillment management o Analytics: opens the analytics table of contents o Setup: opens the ShipCompliant setup area o EmbeddedOrders: opens a screen with recent orders optimized

for smaller screens o EmbeddedHome: opens the ShipCompliant homepage optimized

for smaller screens



The EmbeddedOrders and EmbeddedHome options are optimized for SSO and it is highly recommended that one of these is used as your single-sign-on home page.

3 Order Lifecycle Throughout this document, we reference both the shipment status and compliance status of shipments. We use these status types to ensure that the appropriate shipments are counted towards reporting and volume limits and to allow users and systems to update the status throughout the lifecycle of an order. If tracking numbers are added to a shipment at the time of order entry or after the fact, the system will automatically track the packages associated with each shipment via FedEx, UPS and GSO web services. Shipment statuses will be automatically updated to Shipped when packages are picked up. Once all of the packages are delivered, the shipment status will be updated to Delivered. The UpdateShipmentStatus method can be used to update the status of a shipment as it moves through the order lifecycle.

3.1 Shipment Status Types InProcess In a typical workflow, if an order has been taken, but payment has not been accepted for this order, mark the shipment as InProcess. InProcess shipments do not count towards reporting, but they do count towards volume limit checks. PaymentAccepted If an order has been taken and payment has been accepted for this order, mark it as PaymentAccepted. This is different than InProcess because these orders will count towards reports that are based on payment date. SentToFulfillment When the shipment is ready for fulfillment (this can be either in-house fulfillment or via third party logistics company(3PL)), mark the shipment as SentToFulfillment. This tells the fulfillment operation that the order is ready to be shipped. SentToFulfillment orders count towards both reports that are based on ship date as well as reports based on payment date. Shipped Shipped shipm

Date post:	14-Feb-2016
Category:	Documents
Upload:	sawan-gupta
View:	311 times
Download:	34 times

WS Reference Guide 2-0-13

Documents