Introduction - Avalara Developer Network - Item... · Web viewTo connect to Avalara SFTP server,...

Avalara - Item Classification – File Data Trans

Copyright © 2019 Avalara Inc. P a g e | 1


Avalara - Item Classification - File Data Transfer ContentsIntroduction................................................................................................................................................................................................................. 3File Transfer Protocols.................................................................................................................................................................................................3

SFTP......................................................................................................................................................................................................................... 3AS2........................................................................................................................................................................................................................... 3

File Formats and Naming Convention..........................................................................................................................................................................4HS Classification Request............................................................................................................................................................................................. 4HS Classification Response........................................................................................................................................................................................... 4Models......................................................................................................................................................................................................................... 5

HS Classification Model............................................................................................................................................................................................ 5Item Model.............................................................................................................................................................................................................. 6Item Parameter Model............................................................................................................................................................................................ 7

Parameters List.............................................................................................................................................................................................. 7HS Response Model.................................................................................................................................................................................................9ErrorInfo................................................................................................................................................................................................................ 10ErrorDetail............................................................................................................................................................................................................. 10

Error Codes................................................................................................................................................................................................................ 11Examples.................................................................................................................................................................................................................... 16

JSON....................................................................................................................................................................................................................... 16Request........................................................................................................................................................................................................... 16Response........................................................................................................................................................................................................ 17Error Response for Invalid Json Format...............................................................................................................................................18Error Response for Invalid Values..........................................................................................................................................................18

CSV/EXCEL.............................................................................................................................................................................................................. 20Request........................................................................................................................................................................................................... 20Response........................................................................................................................................................................................................ 20Error Response for Invalid Values..........................................................................................................................................................21

Document History...................................................................................................................................................................................................... 23



IntroductionThis 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:

1. AS2 Identifier 2. AS2 Certificate - for encryption and signing the data 3. 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 Model

Field Type Description ErrorsId String(1000

)Response Only

A unique id generated by Avalara Classification System.

item ItemModel Required Product details ValueRequiredError (5)countryOfDestination String(2) Required Country of destination code (ISO 3166-1 alpha-2). ValueRequiredError (5)

InvalidCountry (125)hsCode String(20) Response

Only This is the HS classification result.

status String(20) Response Only

This 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 NULL

CANNOT_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.

resolution String(1000)

Response Only

This 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 Model

Field Type Description Errorsid Integer Read Only A unique id generated by Avalara

Classification System.companyId Integer Required The unique ID number of the company that

owns this item.ValueRequiredError (5)CompanyInvalidException (3)

itemCode String(255) Required A unique code representing this item. It’s recommended to use the SKU number.

ValueRequiredError (5)MaxStringLengthError (14)ValueMismatch(3003)

description String(1000) Required A short description of the product. It’s also referred as product title or name.

ValueRequiredError (5)MaxStringLengthError (14)

summary String(4000) Optional A long description of the product. MaxStringLengthError (14)itemGroup String(4000) Required Product 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 Trackers

ValueRequiredError (5)

classificationParameters Array of ItemParameterModel

Optional List of item parameters use for classification.

parameters Array of ItemParameterModel

Optional List of item parameters



Item Parameter Model

Field Type Description Errorsname String(255) Required The parameter’s name.

The system has predefined a list of parameter names that are known and processed accordingly: See the Parameters List table

ParameterRequiredError (3000)

value String(1000) Required The parameter’s value.unit String(255) Optional The 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 List

Name Source List Type Description Errorscoo classificationParameters String(2) Country of origin (COO), is

the country of manufacture, production, or growth where the item comes from.

InvalidCountry (125)

image_url classificationParameters String(1000) Image URL. ParameterValueMaxStringLengthError(3002)url classificationParameters String(1000) Item URL ParameterValueMaxStringLengthError(3002)



price classificationParameters Decimal(10,2) Item price.Must be a numeric value greater than zero.For “price” parameter unit of measurement (currency) is required.

InvalidParameterValueDataType (2012)

job classificationParameters String(1000) Job identifier. If not explicitly provided in the request, the application will automatically use file name.

ParameterValueMaxStringLengthError(3002)

