NCR Counterpoint API

The NCR Counterpoint API is a REST API server designed to be hosted on premises or in the cloud. It is built in pure .NET (C#) using the ServiceStack framework and uses basic authentication using existing NCR Counterpoint user credentials. Some key features of the API are:

• Independent from Counterpoint code: The API has no runtime dependencies on Counterpoint, and thus can be installed on a non-Counterpoint machine. This also allows flexibility in forward and backward compatibility and ensures that API upgrades aren't dependent on Counterpoint upgrades.
• Multi-company capable: The API server can connect to multiple independent NCR Counterpoint companies from the same and or separate installs. As long as the API server has connectivity to a Counterpoint system, it can work with it.
• Multi-version capable: The API server is designed to work with multiple versions of Counterpoint systems simultaneously. The same server instance can work with an 8.4.6.12 company and an 8.5.0 company. The API server determines the version of Counterpoint its connected to by querying DB_CTL.DB_VER from the Counterpoint database, and executes the proper set of business rules for the target version of Counterpoint.
• Lightweight, simple, and performant: As much as possible, we hope to keep the API server small, simple, and high performance. As with any software, it will grow as functionality grows, but key design goals are simplicity and performance.

Release Notes

• Version 2.0

Requirements

Any instance of the NCR Counterpoint API server can connect to multiple NCR Counterpoint installations and companies. In order for the server to work against an NCR Counterpoint company, the following requirements must be met:

• Windows 7 (desktop OS) or Windows Server 2012 R2 (server OS) or newer.
• .NET 4.5.2
• 4GB RAM Minimum (8GB recommended)
• The NCR Counterpoint API server must be installed and running on an open http port.
• The NCR Counterpoint API server must have read/write access to the TLD folder for the company. This can be on a separate machine accessible via a UNC path.
• The NCR Counterpoint API server must have administrative access to the company database.
• The NCR Counterpoint API does not support offline databases.
• The company the server is connecting to must have the API user option enabled in its registration.ini file. There are some limited functions that will work without the API user option, but the bulk of the endpoints do require the registration option. See the documentation for an individual endpoint to determine if it requires the registration.ini option for use.
• Most API calls require that client applications or scripts provide a valid "APIKey" header in each request. This APIKey must also be installed on the API Server. See the page on APIKeys for more information. There are some limited functions that will work without an API Key, but the bulk of the endpoints do require an API Key to be provided. See the documentation for an individual endpoint to determine if it requires an APIKey for use.

Supported Counterpoint versions

Version 2.0 of the NCR Counterpoint API is tested and supported with the following Counterpoint verions:

• V8.4.6.18
• V8.5.2.1
• V8.5.3

Please note that the API relies on the database version value in DB_CTL.DB_VER for versioning information, and thus it cannot distinguish between multiple Counteproint versions that share a given value for DB_CTL.DB_VER. There are also no restrictions preventing the API from working with some other versions of Counterpoint Databases. It's very likely that the Counterpoint API will work with other versions of Counterpoint, but the versions listed above are the only versions that the API has been fully tested and is supported on. If there is sufficient demand for support of additional versions, then the scope of supported Counterpoint versions may be expanded.

Installation

Installation of the API Server is simple, you essentially just run the .exe to install. See the Installing page for more details.

Configuration and Administration

The API server allows fine grained configuring over the companies, users, and API calls each user can make. See the Configuring the NCR Counterpoint API Server page for information on how to configure the server properly for your environment.

API Keys and licensing

Most, but not all calls to the API will require a free API License key (for the client application or script), and a paid registration.ini option for the Counterpoint merchant. The endpoint chart below indicates which endpoints require each piece of data. See the API Keys and licensing page for more details.

Card on file tokenization

The API has endpoints that can be used to replace card on file records with tokens from Secure Pay, as well as a web UI to allow for easy conversion of card on file data. Details can be found here.

Functionality and Testing

Automated testing is used to validate the operation and accuracy of the API calls. It is highly recommended that consumers of the API review the automated tests to ensure the API provides the needed capabilities. In short, if it's not covered by our automated tests, there's no guarantee that a given usage of the API will continue to work as expected.

Reporting defects

To report a defect in the API, an automated test that illustrates the defect, using Postman, is required to be submitted as a pull request to our API Tests project. The test should follow the structure of the other tests in the repository as closely as possible. Hardcoded values may be used if needed. NCR will use your test case to reproduce the issue. If NCR deems the issue to be a defect, it will be resolved and the test will be added to our test suites (the test may be modified to better fit our structure, etc.). This method ensures we build a robust automated test suite, and ensures that your needed functionality is always tested and ensured to work in future releases of the API.

In addition, if there is a usage of the API that is working as expected, but not yet covered by an automated test, and you want to ensure it continues to work as expected, you should submit a pull request with an automated test case for us to consider including in the test suite.

We use and recommend the Postman (Packaged app). It's a chrome web app that allows creating and saving REST requests. We also recommend the "Jetpacks" addon, which is very affordable and allows automated test scripting. These tools are required to create and submit additional test cases to NCR.

You can find all the automated tests we run for the API here. They are written to run against a standard Counterpoint test database and TLD (coming soon). The tests are published not only as reference examples of API usage, but also in hopes the community will contribute to the test cases as well, to help reproduce bugs and improve test coverage. The preferable way to get an improvement to tests or documentation is for users to submit pull requests containing tests to illustrate issues or provide new test coverage. Please submit tests that will work against the standard test database and are structured similarly to our existing conventions. Test databases can be downloaded via ftp from:

files165.cyberlynk.net

Using credentials provided from NCR.

Making http requests

Calls to the API Server are made in the form of http requests. See the page on API requests for specifics on how to form http requests for the NCR Counterpoint API. See documentation on the language or script being used to make the request for details on how to properly create the request in your code.

Working with http responses

Calls to the API Server issue http responses similarly to other REST APIs. See the page on API responses for specifics on how to work with http responses. See documentation on the language or script being used to handle the response for details on how to properly work with the response in your code.

Endpoints

The endpoints below each represent individual REST API calls/requests that the API server supports. Each endpoint is either for system administrative functions or company functions, as categorized below. System administrative functions require a system username and password to be included in the Authorization header, while company functions require a counterpoint username (with a company prefix: .) and password to be submitted in the authorization header.

System Administration Endpoints

Endpoint	Operation (Verb)	APIKey	CP Registration	Description
/AdminUsers	GET		X	Gets a list of admins for the API.
/AdminUser/{UserId}	DELETE			Deletes the provided administrator.
/APIKey	GET			Gets information on a single API Key.
/APIKey	POST			Post a new APIKey file and updates the APIKey cache.
/APIKeys	GET			Gets a list of all API Keys installed on the server.
/CompanyAdmin/{CompanyName}/{AdminUser}	DELETE			Delete a company admin by user id.
CompanyAdmins/{CompanyName}	GET			Gets a list of Company Admins for the company.
CompanyAdmins/{CompanyName}	POST			Adds a list of Company Admins.
CompanyAdmins/{CompanyName}	PUT			Sets a list of Company Admins for the company.
/Database/{Id}	GET			Gets information about a Database (Company) configured for use by the API Server.
/Database/{Id}	PUT			Updates information about a Database (Company) configured for use by the API Server.
/Database/{Id}	DELETE			Deletes a Database (Company) so it can no longer be used by the API Server.
/Databases	GET			Gets a list of all Databases (Companies) the API is able to interact with.
/Databases	POST			Adds one or more Databases (Companies) the API can interact with.
/Databases/ini	GET			Gets a list of company DB information from a companies.ini file
/SystemInfo	GET			Gets information about the API server and hardware environment.

Company Endpoints

Endpoint	Operation (Verb)	APIKey	CP Registration	Description
/Company	GET	X	X	Gets information about the given company (from SY_COMP & DB_CTL).
/Customer	POST	X	X	Adds a new customer record.
/Customer/{CustNo}	GET	X	X	Gets information about a customer.
/Customer/{CustNo}	PATCH	X	X	Updates information about a customer.
/Customer/{CustNo}/Address	POST	X	X	Adds a new shipping address to an existing customer.
/Customer/{CustNo}/Address	PATCH	X	X	Updates an existing shipping address for an existing customer.
/Customer/{CustNo}/Address	DELETE	X	X	Deletes a shipping address from an existing customer.
/Customer/{CustNo}/Card	POST	X	X	Adds a credit card on file to an existing customer.
/Customer/{CustNo}/Card	PATCH	X	X	Updates an existing credit card on file for an existing customer.
/Customer/{CustNo}/Card	DELETE	X	X	Deletes a credit card on file for an existing customer.
/Customer/{CustNo}/Note	POST	X	X	Adds a new note to an existing customer.
/Customer/{CustNo}/Note	PATCH	X	X	Updates an existing note on an existing customer.
/Customer/{CustNo}/Note	DELETE	X	X	Deletes a note from an existing customer.
/Customer/{CustNo}/OpenItems	GET	X	X	Gets customer AR Open Item information.
/CustomerControl	GET	X	X	Gets customer control information.
/Customers	GET	X	X	Gets information on customers in bulk.
/Customers/EC	GET	X	X	Gets information on eCommerce customers in bulk.
/Document	POST	X	X	Adds a new document (ticket).
/Document/{DocId}	GET	X	X	Gets information on an existing document (ticket) that hasn't been posted yet.
/Document/{DocId}/Contact	POST	X	X	Adds a contact to an existing document.
/Document/{DocId}/Contact	PATCH	X	X	Updates a contact on an existing document.
/Document/{DocId}/Contact	DELETE	X	X	Deletes a contact from an existing document.
/Document/{DocId}/Lines	POST	X	X	Adds Lines to a document.
/Document/{DocId}/Note	POST	X	X	Adds a note to an existing document.
/Document/{DocId}/Note	PATCH	X	X	Updates a note on an existing document.
/Document/{DocId}/Note	DELETE	X	X	Deletes a note from an existing document.
/Document/{DocId}/Payments	POST	X	X	Adds Payments to a document.
/EC	GET	X	X	Gets eCommerce settings.
/ECCategories	GET	X	X	Gets eCommerce Categories and items.
/GiftCard/{GiftCardNo}	GET	X	X	Gets gift card information.
/GiftCardCode/{GiftCardCode}	GET	X	X	Gets gift card code information.
/GiftCardCodes	GET	X	X	Gets information on gift card codes in bulk.
/GiftCards	GET	X	X	Gets information of Gift Cards in bulk.
/Inventory/{LocId}	GET	X	X	Gets inventory information for all items for a given location. Can be filtered further by category or subcategory
/InventoryControl	GET	X	X	Gets inventory control information.
/Inventory/EC	GET	X	X	Gets eCommerce inventory information for all eCommerce items.
/Item/Images/{Filename}	GET	X	X	Gets an item image for the given item and filename.
/Item/{ItemNo}	GET	X	X	Methods to get item and item inventory information.
/Item/{ItemNo}/Images	GET	X	X	Gets a list of available item images for a given item.
/Item/{ItemNo}/Inventory/{LocId}	GET	X	X	Gets item inventory information for a given item and location.
/Item/{ItemNo}/InventoryCost/{LocId}	GET	X	X	Gets item inventory information for a given item and location.
/Item/{ItemNo}/Serial/{SerialNo}	GET	X		Gets serial information for the given item & serial number.
/Item/{ItemNo}/Serials/Location/{LocId}	GET	X		Gets serials that are active for the given item at the given location.
/ItemCategories	GET	X	X	Gets item Categories in bulk.
/ItemCategory/{CategoryCode}	GET	X	X	Gets item category information for the given category code.
/Items	GET	X	X	Gets item information in bulk. Can be further filtered by category or subcategory.
/Items/{LocId}	GET	X	X	Gets item information for a given location in bulk. Can be further filtered by category or subcategory.
/NSPTransaction	POST			POSTs a list of secure pay transactions from Monetra to the db.
/PayCode/{Paycode}	GET	X	X	Gets information about a given Paycode.
/PayCode/{Paycode}	PATCH	X	X	Updates information about a Paycode.
/PayCodes	GET	X	X	Gets information on Paycodes in bulk.
/Role/Endpoints	GET			Gets a list of endpoints that can be made available to any role.
/Role/{RoleName}	DELETE			Delete a role.
/Role/{RoleName}	GET			Gets endpoint information for a role.
/Role/{RoleName}	PUT			Update or insert a role.
/Role/{RoleName}/Users	GET			Gets a list of users assigned to the role.
/Role/{RoleName}/Users	PUT			Add or update the users list belonging to the role.
/Roles	GET			Gets a list of roles with endpoint data.
/Roles/Names	GET			Gets a list of role names.
/Roles/Users	GET			Gets a list of all roles with permissions and assigned users.
/Store/{StoreID}	GET	X	X	Gets information on a store.
/Store/{StoreID}/Station/{StationID}	GET	X	X	Gets information on a station.
/Store/{StoreId}/Tokenize	POST		X	Tokenizes the cards for the store.
/Store/{StoreId}/Tokenize	GET		X	Gets tokenization information for the store.
/Stores/Tokenized	GET		X	Gets the tokenized count of customer cards on file for each secure pay store.
/TaxCodes	GET	X	X	Gets information on Tax Codes.
/User/Admin	POST		X	Adds a new sysadmin user.
/User/Password	PUT			Updates the authenticated user's password.
/User/{UserID}	GET	X	X	Gets information on a User.
/User/{UserID}/Roles	DELETE			Deletes a user's assigned roles.
/User/{UserID}/Roles	GET			Get a list of roles for the user.
/User/{UserID}/Roles	PUT			Update a user's assigned roles.
/Users	GET			Gets a list of users.
/Users/{CompanyName}	GET			Gets a list of users for the company.
/Users/Roles	GET			Get a list of users and their assigned roles.
/VendorItem/{VendorNo}/Item/{ItemNo}	GET	X	X	Retrieves information about Vendor Item.
/Workgroup/{WorkgroupID}	GET	X	X	Gets workgroup information.