Avalara Developer Network Developer trustFile

TrustFile Connector Management API

All custom integration / ETL ought to behave/operate in the exact same way. Adhering to this documentation will allow this

Tokens:

  • connectorToTFToken: identifies the connector and restricts access to environments / version of TF API the connector is certified for (see below for token usage in header)
  • TFToConnectorToken: authorizes Trustfile to access operate the connector micro-service API
  • connectionId: identifies and authorizes access to the TF company to push data into. Mapped to a UUID Company Token in database

Connector Management API responsibility

  • Integrating with TF Items API
  • Integrating with host system API, including authorization (typically something like oAuth)
  • ETL of sales/refunds/tax/shipping data into TrustFile data model
  • Basic management of user data sources: CRUD, enable/disable/status
  • Scheduling and load balancing of users data synchronization
  • Data integrity. It is the responsibility of the connector micro-service to know what data has been processed by TrustFile.

Connector Management API is not responsible for

  • User experience
  • Branding of experience (aside from the popup for authentication with host system)

Hosting / Language

  • All connectors will be hosted and operated from the Heroku PaaS
  • Language: choose between - Ruby/Node/Java
  • DB: Postgres (on heroku)

Dates and Timestamps

  • Dates are in yyyy-mm-dd format
  • Timestamps are in the ISO format: 2015-07-06T22:26:28+00:00
  • Timestamps are in UTC +00:00 timezone

Configs

Put localization configs (specific to a given environment) into environment variables. Document the required variables in the README.md of the project. https://devcenter.heroku.com/articles/config-vars

Security:

API requests except orangez/health are authorized with Header param

Authorization: Bearer TFToConnectorToken

Get List of Connections

Returns list of connectionId's of the given enabled state

Api Endpoint
GET http://microservice.herokuapp.com/connections

Querystring Parameters

enabled

Enabled state of connections to retrieve. Default: true

boolean

Response

connections

Used to identify the connection in the micro-service API

Array[string]

Create a Connection

This will create a connection with the posted connectionId and startDate.

The connectionId is used to identify the connection in the micro-service API. It's also used to authorize access to a company when posting data to Trustfile.

The connector will synchronize all the Sales / Tax data starting from the startDate into TrustFile; then the connector will periodically synchronize this connection at least once a day

Api Endpoint
POST http://microservice.herokuapp.com/connections

Post Body Parameters

connectionId
Required

Used to identify the connection in the micro-service API

string
startDate
Required

The connector will synchronize all the Sales / Tax data starting from the startDate into TrustFile. Must be a Date parseable string

string

Response

connectionId
string
startDate

The connector will synchronize all the Sales / Tax data starting from the startDate into TrustFile. Must be a Date parseable string

string
enabled
boolean

Determine if Connection Exists

Api Endpoint
HEAD http://microservice.herokuapp.com/connections/{connectionId}

Path Parameters

connectionId
Required

Used to identify the connection in the micro-service API

string

Get a Connection

  • Returns the status and other information about the connection identified by 'connectionId'
  • Enabled connections will process data periodically if authorized
  • Authorized connections are authenticated with the host integration system (paypal, amazon..) and allowed to pull sales/tax data
  • The status message should be sufficient for the user to understand what state the connection is in and if there are any actions required of them to proceed.
  • The HostSystemIdentifier will be displayed to the user (if not null) in TF to identify which host account was used for this connector.
Api Endpoint
GET http://microservice.herokuapp.com/connections/{connectionId}

Path Parameters

connectionId
Required

Used to identify the connection in the micro-service API

string

Response

enabled
boolean
authorized
boolean
hostSystemIdentifier

The HostSystemIdentifier will be displayed to the user (if not null) in TF to identify which host account was used for this connector

string
startDate

The connector will synchronize all the Sales / Tax data starting from the startDate into TrustFile. Must be a Date parseable string

string
statusChangedAt
string
lastSyncAt
string
nextSyncAt
string
statusMessage

The status message should be sufficient for the user to understand what state the connection is in and if there are any actions required of them to proceed.

string

Update a Connection

Api Endpoint
PUT http://microservice.herokuapp.com/connections/{connectionId}

Path Parameters

connectionId
Required

Used to identify the connection in the micro-service API

string

Post Body Parameters

enabled

Setting to true enables the connection; false disables the connection

boolean
connectionId

