Certify.Api 1.2.23

Certify.Api

A modern .NET client library for the Certify Expense Management API, built with .NET 10 and C# 14.

Features

• ?? Full .NET 10 Support - Built with the latest .NET features and C# 14 syntax
• ?? Complete API Coverage - Full support for Certify REST API v1
• ?? Strongly-Typed - All models include comprehensive XML documentation
• ? Async/Await - Modern async patterns with CancellationToken support
• ?? Built on Refit - Leveraging Refit for maintainable HTTP clients
• ?? Debugging Support - Symbol packages (.snupkg) included for source-level debugging
• ?? Structured Logging - Integrated Microsoft.Extensions.Logging support
• ?? Nullable Reference Types - Full nullable annotations for better null-safety

Installation

Install via NuGet Package Manager:

Install-Package Certify.Api

Or via .NET CLI:

dotnet add package Certify.Api

Quick Start

using Certify.Api;

// Initialize the client with your API credentials
using var client = new CertifyClient(
    apiKey: "your-api-key",
    apiSecret: "your-api-secret"
);

// Get a page of users
var users = await client.Users.GetPageAsync(cancellationToken: cancellationToken);

// Get all expense reports
var expenseReports = await client.ExpenseReports.GetAllAsync(cancellationToken: cancellationToken);

// Get a specific department by ID
var department = await client.Departments.GetAsync(departmentId, cancellationToken: cancellationToken);

Configuration Options

Customize the client behavior using CertifyClientOptions:

using Microsoft.Extensions.Logging;

var options = new CertifyClientOptions
{
    Timeout = TimeSpan.FromSeconds(60), // Default is 120 seconds
    Logger = loggerInstance // Optional: add structured logging
};

using var client = new CertifyClient(apiKey, apiSecret, options);

Logging Support

The library supports Microsoft.Extensions.Logging for detailed request/response logging:

using Microsoft.Extensions.Logging;

// Create a logger factory
using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddConsole()
        .SetMinimumLevel(LogLevel.Debug);
});

var logger = loggerFactory.CreateLogger<CertifyClient>();

var options = new CertifyClientOptions
{
    Logger = logger
};

using var client = new CertifyClient(apiKey, apiSecret, options);

Supported Endpoints

The library provides full support for all Certify API endpoints:

Advanced Usage

Pagination

Get all items across multiple pages:

// Extension method automatically handles pagination
var allUsers = await client.Users.GetAllAsync(cancellationToken: cancellationToken);

// Or manually page through results
uint pageNumber = 1;
var page = await client.Users.GetPageAsync(page: pageNumber, cancellationToken: cancellationToken);

Console.WriteLine($"Page {page.PageNumber} of {page.TotalPageCount}");
Console.WriteLine($"Total records: {page.TotalRecordCount}");

Filtering

Most endpoints support filtering parameters:

// Get active users only
var activeUsers = await client.Users.GetPageAsync(
    active: 1,
    cancellationToken: cancellationToken
);

// Get expense reports by date range
var reports = await client.ExpenseReports.GetPageAsync(
    startDate: "2024-01-01",
    endDate: "2024-12-31",
    processed: 1,
    cancellationToken: cancellationToken
);

// Get departments by code
var departments = await client.Departments.GetPageAsync(
    code: "DEPT001",
    cancellationToken: cancellationToken
);

Creating and Updating Resources

// Create a new department
var newDepartment = new Department
{
    Name = "Engineering",
    Code = "ENG",
    Description = "Engineering Department"
};

var createResult = await client.Departments.CreateAsync(
    newDepartment,
    cancellationToken: cancellationToken
);

Console.WriteLine($"Created department with ID: {createResult.Id}");

// Update an existing department
var department = new Department
{
    Id = existingDepartmentId,
    Name = "Updated Name"
};

var updateResults = await client.Departments.UpdateAsync(
    department,
    cancellationToken: cancellationToken
);

foreach (var result in updateResults)
{
    Console.WriteLine($"Status: {result.Status}, Message: {result.Message}");
}

Error Handling

using Refit;

try
{
    var users = await client.Users.GetPageAsync(cancellationToken: cancellationToken);
}
catch (ApiException ex)
{
    // Handle API errors
    Console.WriteLine($"API Error: {ex.StatusCode} - {ex.Content}");
}
catch (TaskCanceledException)
{
    // Handle timeout or cancellation
    Console.WriteLine("Request timed out or was cancelled");
}
catch (Exception ex)
{
    // Handle other errors
    Console.WriteLine($"Error: {ex.Message}");
}

Using with Dependency Injection

using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// Register as singleton or scoped based on your needs
services.AddSingleton<CertifyClient>(sp =>
{
    var logger = sp.GetRequiredService<ILogger<CertifyClient>>();
    var options = new CertifyClientOptions
    {
        Timeout = TimeSpan.FromSeconds(120),
        Logger = logger
    };
    
    return new CertifyClient(
        apiKey: "your-api-key",
        apiSecret: "your-api-secret",
        options: options
    );
});

var serviceProvider = services.BuildServiceProvider();
var certifyClient = serviceProvider.GetRequiredService<CertifyClient>();

API Documentation

For detailed information about the Certify API endpoints and parameters, refer to the official Certify API Documentation.

Requirements

• .NET 10 or higher (recommended)
• .NET 5+ (compatible via .NET Standard 2.0)
• .NET Core 2.0+ (compatible via .NET Standard 2.0)
• .NET Framework 4.6.1+ (compatible via .NET Standard 2.0)

Dependencies

• Refit 8.0.0 - The automatic type-safe REST library
• Microsoft.Extensions.Logging.Abstractions - Logging abstractions
• Nerdbank.GitVersioning - Automatic version management from Git

Building from Source

# Clone the repository
git clone https://github.com/panoramicdata/Certify.Api.git
cd Certify.Api

# Restore dependencies
dotnet restore

# Build the solution
dotnet build

# Run tests (requires appsettings.json with valid credentials)
dotnet test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Testing

The test suite uses xUnit and requires valid Certify API credentials. Create an appsettings.json file in the test project:

{
  "Config": {
    "Credentials": {
      "ApiKey": "your-api-key",
      "ApiSecret": "your-api-secret"
    }
  }
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• David Bond - Panoramic Data Limited
• Daniel Abbatt - Panoramic Data Limited

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Acknowledgments

• Built with Refit
• Uses Microsoft.Extensions.Logging
• Versioned with Nerdbank.GitVersioning

Copyright � 2019-2025 Panoramic Data Limited