CitrusLime.CloudPos.ApiClient 2.0.0

CitrusLime.CloudPos.ApiClient

Provides a C# wrapper for the Cloud POS REST API. This will handle Cloud POS API rate limiting and paging (e.g. if you make a request to get a list, the API will make the required paging calls to return a complete list).

External Links

• API Documentation

Releases

• Release 2.0.0
• Release 1.1.1
• Release 1.1.0
• Release 1.0.17
• Release 1.0.16
• Release 1.0.15
• Release 1.0.14
• Release 1.0.10

Release 2.0.0

Updated CitrusLime.Core.Rest dependency version to 3.0.0.

Added dependency for Newtonsoft.Json with a minimum version 13.0.2.

Release 1.1.1

Updated EnumTenderType to include OtherVoucher & Twint.

Release 1.1.0

Updated CitrusLime.Core.Rest package version to 2.0.2. This required a fairly large refactor, to remove now-obsolete classes.

Release 1.0.17

Initial release to NuGet.org.

Updated CitrusLime.Core.Rest package version to 1.0.14.

Release 1.0.16

Add support to the CloudPosPurchaseOrderService for two new fields AvailableForEcommercePreorders - This purchase order should be loaded as available stock with appropiate lead times onto any attached ecommerce site. IgnoreFromPurchaseOrderCalculations - The purchase should not be considered when reordering based on sales or min/max levels. Updated CitrusLime.Core.Rest package version to 1.0.13.

Release 1.0.15

GroupBillingType added to CloudPosGroupInformation. Update (Put) Inventory method implemented.

Release 1.0.14

Updated CitrusLime.Core.Rest package version to 1.0.12.

Added CloudPosNewsletterIntegrationInformation to the CloudPosGroupInformation model.

Release 1.0.10

Added purchase order service for getting a list of purchase order headers and a given purchase order (including lines) by order id.

Usage

Basics

The API Client contains multiple Services which each map to one of the controllers in the API. To create one or more of these services, you will first need to inject an IRestClientFactory instance into the service constructor, which is what provides the internal REST client for making the API calls. You will also need the API endpoint (https://cloudposapi.citruslime.com) and an API key that you or someone in your organization has set up - both of these will be passed into the service method calls.

Note: Each service has an associated interface to enable dependency injection patterns. The API Client package also contains an extension method in the Microsoft.Extensions.DependencyInjection namespace, which sets up a Microsoft.Extensions.DependencyInjection.IServiceCollection instance with the necessary services, interfaces and factories.

After this setup is complete, making API calls is as simple as calling a method on a service. For example, fetching a single customer by their ID:

    IRestClientFactory restClientFactory = new RestClientFactory(logger);
    ICloudPosCustomerService service = new CloudPosCustomerService(restClientFactory);
    
    CloudPosCustomerModel customer = service.GetCustomerById(apiEndpoint, apiKey, "Fast Bikes", customerId);

Here, we're creating the REST client factory, then the service using that factory, at which point the API call can be made. The service handles everything else; checking HTTP status codes, handling rate limiting, (de)serialization, and error logging. In addition, we are also passing in a string parameter (hardcoded as "Fast Bikes" for these examples) to this API call - this parameter is common to all API calls and is included in any error messages that the API returns, so you can use this parameter for identifying groups that are using the services.

Fetching a single item by it's lookup code is very similar:

    IRestClientFactory restClientFactory = new RestClientFactory(logger);
    ICloudPosItemService service = new CloudPosItemService(restClientFactory);
    
    CloudPosItemModel item = service.GetItemByItemLookupCode(apiEndpoint, apiKey, "Fast Bikes", itemLookupCode);

Timestamp Filtering

Most services also expose the ability to get objects by filtering on their timestamp. This is a number which increments to a new value after the object is updated within our system - the number it increments to is unique across all objects. As such, we can pass in a timestamp parameter to the services, which will then filter out any objects that have not been updated since the given timestamp. This can be very useful for keeping track of changes as they occur.

Note: Despite the name, a 'timestamp' has no relation to dates/times! The timestamp is merely a number that tracks the order of object inserts/updates in our database, and is not, for instance, a Unix Epoch time.

As an example of timestamp filtering, here we get a list of suppliers from an ICloudPosSupplierService and grab the supplier with the highest timestamp value:

    List<CloudPosSupplierModel> suppliers = service.GetSuppliers(apiEndpoint, apiKey, "Fast Bikes");
    CloudPosSupplierModel supplierWithLargestTimestamp = posSuppliers.OrderByDescending(s => s.TimeStamp).First();
    
    System.Console.WriteLine("Supplier ID: " + supplierWithLargestTimestamp.Uid);
    System.Console.WriteLine("Largest TimeStamp: " + supplierWithLargestTimestamp.TimeStamp);

    Supplier ID: 6781
    Largest TimeStamp: 64823301912

Then we can pass that timestamp value back into the service, which will only return the same single supplier with that timestamp:

    List<CloudPosSupplierModel> filteredSuppliers = service.GetSuppliersByTimestamp(apiEndpoint, apiKey, "Fast Bikes", supplierWithLargestTimestamp.TimeStamp);
    
    System.Console.WriteLine("Returned count of filtered suppliers: " + filteredSuppliers.Count);
    System.Console.WriteLine("Filtered supplier ID: " + filteredSuppliers[0].Uid);
    System.Console.WriteLine("Filtered supplier TimeStamp: " + filteredSuppliers[0].TimeStamp);

    Returned count of filtered suppliers: 1
    Filtered supplier ID: 6781
    Filtered supplier TimeStamp: 64823301912

And if a supplier is created or updated in any way, then it will have a timestamp greater than this value and so will be included in the returned results:

    List<CloudPosSupplierModel> updatedSuppliers = service.GetSuppliersByTimestamp(apiEndpoint, apiKey, "Fast Bikes", supplierWithLargestTimestamp.TimeStamp);

    System.Console.WriteLine("Returned count of updated suppliers: " + updatedSuppliers.Count);

    Returned count of updated suppliers: 2