Cardify.Sdk 1.0.0

Cardify .NET SDK

Official .NET SDK for the Cardify API - A powerful library for creating and managing cards with REST API integration.

Installation

Via NuGet Package Manager

dotnet add package Cardify.Sdk

Via Package Manager Console

Install-Package Cardify.Sdk

Quick Start

Basic Setup

using Cardify.Sdk;
using Cardify.Sdk.Configuration;
using Cardify.Sdk.Models;

// Option 1: Initialize with Bearer Token
var client = new CardifyApiClient("https://localhost:44329", "your-access-token");

// Option 2: Initialize with API Key
var client = CardifyApiClient.WithApiKey("https://localhost:44329", "your-api-key");

// Option 3: Use CardifyApiOptions for advanced configuration
var options = new CardifyApiOptions
{
    BaseUrl = "https://localhost:44329",
    AccessToken = "your-access-token", // For Bearer token
    // ApiKey = "your-api-key",        // For API Key (alternative)
    TimeoutSeconds = 60
};
var client = new CardifyApiClient(options);

Card API

Initialize Card Fields from REST API

This endpoint allows you to populate card template fields by calling an external REST API.

Authentication: Supports both Bearer Token and API Key authentication.

Authorization:

• With Bearer Token: Requires CardifyPermissions.Card.Create permission
• With API Key: Full access (bypasses user permissions)

using Cardify.Sdk;
using Cardify.Sdk.Models;
using System.Collections.Generic;

// Create the client
var client = new CardifyApiClient("https://localhost:44329", "your-access-token");

// Prepare the input
var input = new InitCardFieldsFromRestApiInput
{
    TemplateId = 1,
    
    // Path parameters for the REST API (e.g., /api/users/{userId})
    PathParams = new List<KeyValueEntity>
    {
        new KeyValueEntity { Key = "userId", Value = "123", IsStatic = true }
    },
    
    // Headers for the REST API request
    Headers = new List<KeyValueEntity>
    {
        new KeyValueEntity { Key = "Authorization", Value = "Bearer token123", IsStatic = true },
        new KeyValueEntity { Key = "Content-Type", Value = "application/json", IsStatic = true }
    },
    
    // Query parameters for the REST API (e.g., ?filter=active)
    Params = new List<KeyValueEntity>
    {
        new KeyValueEntity { Key = "filter", Value = "active", IsStatic = false },
        new KeyValueEntity { Key = "limit", Value = "10", IsStatic = true }
    },
    
    // Body parameters for POST/PUT requests
    Body = new List<KeyValueEntity>
    {
        new KeyValueEntity { Key = "name", Value = "John Doe", IsStatic = false },
        new KeyValueEntity { Key = "email", Value = "john@example.com", IsStatic = false }
    }
};

// Call the API
try
{
    var result = await client.Cards.InitCardFieldsFromRestApiAsync(input);
    
    // Access the card design
    Console.WriteLine($"Card Width: {result.Width}");
    Console.WriteLine($"Card Height: {result.Height}");
    Console.WriteLine($"Temp Metadata ID: {result.TempMetadataId}");
    Console.WriteLine($"Data JSON: {result.DataJson}");
    
    // Access front face fields
    if (result.Front != null)
    {
        Console.WriteLine($"Front has {result.Front.Fields.Count} fields");
        foreach (var field in result.Front.Fields)
        {
            Console.WriteLine($"  Field ID: {field.Id}, Value: {field.Value}");
        }
    }
    
    // Access back face fields
    if (result.Back != null)
    {
        Console.WriteLine($"Back has {result.Back.Fields.Count} fields");
    }
}
catch (CardifyApiException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
    Console.WriteLine($"Response: {ex.ResponseContent}");
}

Models

InitCardFieldsFromRestApiInput

Input model for initializing card fields from a REST API.

CardDesignWithMetadata

Response model containing the card design and metadata.

KeyValueEntity

Represents a key-value pair for API parameters.

Error Handling

The SDK throws CardifyApiException when an API request fails:

try
{
    var result = await client.Cards.InitCardFieldsFromRestApiAsync(input);
}
catch (CardifyApiException ex)
{
    // Access error details
    Console.WriteLine($"Error Message: {ex.Message}");
    Console.WriteLine($"HTTP Status Code: {ex.StatusCode}");
    Console.WriteLine($"Response Content: {ex.ResponseContent}");
}

Configuration

CardifyApiOptions

Note: If both AccessToken and ApiKey are provided, AccessToken takes precedence.

Important: The API Key must be configured in the Cardify API's appsettings.json under the ApiKeys section for authentication to work.

Authentication Methods

Using Bearer Token

// Method 1: Constructor
var client = new CardifyApiClient(
    "https://localhost:44329", 
    "your-bearer-token"
);

// Method 2: Options
var options = new CardifyApiOptions
{
    BaseUrl = "https://localhost:44329",
    AccessToken = "your-bearer-token"
};
var client = new CardifyApiClient(options);

Using API Key

// Method 1: Static factory method (recommended)
var client = CardifyApiClient.WithApiKey(
    "https://localhost:44329",
    "your-api-key"
);

// Method 2: Options
var options = new CardifyApiOptions
{
    BaseUrl = "https://localhost:44329",
    ApiKey = "your-api-key"
};
var client = new CardifyApiClient(options);

API Key Configuration (Server Side):

Add your API keys to appsettings.json on the Cardify API server:

{
  "ApiKeys": [
    "your-api-key-1",
    "your-api-key-2"
  ]
}

Advanced Usage

Dependency Injection

using Microsoft.Extensions.DependencyInjection;
using Cardify.Sdk;
using Cardify.Sdk.Configuration;

// In Startup.cs or Program.cs
services.AddSingleton(sp => 
{
    var options = new CardifyApiOptions
    {
        BaseUrl = configuration["Cardify:BaseUrl"],
        AccessToken = configuration["Cardify:AccessToken"]
    };
    return new CardifyApiClient(options);
});

// Inject in your service/controller
public class MyService
{
    private readonly CardifyApiClient _cardifyClient;
    
    public MyService(CardifyApiClient cardifyClient)
    {
        _cardifyClient = cardifyClient;
    }
    
    public async Task CreateCard()
    {
        var result = await _cardifyClient.Cards.InitCardFieldsFromRestApiAsync(...);
    }
}

Using CancellationToken

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(10));

try
{
    var result = await client.Cards.InitCardFieldsFromRestApiAsync(input, cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("Request was cancelled");
}

Requirements

• .NET 8.0 or higher
• System.Net.Http.Json
• Microsoft.Extensions.Http

License

This SDK is part of the Cardify project.

Support

For issues, questions, or contributions, please visit:

• GitHub: https://github.com/ALMuraba/Cardify

Changelog

Version 1.0.0

• Initial release
• Support for InitCardFieldsFromRestApiAsync endpoint
• Basic authentication with Bearer token
• Comprehensive error handling
• Full XML documentation