Integration Guide on .NET

To integrate your .NET web application with the Lacuna Scanner Service, follow the steps in this article.

tip

Before you start, see the integration overview.

First, add the Lacuna.Scanner.Client package to your project.

tip

If your application uses ASP.NET Core, see the ASP.NET Core section below.

With the endpoint and the API Key at hand, create a ScannerClient:

var endpoint = "...";
var apiKey = "...";
var scanner = new ScannerClient(endpoint, apiKey);

Call the CreateScanSessionAsync(string) method, passing the returnUrl, to start a session:

var scanSessionParams = await scanner.CreateScanSessionAsync("https://your-return-url/");

note

For backward compatibility, sessions created as above (with only the returnUrl) require the metadata input and document signature steps.

Or, if you want more control over the session options:

var scanSessionParams = await scanner.CreateScanSessionAsync(new CreateScanSessionRequest2() {
	ReturnUrl = "https://your-return-url/",
	MetadataInputEnabled = ...,
	SignatureEnabled = ...,
});

Use the value returned in the RedirectUrl field to redirect the user on the frontend:

location.href = scanSessionParams.RedirectUrl;

When you detect that the user has returned to your site (look for the scanSessionId argument in the URL), call the GetScanSessionAsync(Guid) method to get the scanned documents:

var scanSession = await scanner.GetScanSessionAsync(scanSessionId);
if (scanSession.Result == ScanSessionResults.Success) {
	var document = scanSession.Documents.First();
	using (var srcStream = await document.OpenReadAsync()) {
		using (var destStream = File.Create(...)) {
			await srcStream.CopyToAsync(destStream);
		}
	}
}

Multifile sessions

You can let the user scan multiple documents. To do so, pass the multifile: true parameter when creating the session:

var scanSessionParams = await scanner.CreateScanSessionAsync("https://your-return-url/", multifile: true);

At the end of the process, instead of taking only the first document, iterate over the list of scanned documents:

var scanSession = await scanner.GetScanSessionAsync(scanSessionId);
if (scanSession.Result == ScanSessionResults.Success) {
	foreach (var document in scanSession.Documents) {
		...
	}
}

Sessions with metadata input and/or signature

To ask the person scanning to enter the metadata required by Decree 10,278/2020, set the MetadataInputEnabled = true property:

var scanSessionParams = await scanner.CreateScanSessionAsync(new CreateScanSessionRequest2() {
	ReturnUrl = "https://your-return-url/",
	MetadataInputEnabled = true,
});

note

The Lacuna.Scanner.Client package must be version 1.3.0 or later.

To have the person scanning digitally sign the document at the end of the process, set the SignatureEnabled = true property:

var scanSessionParams = await scanner.CreateScanSessionAsync(new CreateScanSessionRequest2() {
	ReturnUrl = "https://your-return-url/",
	SignatureEnabled = true,
});

tip

To comply with Decree 10,278/2020, enable both metadata input and document signature.

ASP.NET Core

If your web application uses ASP.NET Core, add the following to the ConfigureServices method of your application's startup:

public void ConfigureServices(IServiceCollection services) {
	...
	services.AddScanner()
		.Configure(Configuration.GetSection("Scanner"));
}

note

Don't use the Lacuna.Scanner.Client.AspNetCore package. The Lacuna.Scanner.Client package already has everything you need to use the Scanner in ASP.NET Core.

In the appsettings.json configuration file, add the Scanner section:

...
"Scanner": {
	"Endpoint": "https://scn.lacunasoftware.com/",
	"ApiKey": "..."
},
...

In the parts of the application that need to call the service API, request an instance of IScannerService through dependency injection:

using Lacuna.Scanner.Client;

public class MyController : ControllerBase {

	private readonly IScannerService scanner;

	public MyController(IScannerService scanner) {
		this.scanner = scanner;
	}

	...
}