material classificationParameters String(1000) Product material ParameterValueMaxStringLengthError(3002)color classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)brand classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)size classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)adult classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)upc classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)ean classificationParameters String(1000) ParameterValueMaxStringLengthError(3002)hs_hint classificationParameters String(6) HS hint ParameterValueMaxStringLengthError(3002)hs_code_test classificationParameters String(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 parameters Decimal(14,4) Item weight. Must be a numeric value greater than zero.




height parameters Decimal(14,4) Item height. Must be a numeric value greater than zero.


length parameters Decimal(14,4) Item length. Must be a numeric value greater than zero.


width parameters Decimal(14,4) Item width.Must be a numeric value greater than zero.


HS Response Model

Field Type Description Errorsclassifications Array of

HSClassificationResponse Only

List of product HS classifications.

processedDateTime Response Only

Date and time when the item was classified by Avalara system. Example:2019-04-16T00:00:00+00:00



ErrorInfo

Field Type Descriptionrequest HSClassificationRequest Read Only The original HS Classification Request.

errors ErrorDetail Read Only Array of detailed error messages

ErrorDetail

Field Type Descriptioncode enum Read Only Name of the error. Refer to Error Codes section for a list of accepted values.number Integer Read Only Unique ID number referring to this error or message.message String Read Only Concise summary of the message, suitable for display in the caption of an alert box.description String Read Only A more detailed description of the problem referenced by this error message, suitable for

display in the contents area of an alert box.helpLink String Read Only

OptionalURL to help for this message

refersTo String Read OnlyOptional

Item the message refers to, if applicable. This is used to indicate a missing or incorrect value.

severity enum Read OnlyOptional

Severity of the message: Error



Error Codes

ID Error Summary Example3 CompanyInvalidException The 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": "http://developer.avalara.com/avatax/errors/CompanyInvalidException", "severity": "Error" }

4 EntityNotFoundError You 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": "http://developer.avalara.com/avatax/errors/EntityNotFoundError", "severity": "Error" }

5 ValueRequiredError You 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": "http://developer.avalara.com/avatax/errors/ValueRequiredError", "severity": "Error" }

14 MaxStringLengthError The string you provided was too long for the field.Some fields can only accommodate

{ "code": "MaxStringLengthError", "number": 14, "message": "Field '-0-' has an invalid length.",



strings of a specified maximum length.

"description": "Field '-0-' must be no more than -1- characters in length.", "helpLink": "http://developer.avalara.com/avatax/errors/MaxStringLengthError", "severity": "Error" }

31 AuthorizationException Your 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": "http://developer.avalara.com/avatax/errors/AuthorizationException", "severity": "Exception" }

34 AuthenticationIncomplete Your 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": "http://developer.avalara.com/avatax/errors/AuthenticationIncomplete", "severity": "Exception" }

37 BearerTokenInvalid The 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": "http://developer.avalara.com/avatax/errors/BearerTokenInvalid", "severity": "Exception" }

50 UnhandledException The API you attempted to call resulted in an unhandled exception.This code indicates that an error

{ "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.



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.

No action is required.", "helpLink": "http://developer.avalara.com/avatax/errors/UnhandledException", "severity": "Exception" }

70 ModelStateInvalid You 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": "http://developer.avalara.com/avatax/errors/ModelStateInvalid", "severity": "Error" }

125 InvalidCountry The 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:

{ "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": "http://developer.avalara.com/avatax/errors/InvalidCountry", "severity": "Error" }



http://www.iso.org/iso/country_codes or the Wikipedia article listing current codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

193 DuplicateEntry The 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": "http://developer.avalara.com/avatax/errors/DuplicateEntry", "severity": "Error" }

2102 InvalidParameterValueDataType A 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": "http://developer.avalara.com/avatax/errors/InvalidParameterValueDataType", "severity": "Error" }

3000 ParameterRequiredError One of the parameters in the request { "code": "ParameterRequired",



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-.

"number": 3000, "message": "One of the required parameters is missing.", "description": "Parameter '-0-' is required.", "helpLink": "", "severity": "Error" }

3001 ParameterUnitMeasurementRequired

A 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" }

3002 ParameterValueMaxStringLengthError

The 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": "http://developer.avalara.com/avatax/errors/MaxStringLengthError", "severity": "Error" }

3003 ValueMismatch The 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": "http://developer.avalara.com/avatax/errors/MaxStringLengthError", "severity": "Error" }



Examples

JSON

Request[ { "item":{ "companyId":12345, "itemCode":"SKU001", "description":"Vera Wang Night Gown", "itemGroup":"Clothing > Women > Formal", "classificationParameters":[ { "name":"url", "value":"http://merchant_host.com/path_to_product/SKU001", }, { "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":"http://merchant_host.com/path_to_product/SKU001" }, { "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":"http://developer.avalara.com/avatax/errors/JsonFormatError", "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":"http://merchant_host.com/path_to_product/SKU001", }, { "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":"http://developer.avalara.com/avatax/errors/MaxStringLengthError", "severity":"Error" } ] }, { "request":{ "item":{ "companyId":12345, "itemCode":"SKU002", "description":"Vera Wang Night Gown", "itemGroup":"Clothing > Women > Formal", "classificationParameters":[ { "name":"url", "value":"http://merchant_host.com/path_to_product/SKU001", "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":"http://developer.avalara.com/avatax/errors/InvalidCountry", "severity":"Error" } ] }]

CSV/EXCEL

Request

item

Code

com

pany

Id

coun

tryO

f De

stina

tion

desc

riptio

n

sum

mar

y

item

Grou

p

url

pric

e

leng

th

wid

th

heig

ht

wei

ght

SKU00100 221099 CAVera Wang Night Gown

Very nice dress for formal occasions coming from Vera Wang summer line.

Clothing > Women > Formal http://merchant_host.com/ SKU00100

10 2.3 1.1 0.7 5



Clothing > Women > Formal > NEW URL-01 http://merchant_host.com/SKU001001

12 1.8 2.2 1.9 3



Clothing > Women > Formal > NEW URL-02 http://merchant_host.com/SKU001002

22 0.7 7.1 5.2 10



Responseite

mCo

de

com

pany

Id

coun

tryO

f

desc

riptio

n

sum

mar

y

item

Grou

p

url

pric

e

leng

th

wid

th

heig

ht

wei

ght

stat

us

hsCo

de

reso

lutio

n

proc

esse

dDat

eTim

e

SKU00100

221099 CA

Vera Wang Night Gown


Clothing > Women > Formal

http://merchant_host.com/ SKU00100

10 2.3 1.1 0.7 5

CLASSIFIED 1234567890

2019-04-16T00:00:00+00:00

SKU00101

221099 CA



Clothing > Women > Formal > NEW URL-01


12 1.8 2.2 1.9 3

CLASSIFIED 1234567890

2019-04-16T00:00:00+00:00

SKU00102

221099

CA Vera Wang Night Gown

Very nice dress for formal occasions coming from Vera

Clothing > Women > Formal > NEW URL-02


22 0.7 7.1 5.2 10

CANNOT_BE_CLASSIFIED

Missing title and url.

2019-04-16T00:00:00+00:00



Wang summer line.

Error Response for Invalid Values

item

Code

com

pany

Id

coun

tryO

f De

stina

tion

desc

riptio

n

sum

mar

y

item

Grou

p

url

erro

rCod

e

erro

rNum

ber

erro

rMes

sage

erro

rDes

crip

tion

SKU00100 221099 CA



Clothing > Women > Formal ValueRequiredError 5

Field description is required.

Please provide a value for field description. ValueRequiredError

SKU00101 221099 CA



Clothing > Women > Formal > NEW URL-01 InvalidCountry 3

The country 'XX' is not a recognized country code

The country 'XX' is not a recognized country code InvalidCountry



Document HistoryRevision Date Author Comments1 June 12, 2018 Mircea Niculescu First draft 2 June 19, 2018 Mircea Niculescu Added SLA paragraph3 July 20, 2018 Mircea Niculescu Replace SLA paragraph with Priorities4 July 27, 2018 Mircea Niculescu Updated accepted values for Activities field5 July 31, 2018 Mircea Niculescu Added File Name Convention paragraph6 September 4, 2018 Mircea Niculescu Fixed error field names7 January 9, 2019 Theepan Thiyagarajah Added support for Excel and CSV file format.8 January 9, 2019 Mircea Niculescu Reviewed, updated specs for json, excel and csv9 January 30,2019 Mircea Niculescu Removed support for Excel xls file format10 March 8, 2019 Mircea Niculescu Version 211 April 4, 2019 Mircea Niculescu Added “job” as supported parameter name.

Added support for multiple category pathsAdded support for HS HintsExamples for json request and response

12 April 10, 2019 Mircea Niculescu Examples for Excel/CSV13 April 26, 201`9 Mircea Niculescu Moved HS Hint under classificationParameters

Added 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 Model

14 April 30, 2019 Mircea Niculescu Changed “description” field max length to 1000Added “hs_code_test” parameter

15 May 7, 2019 Mircea Niculescu Updated response file name16 November 11, 2019 Mircea Niculescu Updated errors for ItemClassificationModel


Introduction - Avalara Developer Network - Item... · Web viewTo connect to Avalara SFTP server,...

Documents

Transcript of Introduction - Avalara Developer Network - Item... · Web viewTo connect to Avalara SFTP server,...