CitrusLime.CloudPos.ApiClient 2.0.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package CitrusLime.CloudPos.ApiClient --version 2.0.0
NuGet\Install-Package CitrusLime.CloudPos.ApiClient -Version 2.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CitrusLime.CloudPos.ApiClient" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CitrusLime.CloudPos.ApiClient --version 2.0.0
#r "nuget: CitrusLime.CloudPos.ApiClient, 2.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install CitrusLime.CloudPos.ApiClient as a Cake Addin
#addin nuget:?package=CitrusLime.CloudPos.ApiClient&version=2.0.0

// Install CitrusLime.CloudPos.ApiClient as a Cake Tool
#tool nuget:?package=CitrusLime.CloudPos.ApiClient&version=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).



Releases

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
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.