Skip to main content

C# / .NET SDK

The Staqr C# SDK provides .NET Standard 2.0+ support with RestSharp client for cross-platform compatibility.

Installation​

NuGet​

# Staqr Platform API
dotnet add package Staqr.ApiClient --version 1.0.0

# Commerce APIs
dotnet add package Staqr.Commerce.V1 --version 13.3.0  # Recommended
dotnet add package Staqr.Commerce.V2 --version 13.3.0  # Generic CRUD
dotnet add package Staqr.Commerce.V0 --version 13.3.0  # Legacy

Package Manager​

Install-Package Staqr.ApiClient -Version 1.0.0
Install-Package Staqr.Commerce.V1 -Version 13.3.0

From Local SDK​

<ItemGroup>
    <Reference Include="Staqr.ApiClient">
        <HintPath>.\sdks\staqr-csharp\bin\Release\netstandard2.0\Staqr.ApiClient.dll</HintPath>
    </Reference>
</ItemGroup>

Quick Start​

using Staqr.ApiClient.Api;
using Staqr.ApiClient.Client;
using Staqr.ApiClient.Model;

// Configure the client
var config = new Configuration
{
    BasePath = "https://my.staqr.com/api/v1",
    AccessToken = Environment.GetEnvironmentVariable("STAQR_API_KEY")
};
config.DefaultHeaders.Add("x-seller-id", Environment.GetEnvironmentVariable("STAQR_SELLER_ID"));

// Create API instance
var flowsApi = new FlowsApi(config);

// List flows
var flows = await flowsApi.ListFlowsAsync();
foreach (var flow in flows)
{
    Console.WriteLine($"Flow: {flow.DisplayName}");
}

Authentication​

API Key Authentication​

using Staqr.ApiClient.Client;

var config = new Configuration
{
    BasePath = "https://my.staqr.com/api/v1",
    AccessToken = Environment.GetEnvironmentVariable("STAQR_API_KEY")
};
config.DefaultHeaders.Add("x-seller-id", Environment.GetEnvironmentVariable("STAQR_SELLER_ID"));

OAuth2 (Commerce APIs)​

using Staqr.Commerce.V1.Client;

// For Commerce Direct access (Keycloak OAuth2)
var config = new Configuration
{
    BasePath = "https://commerce.staqr.com/api",
    AccessToken = commerceOAuthToken
};
config.DefaultHeaders.Add("X-Tenant", "YOUR_TENANT_CODE");

Available Packages​

NuGet PackageAPIInstall Command
Staqr.ApiClientStaqr Platformdotnet add package Staqr.ApiClient
Staqr.Commerce.V1Commerce v1 (Structured)dotnet add package Staqr.Commerce.V1
Staqr.Commerce.V2Commerce v2 (Generic CRUD)dotnet add package Staqr.Commerce.V2
Staqr.Commerce.V0Commerce v0 (Legacy)dotnet add package Staqr.Commerce.V0

Common Operations​

Working with Customers (Commerce)​

using Staqr.Commerce.V1.Api;
using Staqr.Commerce.V1.Model;

var customerApi = new CustomerManagementApi(config);

// List customers
var customers = await customerApi.ListCustomersAsync();

// Get customer by code
var customer = await customerApi.GetCustomerByCodeAsync("CUST001");

// Create customer
var newCustomer = new CustomerDto
{
    Code = "CUST002",
    Description = "New Customer"
};
await customerApi.CreateCustomerAsync(newCustomer);

Error Handling​

using Staqr.ApiClient.Client;

try
{
    var flow = await flowsApi.GetFlowAsync("invalid-id");
}
catch (ApiException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.ErrorCode}");
    Console.WriteLine($"Response Body: {ex.ErrorContent}");
}

ASP.NET Core Integration​

Service Registration​

// Program.cs
using Staqr.ApiClient.Api;
using Staqr.ApiClient.Client;

var builder = WebApplication.CreateBuilder(args);

// Register Staqr SDK
builder.Services.AddSingleton<Configuration>(sp =>
{
    var config = new Configuration
    {
        BasePath = builder.Configuration["Staqr:ApiUrl"],
        AccessToken = builder.Configuration["Staqr:ApiToken"]
    };
    config.DefaultHeaders.Add("x-seller-id", builder.Configuration["Staqr:SellerId"]);
    return config;
});

builder.Services.AddScoped<IFlowsApi, FlowsApi>();
builder.Services.AddScoped<IConnectionsApi, ConnectionsApi>();

var app = builder.Build();

Controller Usage​

using Microsoft.AspNetCore.Mvc;
using Staqr.ApiClient.Api;
using Staqr.ApiClient.Model;

[ApiController]
[Route("api/[controller]")]
public class FlowsController : ControllerBase
{
    private readonly IFlowsApi _flowsApi;

    public FlowsController(IFlowsApi flowsApi)
    {
        _flowsApi = flowsApi;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<Flow>>> GetFlows()
    {
        var flows = await _flowsApi.ListFlowsAsync();
        return Ok(flows);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Flow>> GetFlow(string id)
    {
        try
        {
            var flow = await _flowsApi.GetFlowAsync(id);
            return Ok(flow);
        }
        catch (ApiException ex) when (ex.ErrorCode == 404)
        {
            return NotFound();
        }
    }
}

Configuration​

// appsettings.json
{
  "Staqr": {
    "ApiUrl": "https://my.staqr.com/api/v1",
    "ApiToken": "",
    "SellerId": ""
  }
}
// appsettings.Development.json (with user secrets)
{
  "Staqr": {
    "ApiToken": "your-api-token-here",
    "SellerId": "your-seller-id"
  }
}

.NET Requirements​

  • .NET 6.0+ (recommended)
  • .NET Standard 2.0+ (for library compatibility)
  • .NET Framework 4.6.1+ (legacy support)

Dependencies​

The SDK uses:

  • RestSharp for HTTP client
  • Newtonsoft.Json for JSON serialization
  • System.ComponentModel.DataAnnotations for validation

Examples​

See the examples directory for complete usage examples:

  • Console application
  • ASP.NET Core Web API
  • Worker Service
  • Blazor integration
  • Error handling patterns

API Reference​

For complete API documentation, see:

Troubleshooting​

SSL Certificate Issues​

// Development only!
ServicePointManager.ServerCertificateValidationCallback =
    (sender, cert, chain, errors) => true;

Timeout Configuration​

var config = new Configuration
{
    BasePath = "https://my.staqr.com/api/v1",
    Timeout = 30000  // 30 seconds
};

Retry Policy with Polly​

using Polly;
using Polly.Retry;

var retryPolicy = Policy
    .Handle<ApiException>(ex => ex.ErrorCode >= 500)
    .WaitAndRetryAsync(3, retryAttempt =>
        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

var flows = await retryPolicy.ExecuteAsync(() =>
    flowsApi.ListFlowsAsync());