Changes the ConnectionId

string
startDate

Changes the date from which to begin syncing data

string

Response

connectionId
string
startDate

The connector will synchronize all the Sales / Tax data starting from the startDate into TrustFile. Must be a Date parseable string

string
enabled
boolean

Delete a Connection

Deletes the connection from the database given the connectionId and stops syncing data from it

Api Endpoint
DELETE http://microservice.herokuapp.com/connections/{connectionId}

Path Parameters

connectionId
Required

ID of data source to be deleted

string

Response

success
boolean

Get Activity Logs for Connection

Returns a log of all activities up to a max of 365 days. The activity logs should be sufficient to help the user understand what's going on synchronizing their account with Trustfile

Api Endpoint
GET http://microservice.herokuapp.com/connections/{connectionId}/activities

Querystring Parameters

days

Days of activity history to retrieve. Trustfile may request up to 1 year of activity logs. Default: 14 days

string
limit

Number of activities to retrieve. Default: 100

string

Path Parameters

connectionId
Required

Used to identify the connection in the micro-service API. Also used to authorize access to a company when posting data to Trustfile

string

Response

Array[Activities]
timestamp
string
action
string

Authenticate with Connection

Redirects user to the connection authentication. Response will be rendered in a popup iframe to handle oAuth or other authentication mechanism. Once the user logs in or authorizes the connector, they will be redirected to the provided redirectUri, passing the TFToConnectorToken

Api Endpoint
GET http://microservice.herokuapp.com/connections/{connectionId}/authentication

Querystring Parameters

redirectUri
Required

URI to redirect to after authentication. Will be app.trustfile.avalara.com/connectors/success followed by a stringified query param 'id', where 'id' is the TFToConnectorToken: app.trustfile.avalara.com/connectors/success?id=TFToConnectorToken (before uri-encoding)

string

Path Parameters

connectionId
Required

Used to identify the connection in the micro-service API

string

Get Status of a Connector

Api Endpoint
GET http://microservice.herokuapp.com/connector

Response

enabled
boolean
userCount
integer

Enable/Disable Connector

Based on the 'enabled' query param, disables or enables the connector. When the connector is disabled, it stops synchronizing data with TrustFile until it is reenabled

Api Endpoint
PUT http://microservice.herokuapp.com/connector

Post Body Parameters

enabled
Required
boolean

Response

enabled
boolean
userCount
integer

Get Connector Errors

Api Endpoint
GET http://microservice.herokuapp.com/errors

Querystring Parameters

date

Retrieve errors occurring on or after this date. Default: retrieves all errors

string

Response

Errors
Array[Integration]
type
Required

Type will be "INTEGRATION"

string
timestamp
Required
string
message
Required
string
Array[Connection]
type
Required

Type will be "CONNECTION"

string
timestamp
Required
string
message
Required
string
Array[System]
type
Required

Type will be "SYSTEM"

string
timestamp
Required
string
message
Required
string

Retrieve Bad Items

The connector should identify items that it receives that do not match the schema required by TrustFile. These items are stored and can be retrieved through GET to this route

Api Endpoint
GET http://microservice.herokuapp.com/baditems

Querystring Parameters

date

Retrieve bad items errors occurring on or after this date. Default: retrieves all errors

string

Response

Array[Errors]
timestamp
Required
string
message
Required
string
connectionId

Used to identify the connection in the micro-service API. Also used to authorize access to a company when posting data to Trustfile

string
Array[BadItems]
itemId
string
transactionDate
string
ShipFromAddress
line1
Required
string
city
Required
string
state
Required
string
zip
Required
string
ShipToAddress
line1
Required
string
city
Required
string
state
Required
string
zip
Required
string
shippingAmount
number
shippingTax
number
salesAmount
number
salesTax
number
description
string
refund
boolean
friendlyMessage
string

Get Connector Health

  • Health check for connector, used for monitoring
  • Monitors verify all statuses report OK, or the health check will fail.
  • Will return an array of statuses of the three types:
    • connector
    • hostSystem
    • trustfile
  • Possible statuses are:
    • OK - nominal
    • FAIL - integration point is non-responsive or failing
    • DEGRADED - functional, but not functioning at full capacity
Api Endpoint
GET http://microservice.herokuapp.com/health

Response

Array[Statuses]
type
Required
string
status
Required
string
description
Required
string