MyKEY4.Invoicing.Library

The MyKEY4.Invoicing.Library project provides a client library in .NET Standard 2.0 to easily make API calls to the invoicing service using predefined contracts and DTOs.

It is available through the Key4Events Nuget package source

The main entry point is the MyKey4InvoicingClient which will make REST requests to the invoicing service based on routes described below

Table of Content

• Table of content
• Available Routes
• Examples
  • 1. Setting up the requirement
  • 2. Creating an invoice
  • 3. Subscribing to Webhooks

Available Routes

The Routes class provides strongly-typed API contracts for all endpoints. Its contracts are used in the API client to send a request.

Usage

// Create the eventual request body DTO
InvoiceCreationRequestDto requestDto = new InvoiceCreationRequestDto();

// Describe the request with query params and body DTO (strongly typed)
ApiContract<InvoiceCreationResponseDto> request = myKEY4.Invoicing.Library.Routes.Invoices.Create(
    clientId: clientId,
    operationId: operationId,
    dto: requestDto);

// Send the request and receive the response.
// Will throw MyKey4InvoicingClientException on HTTP errors.
InvoiceCreationResponseDto response = await apiClient.SendRequest(request, cancellationToken: default);

Examples

There is an example app documentation/LibraryDemo/LibraryDemo.slnx with a minimal interaction with the invoicing service.

1. Setting up the requirement

Guid clientId = Guid.NewGuid(); // Must be known by your system
Guid operationId = Guid.NewGuid(); // Must be known by your system
MyKey4InvoicingClientSettings apiClientSettings = new MyKey4InvoicingClientSettings
{
    ApiKey = "esaic.aladdin",
    ApiSecret = "[...]",
    MyKey4LoginUrl = "https://dev.auth.mykey4.events/key4events/connect/token",
    MyKey4BaseUrl = "https://localhost:7009"
};
var apiClient = new MyKey4InvoicingClient(new HttpClient(), apiClientSettings);

2. Login in into MyK4

In the lifetime of a MyKey4InvoicingClient:

• You need to call Login() before sending the first request
• If the MyKey4InvoicingClient exists for a while, the login will expire and will need to be refreshed, see LoginResponseDto.ExpirationDelay

async Task Login(MyKey4InvoicingClient client)
{
    var loginResponse = await client.Login(default);
    var cts = new CancellationTokenSource();
    cts.CancelAfter(loginResponse.ExpirationDelay);
    cts.Token.Register(async () =>
    {
        if (client == null)
        {
            return;
        }
        Console.WriteLine("Authentication token expired, logging in again...");
        await Login(client);
    });
}

3. Creating an invoice

var invoiceCreationRequest = new InvoiceCreationRequestDto
{
    OrderDate = DateTimeOffset.UtcNow,
    InvoiceId = new ExternalReferenceDto("Tests", Guid.NewGuid().ToString("N")),
    OrderNumber = "TestOrder001",
    OrderStatus = InvoicePaidStatus.Paid,
    Recipient = new InvoiceRecipientDto
    {
        [...]
    },
    OrderItems = new List<OrderItemDto>
    {
        [...]
    }
};
var invoiceResponse = await apiClient.SendRequest(
    Routes.Invoices.Create(clientId, operationId, invoiceCreationRequest),
    cancellationToken: default);

4. Subscribing to Webhooks

When asking for an invoice's creation, a GUID is returned, but the invoice is not created immediatly.

The invoicing service allows you to receive callbacks on invoices updates, for example to know:

• When the invoice has been created in the provider's system
• When the invoice file (PDF) is available for download
• When an invoice has been sent through the Peppol network

Or, more dramatically, when your request for an invoice creation has failed.

Creating the hook

WebhookCreationResponseDto webhookCreationResponse = await apiClient.SendRequest(
    Routes.Webhooks.Create(clientId, new WebhookCreationRequestDto(
        "https://localhost:7042/webhooks/callback",
        operationId: null)), // null to catch all updates for the client
    cancellationToken: default);
webHooksSecrets.Add(webhookCreationResponse.Id, webhookCreationResponse.Base64Sha256Secret);

Receiving callbacks

app.MapPost("/webhooks/callback", async (WebhookCallbackDto dto) =>
{
    WebhookCallbackContentDto content = dto.DeserializePayload();
    bool isSignatureValid = dto.VerifySignature(webHooksSecrets[content.WebhookId]);
});

The callback content will contain a list of updates, with both successful and failing invoices being listed.