Allegro.pl REST API

Unofficial implementation of Allegro.pl commerce platform REST API for .NET as documented on https://developer.allegro.pl

Warning

Current state: ALPHA

All endpoints are code-generated providing entirety of the API for consumption. Please be advised IAllegroApi.generated.cs may change dramatically between regenerations requiring substantial code changes for calling API endpoints. Needs better deterministic name generation handling.

Highlights

Function	Description
Strongly-typed API communication	With Refit REST library, communication with Allegro API is conducted in a type-safe manner, no magic strings or studying documentation necessary, everything is in the IntelliSense.
Code generated OpenAPI endpoints	All endpoints are code generated from most current OpenAPI specification published by Allegro.pl using Refitter, therefore is always up-to-date, error-prone and includes full IntelliSense.
Authentication API	When instance is provided with valid credentials & refresh token, library will ensure all requests have valid authentication headers. Tokens are validated and automatically refreshed only as needed. Only device flow is currently supported.

Install with NuGet

dotnet add package JadeX.AllegroAPI --prerelease

Basic Usage (Console)

Important

Make sure you have registered your application with Allegro API Apps (Sandbox) or Allegro API Apps (Production), for this you need active account on respective environment. Take note of CLIENT ID and CLIENT SECRET.

using JadeX.AllegroAPI;

var allegroRestClient = new AllegroRestClient(x =>
{
    x.Environment = AllegroEnvironment.Sandbox;
    x.Authentication.Flow = AuthenticationFlow.Device;
    x.Authentication.ClientId = "{YOUR CLIENT ID}";
    x.Authentication.ClientSecret = "{YOUR CLIENT SECRET}";
});

var deviceCodeResponse = await allegroRestClient.AuthenticationService.GetDeviceCode().ConfigureAwait(false); // Don't call this very often
Console.WriteLine($"Open {deviceCodeResponse.VerificationUrlComplete} in browser and follow instructions there ... Once finished, press enter to obtain access token and call some API endpoint.");
Console.ReadLine();
await allegroRestClient.AuthenticationService.GetAccessTokens().ConfigureAwait(false); // Valid for 12 hours, need to call RefreshTokens() afterwards

// Now it's possible to call API enpoints

var offers = await allegroRestClient.API.SearchOffersUsingGET(limit: 1).ConfigureAwait(false);
Console.Write($"You have total of {offers.TotalCount} offers.");
if (offers.TotalCount > 0)
{
    Console.WriteLine($" First one is called '{offers.Offers?.First().Name}'.");
}

var orderEvents = await allegroRestClient.API.GetOrderEventsUsingGET().ConfigureAwait(false);
Console.WriteLine($"There is total of {orderEvents.Events.Count} order events:");
Console.WriteLine("Types are: " + string.Join(", ", orderEvents.Events.Select(x => x.Type.ToString())));
Console.ReadLine();

Caution

You can't get access tokens with GetAccessTokens() until device code is validated with browser under desired user account (link in VerificationUrlComplete)!

Advanced Authentication

Clearly previous example is handling authentication very poorly, calling GetDeviceCode() every time instance is created is not just incredibly cumbersome, but deemed unwated by the API and will very soon hit rate limiter like requiring solving CAPTCHA. To solve this AccessToken and RefreshToken need to be reused.

Tip

AllegroRestClient remembers most recent device code and access/refresh tokens internally, you should deal with them only during initialization.

using JadeX.AllegroAPI;

var AllegroRestClient = new AllegroRestClient(x =>
{
    x.Environment = AllegroEnvironment.Sandbox;
    x.Authentication.Flow = AuthenticationFlow.Device;
    x.Authentication.ClientId = "{YOUR CLIENT ID}";
    x.Authentication.ClientSecret = "{YOUR CLIENT SECRET}";

    x.Authentication.RefreshToken = "{retrieve your RefreshToken from secure persistent storage}";
    // While not absolutely necessary you can also store/retrieve AccessToken, prevents unnecessary token refresh (especially useful in testing).
    x.Authentication.AccessToken = "{retrieve your AccessToken from secure persistent storage}";

    x.Authentication.OnAccessTokenChanged += OnAccessTokenChanged;
    x.Authentication.OnRefreshTokenChanged += OnRefreshTokenChanged;
});

static void OnAccessTokenChanged(object? sender, string? accessToken)
{
    // Store new accessToken in secure persistent storage like database or user-secrets file
}

static void OnRefreshTokenChanged(object? sender, string? refreshToken)
{
    // Store new refreshToken in secure persistent storage like database or user-secrets file
}

Versioning Scheme

This library is using SemVer 2.0.0 as it's versioning scheme.