What Is A Web Endpoint - And How Does It Work?

Applicability
Deploying a web endpoint allows automated import of transactions from any sales or accounting system. You should deploy a web endpoint when:

• You want to automate transaction upload (so as to avoid manual uploads)
• Your sales transactions are not in such as QuickBooks, HubSpot, SalesForce, Stripe, Chargebee, Xero, Dynamics, etc. (we have a native connector for those)
• You do not want to use the Zapier integration
• You do not want to use a push model (you are looking for a pull model)

Overview
Web endpoints are implemented by you. They are implemented as a single web page. They enable secure automatic upload of sales transactions from any sales or accounting system (even those only available within your intranet).

To deploy a web endpoint, you need a developer (or development team) to implement the web page. In most cases, the implementation of your web page can be accomplished within hours, eliminating all future needs to manually import sales transactions. You don't need to learn another API or run a background job.

Web endpoints have been designed to:

• Be trivial to implement
• Never miss a record at the source
• Enable reliable change detection
• Scale to millions of transactions

This diagram shows an overview of interactions:

Implementation

In order to implement a working web endpoint as a simple web page, you must:

• Ensure your web page's URL is publicly-accessible from the internet
  
• Handle GET requests from SalesCookie
  
• Check that the received HTTP header "X-Secret" matches the secret you specified in SalesCookie
  
• Extract parameters "count" and "date" from the URL's query string
  
• Example of "count": 30
  
• Example of "date": 2018-08-06T03:31:24.0277712Z
  
• All values are URL-encoded
  
• The ending Z indicates that the date is in UTC / GMT
  
• Connect to your sales system
  
• Identify the property tracking each transaction's update date
  
• We will refer to it as <record change date> below
  
• Retrieve from your sales systems those transactions:
  
• Whose <record change date> is greater or equal to the received "date"
  
• Sorted by ascending (oldest first) <record change date>
  
• Not more than the specified "count"
  
• Return an array of JSON objects
  
• One JSON object per transaction
  
• Your object can have properties
  
• Use simple values such as strings, numbers, etc.
  
• Always include a property on each object called "syncDate", set to the <record change date>
  
• Make sure returned dates are in the UTC / GMT time zone
  
• You can return dates using the:
  
• Microsoft JSON epoch format: ex: "/Date(1541079930000)/"
  
• The ISO 8601 standard format: ex: "2018-11-01T13:45:30.0000000Z"
  
• Your JSON library may automatically choose one of those for you
  

Sample Response

Here is an example of a valid basic JSON response returned by a Web Endpoint web page:

[{"transactionId":0,"syncDate":"\\/Date(946684800000)\\/","transactionCredit":"James Cookie","transactionValue":0},{"transactionId":1,"syncDate":"\\/Date(946684801000)\\/","transactionCredit":"James Cookie","transactionValue":1}, ...]

An alternative dictionary-based format is also supported:
[[{"Key":"syncDate","Value":"\\/Date(1517304120000)\\/"},{"Key":"Date","Value":"\\/Date(1517304120000)\\/"},{"Key":"Unique ID","Value":"2948383"},{"Key":"Sold By","Value":"jamescookie@example.com"},{"Key":"Total","Value":"$207.15 "},{"Key":"Taxes","Value":"$12.01 "},{"Key":"Type","Value":"Sell"},{"Key":"Product","Value":"Lemon Cookies"},{"Key":"Customer","Value":"The Pastry Corp."},{"Key":"Quantity","Value":"10"}],...]

Note that field names can be chosen by you. Make sure to provide the syncDate field, however. 

Push Vs. Pull API

Some of our customers ask for an API they can call to add or update sales transactions to Sales Cookie. We offer many push-based APIs. At the same time, the Web Endpoint pull approach offers several benefits as compared to the push approach:

• You don't need to implement a background worker
  
• Sales Cookie is responsible for calling your web page
  
• You don't need to learn yet another API
  
• Simply implement a web page and return JSON objects using your field names
  
• It's impossible for Sales Cookie to miss a change
  
• No need to implement API POST retries on your end
  
• It's a secure protocol
  
• Provided access is narrow, and you can revoke access any time
  

• Related Articles

• How Do Custom Variables Work?

  Custom variables (also known as custom properties) help you define values which change over time. Custom variables are essential to Sales Cookie's ability to calculate commissions en-masse. Custom variables also help you manage various ...

• How Can I Add A Connection?

  Here are the steps to create a new connection: Login to your workspace On the left pane, click on "Systems > Connections" Select the type of connection you want to add Follow the instructions on the page for the type of connection Here is a brief ...

• What Is A Connection?

  Connections help you import users and sales transactions from various sales or accounting systems. The import can be one-time, or fully automated. Connections include: CRM connections We provide native support for systems such as QuickBooks, HubSpot, ...

• How Can I Import Transactions?

  For programmatic import options, click here. You can use the following methods to add transactions: Manually or automatically from CSV files Manually upload CSV files containing sales transactions Automatically by having us fetch CSV files from FTP ...

• What Are Some Pre-Requisites For Using Sales Cookie?

  There are no pre-requisites to using Sales Cookie. We do NOT require any of the following: Provisioning servers Setting up new permissions in your environment Purchasing additional software / hardware Providing a credit card at sign up You can start ...