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 = Routes.Invoices.Create(
    clientId: clientId,
    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 = "N/A", // Not needed locally, will be required in production
    MyKey4BaseUrl = "https://localhost:7007"
};
var apiClient = new MyKey4InvoicingClient(new HttpClient(), apiClientSettings);

2. Creating an invoice

var invoiceCreationRequest = new InvoiceCreationRequestDto
{
    OperationId = operationId,
    OrderNumber = "TestOrder001",
    OrderStatus = InvoicePaidStatus.Paid,
    Recipient = new InvoiceRecipientDto
    {
        [...]
    },
    OrderItems = new List<OrderItemDto>
    {
        [...]
    }
};
invoiceCreationRequest.Recipient.SetMetadata(new CustomerMetadata_FR
{
    Siren = "SIREN",
    VatNumber = "VAT"
});
var invoiceResponse = await apiClient.SendRequest(
    Routes.Invoices.Create(clientId, invoiceCreationRequest),
    cancellationToken: default);

3. 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.