# Java Integration

If you successfully followed the configuration steps in Configuration, you are ready to go and connect your POS to our Vendor API using the anybill Java SDK.

# Authentication and Context

In order to authenticate properly authenticate the library, you need to create an instance of class ApiContext. The ApiContext class contains authentication information used to communicate with our API. There are currently 2 ways to create a ApiContext.

  1. Using the ApiContext.from() factory methods:

ApiContext.from() has 2 overloads, accepting a Path and another one accepting an InputStream. You should have received a JSON file with autentication information of this format:

{
    "username":"your-username",
    "password":"your-password",
    "clientId":"your-pos-cliend-id",
    "path":"https://vendor.stg.anybill.de/api"
}

This file should be either passed as Path or InputStream to ApiContext.from().

var context = ApiContext.from(Paths.get("/pathToYourCredentialsFile"));
  1. Constructing a ApiContext yourself:

Alternativly, if you store credentials by an other way, the ApiContext can also be created by calling the constructor yourself:

var context = new ApiContext(new Credentials(
    "your-username", 
    "your-password", 
    "your-pos-cliend-id",
    "https://ad.anybill.de/vendor/store https://ad.anybill.de/vendor/category https://ad.anybill.de/vendor/bill offline_access",
    "https://vendor.stg.anybill.de/api"
));

Authentication is fully done internally. The library fetches authentication tokens and refreshes them automatically, if required.

# anybill Clients

After setting up the context, anybill Clients can be created with it. Using var clients = AnybillApiClients.createClients(context) gives you access to the following clients:

var clients = AnybillApiClients.createClients(context);

// Bill client
var billClient = clients.bill();

// Category client
var categoryClient = clients.category();

// Store client
var storeClient = clients.store();

// User client
var userClient = clients.user();

These clients mimic the overall stucture of the anybill Vendor API (opens new window)

These clients can be further customized to your needs. It is possible to configure proxy or connection/request timeouts. The following shows how to configure the internal HttpClient with a 10 seconds connection timeout and 3 seconds request timeout. Additionally a proxy can be specified. These settings are applied globally for all anybill clients.

var httpClient = HttpClient.newBuilder()
    .proxy(...)
    .connectTimeout(Duration.ofSeconds(10))
    .build();
var httpOptions = new HttpOptions(Duration.ofSeconds(3));
var clients = AnybillApiClients.createClients(context, httpClient, httpOptions);

# Register new bill

If you want to display a QR code already during the checkout process and before the purchase is completed, you can request a new BillId using the register() method of a bill client.

var registerBillModel = RegisterBill.builder("your-store-id").build();
var result = billClient.register(registerBillModel);

When information about the buyer need to be encoded in the bill url, pass buyerInformation to the RegisterBill.builder:

var buyerInfo = BuyerInfo.builder(Clock.System.INSTANCE.now())
    .firstname("Test")
    .lastname("User")
    .email("test@user.de")
    .gender(Gender.f)
    .externalId("your-external-user-id")
    .build();
var registerBill = RegisterBill.builder("1")
    .buyerInformation(buyerInfo)
    .build();
var result = billClient.register(registerBillModel);

The result is either a instance of RegisterBillIdUrlResponseDto or RegisterBillIdExternalIdDto. Both contain a unique UUID for a new bill, but only RegisterBillIdUrlResponseDto contains a property url that can be used to show at the POS display as QR code.

if (result instanceof RegisterBillIdUrlResponseDto) {
    System.out.println(((RegisterBillIdUrlResponseDto) result).getUrl());
    System.out.println(result.getBillId());
} else if (result instanceof RegisterBillIdExternalIdDto) {
    System.out.println(result.getBillId());
}

RegisterBillIdExternalIdDto does not contain an url because it has already been matched to the user matching the externalId property.

# Adding a bill

A bill can be added by calling the add method of a bill client.

var data = Data.builder(Currency.getInstance("EUR"), 13.0, List.of(new VatAmount(7.0, 13.0, 12.0, 1.0)))
    .paymentType(
        PaymentTypeInformation.builder("Cash Payment", 10, new PaymentTypeExtension(
            new CashPaymentDetails(13.0, 0.0), PaymentType.Cash)
        ).build()
    )
    .build();

var security = Security.builder()
    .extend(new SecurityExtension(false, false))
    .build();
var bill = Bill.builder(new CashRegister("1234"), Head.builder().build(), data, security)
    .build();
var addBill = AddBill.builder("1", bill).build();

try {
    var result = clients.bill().add(addBill, DisplayTarget.PosDisplay);
    logger.info("Result: " + result);
} catch (BadRequestException e) {
    e.getApiError().getErrors()
        .forEach((key, errors) -> errors.forEach(System.out::println));
} catch (ApiException e) {
    e.printStackTrace();
}