Introduction - Avalara Developer Network



Avalara - Item Classification - File Data Transfer Contents TOC \o "1-3" \h \z \u Introduction PAGEREF _Toc7185234 \h 3File Transfer Protocols PAGEREF _Toc7185235 \h 3SFTP PAGEREF _Toc7185236 \h 3AS2 PAGEREF _Toc7185237 \h 3File Formats and Naming Convention PAGEREF _Toc7185238 \h 4HS Classification Request PAGEREF _Toc7185239 \h 4HS Classification Response PAGEREF _Toc7185240 \h 4Models PAGEREF _Toc7185241 \h 5HS Classification Model PAGEREF _Toc7185242 \h 5Item Model PAGEREF _Toc7185243 \h 6Item Parameter Model PAGEREF _Toc7185244 \h 7Parameters List PAGEREF _Toc7185245 \h 7HS Response Model PAGEREF _Toc7185246 \h 9ErrorInfo PAGEREF _Toc7185247 \h 10ErrorDetail PAGEREF _Toc7185248 \h 10Error Codes PAGEREF _Toc7185249 \h 11Examples PAGEREF _Toc7185250 \h 16JSON PAGEREF _Toc7185251 \h 16Request PAGEREF _Toc7185252 \h 16Response PAGEREF _Toc7185253 \h 17Error Response for Invalid Json Format PAGEREF _Toc7185254 \h 18Error Response for Invalid Values PAGEREF _Toc7185255 \h 18CSV/EXCEL PAGEREF _Toc7185256 \h 20Request PAGEREF _Toc7185257 \h 20Response PAGEREF _Toc7185258 \h 20Error Response for Invalid Values PAGEREF _Toc7185259 \h 21Document History PAGEREF _Toc7185260 \h 23IntroductionThis document describes data transfer process for HS classification between clients and Avalara. It covers the data transfer flows, file format and transfer protocols.File Transfer ProtocolsAvarala supports two types of transfer protocols: AS2 and SFTP.SFTPTo connect to Avalara SFTP server, you’ll need to generate a public/private key pair. Provide Avalara with the public key and add the private key to your client software. Avalara will supply you back a user name and the SFTP URL. After connecting to the SFTP server you’ll have access to two directories. Upload the requests for classification (product and category files) in the “inbound” directory. The processing errors (if any) and the classification results will be available in the “outbound” directory.AS2To connect to Avalara AS2 server you’ll need to exchange the following information with us:AS2 Identifier AS2 Certificate - for encryption and signing the data AS2 endpoint - comprised of IP address, port and a URI Avalara supports only synchronous MDN.You’ll have to send us all requests for classification via products/category files in json, excel or csv format. In return Avalara will send back the processing errors (if any) and the classification results using the same format we received your requests.File Formats and Naming ConventionAvalara supports json, Excel and CSV as formats for data request and response.File extensions must be according with the file format: json for json files, xlsx for Excel and csv for CSV files.All request file names must start with “HSCR.V2.”. Example: HSCR.V2.GRG009_CA.jsonResponse file names (classifications) start with “HSCR.CLASSIFICATION.V2.”.HS Classification RequestAll requests for HS classification should be sent to Avalara in files using one of the supported formats: json, csv or Excel. File format will be setup when the customer enrolls for the service. Once setup is complete, a customer can only use the chosen format. One file can contain one or multiple requests. Each request must follow the specifications defined for HS Classification Model. In case a request for HS Classification is invalid and cannot be processed, Avalara will generate a response file with the errors.HS Classification ResponseAfter a product was classified the response will be sent back to customer using the same format customer opted for. One file can contain one or multiple responses. The response follows specifications defined for HS Response Model.Models HS Classification ModelFieldTypeDescriptionErrorsIdString(1000)Response OnlyA unique id generated by Avalara Classification System.itemItemModelRequiredProduct detailsValueRequiredError (5)countryOfDestinationString(2)RequiredCountry of destination code (ISO 3166-1 alpha-2).ValueRequiredError (5)InvalidCountry (125)hsCodeString(20)Response Only This is the HS classification result. statusString(20)Response OnlyThis value is returned in the response only and it’ll be ignored if it’s provided in the request. CLASSIFIED - the item was classified, and an HS code was assigned. In this case the hsCode field is not NULLCANNOT_BE_CLASSIFIED – the item cannot be classified based on the information provided. A more detailed explanation is provided in the resolution field. The hsCode is NULL.resolutionString(1000)Response OnlyThis value is returned in the response only and it’ll be ignored if it’s provided in the request. A resolution is returned only if an item cannot be classified (status=CANNOT_BE_CLASSIFIED). It contains a detailed description of the issue. Item ModelFieldTypeDescriptionErrorsidIntegerRead OnlyA unique id generated by Avalara Classification panyIdIntegerRequiredThe unique ID number of the company that owns this item.ValueRequiredError (5)CompanyInvalidException (3)itemCodeString(255)RequiredA unique code representing this item. It’s recommended to use the SKU number.ValueRequiredError (5)MaxStringLengthError (14)ValueMismatch(3003)descriptionString(1000)RequiredA short description of the product. It’s also referred as product title or name. ValueRequiredError (5)MaxStringLengthError (14)summaryString(4000)OptionalA long description of the product.MaxStringLengthError (14)itemGroupString(4000)RequiredProduct category breadcrumbs. This is the full path to the category where item is included. Categories should be separated by “ > “. Please note that each category (breadcrumb) should not exceed 100 characters. Multiple category paths per item are accepted. In this case, category paths should be separated by “;”.Example: Sports & Outdoors > Exercise & Fitness > Wearable Technology > Fitness TrackersValueRequiredError (5)classificationParametersArray of ItemParameterModelOptionalList of item parameters use for classification.parametersArray of ItemParameterModelOptionalList of item parametersItem Parameter ModelFieldTypeDescriptionErrorsnameString(255)RequiredThe parameter’s name.The system has predefined a list of parameter names that are known and processed accordingly: See the Parameters List tableParameterRequiredError (3000)valueString(1000)RequiredThe parameter’s value.unitString(255)OptionalThe unit of measurement code for the parameter. For price parameter the unit is required and must be currency code alpha ISO 4217. For dimensions (length, width, height) the default value is “IN” (inches). Accepted values are: “IN”, “CM”, “M”.For weight the default value is “LB” (pounds). Accepted values are: “LB”, “OZ”, “KG”, ”G”.Units of measurement are case insensitive.Only for “price” parameter:ParameterUnitMeasurementRequired (3001)If the unit has a predefined list of accepted values (e.g. for parameter “price”, “weight”, “length”, “width” or “height”):InvalidParameterUnitMeasurementType(2100)Parameters ListNameSource ListType DescriptionErrorscoo classificationParametersString(2)Country of origin (COO), is the country of manufacture, production, or growth where the item comes from.InvalidCountry (125)image_url classificationParametersString(1000)Image URL.ParameterValueMaxStringLengthError(3002)url classificationParametersString(1000)Item URLParameterValueMaxStringLengthError(3002)price classificationParametersDecimal(10,2)Item price.Must be a numeric value greater than zero.For “price” parameter unit of measurement (currency) is required.InvalidParameterValueDataType (2012)jobclassificationParametersString(1000)Job identifier. If not explicitly provided in the request, the application will automatically use file name.ParameterValueMaxStringLengthError(3002)materialclassificationParametersString(1000)Product materialParameterValueMaxStringLengthError(3002)colorclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)brandclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)sizeclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)adultclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)upcclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)eanclassificationParametersString(1000)ParameterValueMaxStringLengthError(3002)hs_hintclassificationParametersString(6)HS hintParameterValueMaxStringLengthError(3002)hs_code_testclassificationParametersString(20)HS code for testing. This parameter can be used in a sandbox/integration environment to pass an HS Code directly. In this case the product will not be reviewed by any operator and a response will be sent back in a matter of minutes.ParameterValueMaxStringLengthError(3002)weight parametersDecimal(14,4)Item weight. Must be a numeric value greater than zero.InvalidParameterValueDataType (2012)height parametersDecimal(14,4)Item height. Must be a numeric value greater than zero.InvalidParameterValueDataType (2012)length parametersDecimal(14,4)Item length. Must be a numeric value greater than zero.InvalidParameterValueDataType (2012)widthparametersDecimal(14,4)Item width.Must be a numeric value greater than zero.InvalidParameterValueDataType (2012)HS Response ModelFieldTypeDescriptionErrorsclassificationsArray of HSClassificationResponse OnlyList of product HS classifications.processedDateTimeResponse OnlyDate and time when the item was classified by Avalara system. Example:2019-04-16T00:00:00+00:00ErrorInfoFieldTypeDescriptionrequestHSClassificationRequestRead OnlyThe original HS Classification Request.errorsErrorDetailRead OnlyArray of detailed error messagesErrorDetailFieldTypeDescriptioncodeenumRead OnlyName of the error. Refer to Error Codes section for a list of accepted values.numberIntegerRead OnlyUnique ID number referring to this error or message.messageStringRead OnlyConcise summary of the message, suitable for display in the caption of an alert box.descriptionStringRead OnlyA more detailed description of the problem referenced by this error message, suitable for display in the contents area of an alert box.helpLinkStringRead OnlyOptionalURL to help for this messagerefersToString Read OnlyOptionalItem the message refers to, if applicable. This is used to indicate a missing or incorrect value.severityenumRead OnlyOptionalSeverity of the message: Error Error CodesIDError SummaryExample3CompanyInvalidExceptionThe company with the specific ID number does not exist, or you do not have access to use that company. { "code": "CompanyInvalidException", "number": 3, "message": "Company could not be found.", "description": "The company -0- does not exist, or you do not have the rights to view it.", "helpLink": "", "severity": "Error" }4EntityNotFoundErrorYou attempted to act on, retrieve, update, or delete an object that does not exist.This problem occurs when an object cannot be found.Have you inadvertently misspelled the code or used the wrong ID number for an object?Check your URL and ensure that the object you are attempting to use exists. { "code": "EntityNotFoundError", "number": 4, "message": "-0- not found.", "description": "The -0- with -2- '-1-' was not found.", "helpLink": "", "severity": "Error" }5ValueRequiredErrorYou submitted a request and did not provide a value in a required field.The field designated by -0- in your error message is required. Your request cannot be processed until you resubmit it with a value in that field. { "code": "ValueRequiredError", "number": 5, "message": "Field -0- is required.", "description": "Please provide a value for field -0-.", "helpLink": "", "severity": "Error" }14MaxStringLengthErrorThe string you provided was too long for the field.Some fields can only accommodate strings of a specified maximum length. { "code": "MaxStringLengthError", "number": 14, "message": "Field '-0-' has an invalid length.", "description": "Field '-0-' must be no more than -1- characters in length.", "helpLink": "", "severity": "Error" }31AuthorizationExceptionYour account is not authorized to call this API. { "code": "AuthorizationException", "number": 31, "message": "Authorization failed.", "description": "This service or operation is not authorized for this account or user.", "helpLink": "", "severity": "Exception" }34AuthenticationIncompleteYour API call did not contain authentication information.Avalara looks for these values in the HTTP “Authorization” header. The Basic values are expected to be Base64 encoded as specified by the HTTP standard.Please check your HTTP request headers and verify that you are providing the correct values. { "code": "AuthenticationIncomplete", "number": 34, "message": "Authentication Incomplete.", "description": "You must provide an Authorization header of the type Bearer to authenticate correctly. -0-", "helpLink": "", "severity": "Exception" }37BearerTokenInvalidThe Bearer Token that you used for authentication was not valid. { "code": "BearerTokenInvalid", "number": 37, "message": "The Bearer token you provided was not recognized by Avalara.", "description": "If you have received a bearer token from Avalara, this token may have expired. Please contact Avalara and request a refreshed token.", "helpLink": "", "severity": "Exception" }50UnhandledExceptionThe API you attempted to call resulted in an unhandled exception.This code indicates that an error message has been escalated to Avalara operations team members for analysis. You should not experience this error code during normal operations.There is no action required of you when you experience this error message. This error has already been logged and escalated to Avalara’s service reliability engineering team. { "code": "UnhandledException", "number": 50, "message": "An invalid exception handler routine has been detected.", "description": "This error has been logged and reported to Avalara system administrators. No action is required.", "helpLink": "", "severity": "Exception" }70ModelStateInvalidYou provided an incorrect object. { "code": "ModelStateInvalid", "number": 70, "message": "Invalid JSON object.", "description": "The request body does not represent a valid JSON object. The value '-1-' is not a valid '-0-'.", "helpLink": "", "severity": "Error" }125InvalidCountryThe country code you provided is not recognized as a valid ISO 3166 country code.All Avalara country codes are two-character ISO 3166 codes. Please verify that the country/region combination you are specifying matches the ISO 3166 definitions.For more information on the international standard for ISO 3166 country/region codes, please see the ISO webpage: or the Wikipedia article listing current codes: { "code": "InvalidCountry", "number": 125, "message": "The country '-0-' is not a recognized country code.", "description": "Please use the `ListCountries` API to identify a list of ISO 3166 countries and codes.", "helpLink": "", "severity": "Error" }193DuplicateEntryThe key or name already exists.Objects must be uniquely named and identified. In most cases, two objects cannot have the same code or name. Please check your object, ensure the name and code are unique, and try your API call again. { "code": "DuplicateEntry", "number": 193, "message": "The object is a duplicate of an existing object.", "description": "The object that you are trying to create already exists. Each -0- object must have a unique identity. The identity of a -0- is determined by the fields: -1-.", "helpLink": "", "severity": "Error" }2102InvalidParameterValueDataTypeA parameter value in the request has an invalid data type. Certain parameters are expected to be of a certain type. In your request, you’ve sent a parameter with an unexpected attribute type.To find the correct attribute type for your request’s parameter, look at the error’s description. Using the example error above, you can see the correct parameter type in the -2- position of your error description. If you aren’t sure what parameter caused the error, check the -1- position of your error’s description. { "code": "InvalidParameterValueDataType", "number": 2102, "message": "The parameter value is not valid for the required data type.", "description": "The parameter value '-0-' is not valid for the '-1-' data type required by parameter '-2-'.", "helpLink": "", "severity": "Error" }3000ParameterRequiredErrorOne of the parameters in the request is missing.Some parameters are mandatory. You can find which parameter is causing the error in your error’s description. Looking at the example error, the error causing parameter is at position -0-.{ "code": "ParameterRequired", "number": 3000, "message": "One of the required parameters is missing.", "description": "Parameter '-0-' is required.", "helpLink": "", "severity": "Error" }3001ParameterUnitMeasurementRequiredA unit of measurement for a parameter in the request is missing.Parameters related to units of measurement expect a certain measurement type. For example, for “price” parameter, the currency is expected in the unit.{ "code": " ParameterUnitMeasurementRequired ", "number": 3001, "message": "The unit measurement is missing for the parameter.", "description": "The parameter '-0-' requires a unit of measurement.", "helpLink": "", "severity": "Error" }3002ParameterValueMaxStringLengthErrorThe string you provided was too long for the parameter value.Some parameter values can only accommodate strings of a specified maximum length. { "code": "ParameterValueMaxStringLengthError", "number": 3002, "message": "The value for parameter '-0-' has an invalid length.", "description": "Value for parameter '-0-' must be no more than -1- characters in length.", "helpLink": "", "severity": "Error" }3003ValueMismatchThe value provided for one of the fields during an update call doesn’t match the original value used when the original request was created.The field name is designated by -0-, the original value in -2- and the new value in -1-. { "code": "ValueMismatch", "number": 3003, "message": "The value for '-0-' does not match the value provided when the original request was created.", "description": "Value ‘-1- ‘ provided for '-0-' is different than the value -2- provided when the request was created", "helpLink": "", "severity": "Error" } ExamplesJSON Request[ { "item":{ "companyId":12345, "itemCode":"SKU001", "description":"Vera Wang Night Gown", "itemGroup":"Clothing > Women > Formal", "classificationParameters":[ { "name":"url", "value":"", }, { "name":"price", "value":"120.50", "unit":"USD" } ], " parameters":[ { "name":"weight", "value":"10.2", "unit":"lb" } ] }, "countryOfDestination":"CA" }]Response{?????"classifications":[????????{???????????"id":"1234-SKU001-CA",?????????"item":{??????????????"id":56789,????????????"companyId":12345,????????????"itemCode":"SKU001",????????????"description":"Vera?Wang?Night?Gown",????????????"itemGroup":"Clothing?>?Women?>?Formal",????????????"classificationParameters":[?????????????????{????????????????????"name":"url",??????????????????"value":""???????????????},???????????????{????????????????????"name":"job",??????????????????"value":"abc"???????????????}????????????],????????????"?parameters":[?????????????????{????????????????????"name":"weight",??????????????????"value":"10.2",??????????????????"unit":"lb"???????????????}????????????]?????????},?????????"countryOfDestination":"CA",?????????"status":"CLASSIFIED",?????????"hsCode":"61611234"??????},??????{???????????"id":"6436-SKU001-AU",?????????"item":{??????????????"id":56789,????????????"companyId":12345,????????????"itemCode":"SKU001",????????????"description":"some?gibberish",????????????"itemGroup":"Clothing?>?Women?>?Formal"?????????},?????????"countryOfDestination":"CA",?????????"status":"CANNOT_BE_CLASSIFIED",?????????"resolution":"Not?enough?data.?Missing?URL"??????}???],???"processedDateTime":"2019-04-16T00:00:00+00:00"}Error Response for Invalid Json Format[ { "errors":[ { "code":"JsonFormatError", "number":47, "message":"The request body did not contain valid JSON.", "description":" The request body did not contain valid JSON.", "helpLink":"", "severity":"Error" } ] }]Error Response for Invalid Values[?????{????????"request":{???????????"item":{??????????????"companyId":12345,????????????"itemCode":"SKU001",????????????"description":"Vera?Wang?Night?Gown",????????????"itemGroup":"Clothing?>?Women?>?Formal",????????????"classificationParameters":[?????????????????{????????????????????"name":"url",??????????????????"value":"",???????????????},???????????????{????????????????????"name":"price",??????????????????"value":"120.50",??????????????????"unit":"USD"???????????????},???????????????{????????????????????"name":"job",??????????????????"value":"abc"???????????????}????????????]?????????},?????????"countryOfDestination":"CA"??????},??????"errors":[???????????{??????????????"code":"MaxStringLengthError",????????????"number":14,????????????"message":"Field?'description'?has?an?invalid?length.",????????????"description":"Field?'description'?must?be?no?more?than?2000?characters?in?length.",????????????"helpLink":"",????????????"severity":"Error"?????????}??????]???},???{????????"request":{???????????"item":{??????????????"companyId":12345,????????????"itemCode":"SKU002",????????????"description":"Vera?Wang?Night?Gown",????????????"itemGroup":"Clothing?>?Women?>?Formal",????????????"classificationParameters":[?????????????????{????????????????????"name":"url",??????????????????"value":"",??????????????????"unit":""???????????????},???????????????{????????????????????"name":"price",??????????????????"value":"120.50",??????????????????"unit":"USD"???????????????}????????????],????????????"?parameters":[?????????????????{????????????????????"name":"job",??????????????????"value":"abd"???????????????}????????????]?????????},?????????"countryOfDestination":"QQ"??????},??????"errors":[???????????{??????????????"code":"InvalidCountry",????????????"number":125,????????????"message":"The?country?XX?is?not?a?recognized?country?code.",????????????"description":"Please?use?the?`ListCountries`?API?to?identify?a?list?of?ISO?3166?countries?and?codes.",????????????"helpLink":"",????????????"severity":"Error"?????????}??????]???}]CSV/EXCEL RequestitemCodecompanyIdcountryOf DestinationdescriptionsummaryitemGroupurlpricelengthwidthheightweightSKU00100221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal SKU00100102.31.10.75SKU00101221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal > NEW URL-01 Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal > NEW URL-02 DestinationdescriptionsummaryitemGroupurlpricelengthwidthheightweightstatushsCoderesolutionprocessedDateTimeSKU00100221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal SKU00100102.31.10.75CLASSIFIED12345678902019-04-16T00:00:00+00:00SKU00101221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal > NEW URL-01 SKU001001121.82.21.93CLASSIFIED12345678902019-04-16T00:00:00+00:00SKU00102221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal > NEW URL-02 SKU001002220.77.15.210CANNOT_BE_CLASSIFIEDMissing title and url.2019-04-16T00:00:00+00:00Error Response for Invalid ValuesitemCodecompanyIdcountryOf DestinationdescriptionsummaryitemGroupurlerrorCodeerrorNumbererrorMessageerrorDescriptionSKU00100221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > FormalValueRequiredError5Field description is required.Please provide a value for field description.ValueRequiredErrorSKU00101221099CAVera Wang Night GownVery nice dress for formal occasions coming from Vera Wang summer line.Clothing > Women > Formal > NEW URL-01InvalidCountry3The country 'XX' is not a recognized country codeThe country 'XX' is not a recognized country codeInvalidCountryDocument HistoryRevisionDateAuthorComments1June 12, 2018Mircea NiculescuFirst draft 2June 19, 2018Mircea NiculescuAdded SLA paragraph3July 20, 2018Mircea NiculescuReplace SLA paragraph with Priorities4July 27, 2018Mircea NiculescuUpdated accepted values for Activities field5July 31, 2018Mircea NiculescuAdded File Name Convention paragraph6September 4, 2018Mircea NiculescuFixed error field names7January 9, 2019Theepan ThiyagarajahAdded support for Excel and CSV file format.8January 9, 2019Mircea NiculescuReviewed, updated specs for json, excel and csv9January 30,2019Mircea NiculescuRemoved support for Excel xls file format10March 8, 2019Mircea NiculescuVersion 211April 4, 2019Mircea NiculescuAdded “job” as supported parameter name.Added support for multiple category pathsAdded support for HS HintsExamples for json request and response12April 10, 2019Mircea NiculescuExamples for Excel/CSV13April 26, 201`9Mircea NiculescuMoved HS Hint under classificationParametersAdded file naming conventionsModified the response format (added processedDateTime)Modified Error Response FormatChanged Item’s summary field as optionalAdded definition for id field for Item Model and HS Classification Model14April 30, 2019Mircea NiculescuChanged “description” field max length to 1000Added “hs_code_test” parameter15May 7, 2019Mircea NiculescuUpdated response file name16November 11, 2019Mircea NiculescuUpdated errors for ItemClassificationModel ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download