MKMApi 1.0.8

MKMApi

A .NET client library for the Cardmarket API v2.0, providing easy access to Cardmarket's trading card marketplace services.

Features

• 🔐 OAuth 1.0a authentication
• 🎮 Game information retrieval
• 📦 Order management (seller paid orders)
• 🎴 Article and product fetching with parallel support
• 📅 Custom DateTime handling for Cardmarket's non-standard date formats
• 🔧 Built with dependency injection support
• ⚡ Async/await support with cancellation token support
• 🎯 Strongly typed responses
• 🔄 Automatic product enrichment for order articles

Installation

dotnet add package MKMApi

Quick Start

1. Configure Services

Add the Cardmarket API client to your service collection:

using Microsoft.Extensions.DependencyInjection;

IServiceCollection services = new ServiceCollection();

services.AddCardmarketApi(config =>
{
    config.AppToken = "YOUR_APP_TOKEN";
    config.AppSecret = "YOUR_APP_SECRET";
    config.AccessToken = "YOUR_ACCESS_TOKEN";
    config.AccessSecret = "YOUR_ACCESS_SECRET";
});

2. Use the Client

Retrieve the client from the service provider and make API calls:

var serviceProvider = services.BuildServiceProvider();
var cardmarketClient = serviceProvider.GetRequiredService<CardmarketApiClient>();

// Get available games
var games = await cardmarketClient.GetGames();

// Get seller paid orders with automatic product enrichment
var orders = await cardmarketClient.GetBoughtOrders();

// Get specific article details
var articleResponse = await cardmarketClient.GetArticle(12345);

// Get products from a list of articles (with rate limiting)
var articles = orders.Order.SelectMany(o => o.Article ?? []).ToList();
var products = await cardmarketClient.GetProductsFromArticles(articles);

API Credentials

To use this library, you need to obtain API credentials from Cardmarket:

1. Log in to your Cardmarket account
2. Navigate to your account settings
3. Go to the API section
4. Create a new API application
5. Copy your App Token, App Secret, Access Token, and Access Secret

Available Methods

GetGames(CancellationToken cancellationToken = default)

Retrieves the list of available games from Cardmarket.

Returns: Task<GameResponse>

Example:

var games = await cardmarketClient.GetGames();
foreach (var game in games.Games ?? [])
{
    Console.WriteLine($"{game.IdGame}: {game.Name}");
}

GetBoughtOrders(CancellationToken cancellationToken = default)

Retrieves seller paid orders (page 101) and automatically enriches them with full product details by making parallel API calls for each unique article.

Note: This method includes automatic product fetching with a 30-second delay between requests to comply with API rate limits.

Returns: Task<OrderResponse>

Example:

var orders = await cardmarketClient.GetBoughtOrders();
foreach (var order in orders.Order)
{
    Console.WriteLine($"Order {order.IdOrder}:");
    foreach (var article in order.Article ?? [])
    {
        Console.WriteLine($"  - {article.Product?.EnName} ({article.Count}x)");
    }
}

GetArticle(int articleId, CancellationToken cancellationToken = default)

Retrieves detailed information about a specific article, including its associated product.

Parameters:

• articleId: The unique identifier of the article

Returns: Task<ProductResponse>

Example:

var articleResponse = await cardmarketClient.GetArticle(12345);
var product = articleResponse.Article?.Product;
Console.WriteLine($"{product?.EnName} - {product?.ExpansionName}");

GetProductsFromArticles(List<Article> articles, CancellationToken cancellationToken = default)

Fetches product details for multiple articles sequentially with a 30-second delay between each request to respect API rate limits.

Parameters:

• articles: List of articles to fetch product information for

Returns: Task<List<Product>>

Example:

var articles = orders.Order.SelectMany(o => o.Article ?? []).ToList();
var products = await cardmarketClient.GetProductsFromArticles(articles);

Important: This method processes articles sequentially with a 30-second delay between requests. For large order sets, this operation may take considerable time.

Configuration

ApiSettings

The ApiSettings class contains the following properties:

• AppToken: Your application token from Cardmarket
• AppSecret: Your application secret from Cardmarket
• AccessToken: Your access token from Cardmarket
• AccessSecret: Your access secret from Cardmarket

Requirements

• .NET 10.0 or higher
• Microsoft.Extensions.DependencyInjection 10.0.5+
• Microsoft.Extensions.Http 10.0.5+

Technical Details

DateTime Handling

The library includes custom JSON converters to handle Cardmarket's non-standard DateTime format (2010-05-04T01:24:27+0200), which lacks the colon separator in the timezone offset. The converters automatically normalize this format to ISO 8601 standard before parsing.

Rate Limiting

The GetProductsFromArticles method implements a 30-second delay between consecutive API requests to comply with Cardmarket's rate limiting requirements. When fetching products for multiple articles, expect approximately 30 seconds per article.

Project Structure

MKMApi/
├── Infrastructure/
│   ├── CardmarketApiClient.cs           # Main API client
│   ├── ApiSettings.cs                   # Configuration settings
│   ├── OAuthHeader.cs                   # OAuth 1.0a implementation
│   ├── CardmarketDateTimeConverter.cs   # Custom DateTime converters
│   ├── IServiceCollectionExtensions.cs  # DI extensions
│   └── Responses/
│       ├── GameResponse.cs              # Game data models
│       └── Order.cs                     # Order & Article data models
└── MKMApi.csproj

Error Handling

The library uses async/await patterns and returns default empty responses when the API returns null. The library handles Cardmarket's non-standard DateTime formats automatically.

Consider implementing comprehensive error handling for production use:

try
{
    var orders = await cardmarketClient.GetBoughtOrders();
    if (orders?.Order?.Any() == true)
    {
        foreach (var order in orders.Order)
        {
            Console.WriteLine($"Order #{order.IdOrder} - {order.ArticleCount} items");

            foreach (var article in order.Article ?? [])
            {
                var productName = article.Product?.EnName ?? "Unknown Product";
                Console.WriteLine($"  {article.Count}x {productName}");
            }
        }
    }
    else
    {
        Console.WriteLine("No orders found.");
    }
}
catch (HttpRequestException ex)
{
    // Handle network errors
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (OperationCanceledException)
{
    // Handle cancellation
    Console.WriteLine("Operation was cancelled.");
}
catch (System.Text.Json.JsonException ex)
{
    // Handle JSON parsing errors
    Console.WriteLine($"JSON parsing error: {ex.Message}");
}
catch (Exception ex)
{
    // Handle other errors
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

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/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

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

Acknowledgments

• Cardmarket API Documentation
• Built with ❤️ for the trading card community

Disclaimer

This library is not officially affiliated with or endorsed by Cardmarket. Use at your own risk and ensure compliance with Cardmarket's Terms of Service and API usage guidelines.

Support

For bugs and feature requests, please open an issue on GitHub.

Roadmap

• OAuth 1.0a authentication
• Custom DateTime format handling
• Seller paid orders retrieval
• Article and product fetching
• Rate limiting for API calls
• Add support for other order types
• Add support for product searches
• Add support for stock management
• Add support for shopping cart operations
• Implement configurable rate limiting
• Add comprehensive unit tests
• Add retry logic for failed requests
• Add bulk operations support

Made with 🎴 for the Magic: The Gathering and trading card community