Generic POS API
      Back to home
      1. Help Center
      2. API
      3. Generic POS API

      Implementation guidelines for the Generic POS API

      You're a point of sale provider and you'd like to integrate with Apicbase? Keep the guidelines below in the back of your mind while developing.

      This is a set of requirements that integrations built by partner POS providers should meet before they can be granted access to customer libraries. These guidelines define a standard of quality that meets our customers' expectations for the reliability of the connection between their accounts and their POS systems. If all points are satisfied, we can ensure that your solution is fully compatible with Apicbase.

      The completeness of your solution will be assessed by our integrations team. Having your integration be validated opens up possibilities for marketing and other types of partnerships.

       General:

        • The application should NOT use any endpoints outside of the Sales scope to create entities such as Recipes, Ingredients or Menus.
        • IF the application receives an error response from the Apicbase API at the moment of uploading either product or sales data, THEN the application must communicate clearly via the POS system’s user interface that an error occurred when connecting to Apicbase.
        • The application should be able to refresh expired access tokens without the need for manual user intervention.
        • The application should NOT refresh their access tokens before every API request. Refresh token requests must be kept under a reasonable limit (recommended: catch 401 Unauthorized error responses from the Apicbase API, refresh the access token and re-try the same request).

      Product Catalogue:

        • The application should only upload POS items and categories via the POST /analytics/generic_pos/group_items/ endpoint.
        • The application should upload all categories, items and modifiers at a single outlet in bulk, with one API request.
        • The application should NOT use PUT /analytics/generic_pos/product/ endpoint to create or update multiple items. Use of this method should be reserved to minor updates for a single item.
        • The application should keep the product catalogues in Apicbase and the POS system in sync by performing periodic and automatic requests to the POST /analytics/generic_pos/group_items/ endpoint with the updated product catalogue.
        • IF, due to technical limitations, it is not possible for the application to periodically upload the product catalogue to Apicbase, THEN it must perform such a sync without user intervention before uploading sales data.

      Sales:

        • The application should upload tickets to the /analytics/generic_pos/sales/ endpoint automatically, without the need for manual user intervention.
        • IF the application periodically uploads tickets in bulk, THEN it should perform a periodic upload at least daily.
        • IF the application automatically uploads tickets when they are created/closed/paid, THEN it must do so with no impact to the functionality of the POS system, especially in cases where the Apicbase API returns an error response or when the response is delayed.
        • The application should upload sales data chronologically, from the oldest ticket to the newest.
        • The application should NOT automatically upload tickets from an earlier date than a ticket that has already been uploaded to Apicbase.
        • IF an event happens that prevents the application from uploading sales data for an extended period of time, THEN, as soon as the issue is resolved, the application should automatically upload all tickets from the missed period. The application should NOT upload any newer tickets until the issue has been resolved.
        • The application should attempt to resolve errors of the “Group not found” or “Product not found” type by uploading an updated version of the product catalogue, or by creating the missing product referenced by the error message with a PUT request, and then re-trying to upload the same request.

      If your integration is complete and functional, reach out to api_support@apicbase.com to schedule a quality assurance call. If everything looks good, we will guide you through the next steps of the partnership and release your application to customer libraries.

      Cheers!