Koalaboox

About Koalaboox API

Koalaboox API allows you to extend Koalaboox and provide its capabilities in your application. You can automate the encoding of invoice, import invoices from another system or use Koalaboox to provide new features to your software

For more general information about the API and use cases, you can go to koalapi.com.

For an exhaustive list of the endpoints, you can go to connect.koalaboox.com

Reference implementation

To help the developers in their implementation of a Koalaboox API client, we have developed a basic reference implementation

This PHP/Laravel implementation is under the MIT license, which means you can copy it and adapt it to your need as a starting point.

Connection

Connections to the API are stateless (there is no session) and you will need to provide your authentication token for each request. Tokens are linked to a unique Koalaboox account. If you don’t have a Koalaboox account, you can create one for free.

Tokens are generated and handled using the OAuth2 protocol. If you want to connect to the Koalaboox API on behalf of your users, you must first create an OAuth client. It will allow you to ask your users to accept to connect your application with Koalaboox. If they agree to connect Koalaboox to your application, you will receive a unique API token for each users. The procedure is documented here.

Once you have a valid API token, you can make calls to the Koalaboox API by setting the Authorization HTTP request headers:

Authorization: Bearer OAUTH-TOKEN

For example, you can get a list of your products with the following curl call:

curl -H 'Authorization: Bearer ey...' https://connect.koalaboox.com/api/products

Or create an empty invoice for a given debtor:

curl -H 'Authorization: Bearer ey...' \
     -H "Content-type: application/json" \
     -XPOST https://connect.koalaboox.com/api/invoices \
     -d '{"debtorId": "deb_0123456789abc"}

Option A: Personal Access Tokens

Personal Access Tokens allow you to use the Koalaboox API on your own account. All you need to do is go to Koalaboox API Connect, on the Personal Access Tokens section and click on Create New Token.

Option B: OAuth Client

To integrate your third-party application with Koalaboox, use the following flow:

1. You redirect your user to Koalaboox

The first step is to redirect your user to Koalaboox.

https://connect.koalaboox.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=CLIENT_URL&state=RANDOM&response_type=code&scope

Parameters

Key Description
client_id Required. Your application client ID. You can find it in your dashboard.
redirect_uri Required. The callback URI you gave when you registered your OAuth client. You can find it in your dashboard.
state Required. A random string that identify your request. You should keep it during the process to identify the callback.
response_type Required. Should always be code.
scope Required. For future use. Should be left empty.

The user will be prompted with a screen that allows them to accept or refuse the connection between Koalaboox and your application.

Koalaboox redirect the user to client_uri

If the user accepts your request, Koalaboox will redirect the users to your redirect_uri.

In the redirect URL, you will find a temporary code parameter. You will also find a the state you provided in step 1. If the state doesn’t match what you provided in step 1. the request is not genuine and should be discarded.

If the user refused the connection, the return URL will contain an error parameter with the value access_denied.

If the process is successful, you can finally exchange your temporary code for the real API token:

$client = new GuzzleHttp\Client();
$response = $client->post('https://connect.koalaboox.com/oauth/token', [
    'form_params' => [
        'client_id' => $client_id,
        'client_secret' => $client_secret,
        'code' => $code,
        'redirect_uri' => $redirect_url,
        'grant_type' => 'authorization_code',
    ],
]);

Parameters

Key Description
client_id Required. Your application client ID. You can find it in your dashboard.
client_secret Required. Your application client secret. You can find it in your dashboard.
redirect_uri Required. The callback URI you gave when you registered your OAuth client. You can find it in your dashboard. The URI must be the same in both places or the authorization process will fail.
code Required. The code found in the callback URL.
grant_type Required. Always authorization_code.

Response

If everything works correctly, you will receive a JSON response:

{
    "access_token": "ey1565d5…",
    "expires_in": 231545
    "refresh_token": "ey1565d5…"
}

Sending an Invoice

Available methods

Non financed invoices can be sent with one of the following methods: print (print), e-mail (email), e-invoice (eInvoice), and mail (post).

Financed invoices can be send with the following methods: e-mail (email), e-mail + e-invoice (eInvoiceAndEmail), and e-mail + mail (postAndEmail).

Print

This is the simplest method to send an invoice: you just tell the application that you are going to print it and send it yourself.

This method is no suitable for finances invoices.

E-mail

Koalaboox will send the invoice by e-mail in your name. It is incumbent to you to provider a value for the to, from, cc, title and message fields. If the invoice is financed, those fields might be overwritten by the application.

E-invoice

If the debtor can receive e-invoices through the PEPPOL network, you can use this sending method.

You don’t have to provide any more information.

Post

The invoice will be printed and sent via mail by Koalaboox. This method if mandatory for certain public entities.

Your debtor’s address will be used. The only information that you have to provide is the size of the envelope and the sending method you wan to use: express (the default method) or registered (with a a proof of reception).

Formatting the payload

The POST /invoices/.../send payload should be formatted as follows:

curl -XPOST -H 'Authorization: Bearer ...'  https://connect.koalaboox.com/api/invoices/.../send -d '
{
    "method": "...",
    "email": {
        ...
    },
    "post": {
        ...
    }
}'

Default values

To help you build your /send payloads, Koalaboox provides a route that provides sensible default values for all the required fields, and, more importantly, a list of all the available sending methods:

curl -H 'Authorization: Bearer ...'  https://connect.koalaboox.com/api/invoices/.../send -d '
{
    "methods": ["print", "email", "eInvoice", "post"],
    "email": {
        "from": "...",
        "to": "...",
        ...
       },
    "post": {
        "size": "C4",
        "method": "EXPRESS"
    },
}'

Invoice Numbering

There are three options for invoice numbering that you can choose from:

  • Let Koalaboox automatically assign your invoice numbers
  • Set the document number (13) and let Koalaboox assign the fiscal period and format the number (2020/013)
  • You set the complete invoice number according to your own format

Default numbering format

The default format for invoice numbering is as follows: 2000/001, where 2000 is the legal year of the invoice and 001 is the sequence number of the invoice within that year.

The sequence (document) number is automatically incremented for each invoice you send (draft invoices don’t have a number until they are sent) and is reset to 1 at the beginning of each year.

In their preferences, your users have the ability to change the numbering format, when to reset the numbering (year, quarter…) and and to offset the current fiscal year forwards or backwards.

To take advantage of this system, you don’t have to do anything. Don’t worry about numbering and everything will be handled for you.

Specify the document number

If you want to keep the numbering style but want to provide the actual document number you can do so by setting it the invoice update route with the documentNumber field:

 curl -H 'Authorization: Bearer ey...' \
     -XPUT https://connect.koalaboox.com/api/invoices/inv_e55d5df6a5ds6d \
     -d '{"documentNumber": 654}' 

You will see the result in the returned payload:

{
    "data": {
        "id": "inv_e55d5df6a5ds6d",
        ...
        "number": "2020/654",
        "documentNumber": 654,
        ...
    }   
}

Override the numbering system

If you want to import invoices from another system to Koalaboox, you sometimes have to use a numbering scheme that is not compatible with Koalaboox’s system.

In those cases, you can override our numbering system completely by providing your own externalNumber with no limitations on its format. It can be anything as long as:

  • It is shorted than 45 characters
  • In is unique within a customer’s account

For example:

 curl -H 'Authorization: Bearer ey...' \
     -XPUT https://connect.koalaboox.com/api/invoices/inv_e55d5df6a5ds6d \
     -d '{"externalNumber": "Invoice Number One"}' 

Will return:

{
    "data": {
        "id": "inv_e55d5df6a5ds6d",
        ...
        "number": "2020/001",
        "documentNumber": 001,
        "externalNumber": "Invoice Number One",
        ...
    }   
}

As you can see, Koalaboox still provides an internal number for internal use, but your number will override in the following places:

  • Invoice PDF
  • Debtor portal
  • Invoice financing confirmation page
  • Confirmation e-mails

Caution!

This functionality is only available in the API and has no equivalent in application.

Applying to Financing

Overview

The following process alloys your users to obtain a financing contract that will allow them to finance invoices.

This process will require your user to provide some information about themselves and their company and to prove their identity as a representative of the company for which they are applying.

It consists of the following steps:

  1. Check that company is eligible for financing
  2. Update the application with a representative ID
  3. Go through the IDV (Identity Verification) process
  4. Apply for financing
  5. Register the bank account that will be used for financing
  6. Sign financing contract

If the process is successful, your user’s contract will be automatically activated and they will be able to finance invoices straight away. If all the conditions are not met to automatically activate the contract, the application will go through the manual review process that and take up to two business days.

Prerequisite

Before starting the factoring application process, make sure the account for which you are trying to activate the financing has a valid VAT number.

1. Check your eligibility status

The fist step is to check that the user’s company is eligible for financing (given that you have provided a valid VAT number in the account preferences or at registration), you can query the GET /api/financing/application route:

curl -H 'Authorization: Bearer ey...' \
    https://connect.koalaboox.com/api/financing/application

This route will include two fields related to you eligibility:

  • eligible (boolean): whether of not the company is eligible for financing
  • limit (integer): the maximal amount at your disposal for financing (always 0 if eligible is false)

To select the legal representativeId, you first need to get the list of the company’s representatives:

curl -H 'Authorization: Bearer ey...' \
    https://connect.koalaboox.com/api/customers/current/enterprise/representatives

You will receive a list of all the representatives of the company:

{
    "data": [
        {
            "id": 1779,
            "name": "John Doe"
        },
        {
            "id": 1783,
            "name": "Koala Books"
        }
    ]
}

To decide which representative you are going to use, you can ask you user to pick their name or match the name with your records.

Once you have picked the right representative, you can update the current financing application with the corresponding id:

curl -H 'Authorization: Bearer ey...' \
    -XPUT https://connect.koalaboox.com/api/financing/application \ 
    -d '{"representativeId": 1783}'

Note: The list of representatives may sometimes return an empty set ({"data": []}) for one of the following reasons:

  • The user’s account does not have VAT number saved. You can provide your VAT number at during the creation or prompt your user to update account preferences page in the application (it is not possible to update your VAT number through the API yet).
  • The VAT you have provided does not correspond to an existing company

3. Verify the user’s identity (IDV)

We now need to verify that your user is really who they claim to be. This is a central part of the application process and it will determine if the financing contract can be activated automatically or not.

To do so, you need to provide a mobile phone number for your user to which we will send a text message inviting them to go though the IDV process. You can get that number from your records of, better yet, prompt your user to provide it.

You can then ask Koalaboox to send your user a link to the IDV process:

 curl -H 'Authorization: Bearer ey...' \
     -XPOST https://connect.koalaboox.com/api/financing/application/send-link \ 
     -d '{"phoneNumber": "+32485653698"}'

If the number is invalid you will receive a validation error (422). If the number is valid and the SMS has been successfully sent, you will receive a 200 status and the response should show "idvSessionStatus": "pending".

It is now up to your user to go through the IDV process to prove their identity.

You can keep track of their progress by polling the GET api/financing/application/ route until the status changes to any of the following: succeeded, failed, pending-review or canceled.

If the status is succeeded, it means that we could reliably match you user’s identity against one company representative and that the activation will most likely be automatic.

The fact that the status is not suceeded does not mean that you cannot go further with the application. As long as the status is different from pending you can go on with the financing application and we will do whatever is necessary to establish your user’s identity and activate their account.

4. Apply for financing

After the IDV is finished, you can now apply for financing:

 curl -H 'Authorization: Bearer ey...' \
     -XPUT https://connect.koalaboox.com/api/financing/application/apply \ 
     -d '{"phoneNumber": "+32485653698"}'

5. Register a bank account

To be able to finance invoice, your user will need to provide the IBAN of the bank account they want to use for financing. Once you have obtained it from your them, you wan call the PUT /api/financing/application/register-iban route:

 curl -H 'Authorization: Bearer ey...' \
     -XPUT https://connect.koalaboox.com/api/financing/application/register-iban \ 
     -d '{"iban": "BE76663114144995"}'

6. Sign the users contract

Before signing, you should display the contract so that the user can read it. You can retrieve a draft of the contract in a PDF format with the following route:

 curl -H 'Authorization: Bearer ey...' \
     -XGET https://connect.koalaboox.com/api/financing/application/contract 

To finish the process, you need to sign the contract application. For this step to be successful, you need to pass an acceptedConditions parameter set to true. This value can be linked to a checkbox in you UI for the user to mark their approval of the terms and conditions of the financing contract.

 curl -H 'Authorization: Bearer ey...' \
     -XPUT https://connect.koalaboox.com/api/financing/application/sign \ 
     -d '{"acceptedConditions": true}'

Done!

Once the process is done, you will see that the current application’s status will change to done. It means that no further action from you part is required.

You will also see that the application will now contain a contract sub-object. It is the representation of the newly created financing contract. It’s status field will inform you on the current status of the financing contract:

  • applied: the contract has been created but still need to be manually activated by Koalaboox
  • approved: the contract is active and you can finance invoice with that account
  • closed: the financing contract has been terminated

Financing Flow

Prerequisites

To finance an invoice, you first have to make sure that:

  1. You have created a draft invoice that hold all the the required information to be sent. You can verify that by looking at the sending/ready key in an invoice resource.

  2. The invoice is eligible (with the /invoices/{id}/financing/check-eligibility route).

    This step is optional: Koalaboox will always check at time of sending the invoice that it is eligible for financing. If it is not, it will be sent without financing.

    You only need to check for eligibility manually before sending if you only want to send financed invoices and not take the risk to have them sent without financing.

  3. The invoice has been marked as having the financing requested. This can be achieved in two ways:

    1. By setting the requestFinancing field to true during the creation or update of an invoice.

    2. By passing a parameter requestIfEligible set to true when you call /invoices/{id}/financing/check-eligibility</p>

    In both cases, it will only communicate your intention to have the invoice financed in the future, not send it through the financing process

Sending the Invoice for Financing

To trigger the financing process, you need to send the invoice. If you have marked it for financing and if it is eligible, it will be sent though the financing process.

Tracking the Financing Process

Once an invoice has been financed, you can track the progress of its financing process through the financingStatus field. This field is accessible on both the index (/invoices) and the show (/invoices/{id}) API endpoints.

Languages and Currencies

Languages

The display languages of the invoices can be set to any of the following:

  • French (fr)
  • English (en)
  • Spanish (es)
  • Catalan (ca)
  • Dutch (nl)
  • German (de)

Languages used in the API must follow the ISO 639 standard.

  • If a debtor ID is provided at the creation of an invoice$section-anchor-sign-color, the debtor’s language will be used as the display language of the invoice.
  • If no debtor is provided, or if the debtor does not have a set language, the customer’s language will be used.
  • If neither the debtor’s nor the customer’s languages can be determined, the default language (fr) is used.

Currencies

The supported currencies are:

  • Canadian Dollars (CAD)
  • Swiss Frans (CHF)
  • Chinese Yuan (CNY)
  • Euros (EUR)
  • U.K. Pounds (GBP)
  • Japanese Yens (JPY)
  • Norwegian Crowns (NOK)
  • Swedish Crowns (SEK)
  • U.S. Dollars (USD)

Currencies used in the API must follow the ISO 4217 standard (upper-case 3-letter code).

By default, all new invoices are created with Euro as their currency, except if the customer has chosen a different one in their application preferences.

Tax Rates

Throughout the API, tax rates are communicated using unique textual codes. The following table describes the available rates and their respective codes.

You can also download all the tax rates as a JSON files.

Code Country Description Value
BEVAT21 Belgium TVA/btw 21% 21%
BEVAT12 TVA/btw 12% 12%
BEVAT6 TVA/btw 6% 6%
BEVAT0 TVA/btw 0% 0%
BEVATNONE n/a 0%
COC6 Cocontractant/medecontractant 6% 6%
BEVATC Cocontractant/medecontractant 0% 0%
BEVATINTRA Intracommunautaire 0%
BEVATINTRAS Intracommunautaire (service) / intracommunautaire (diensten) 0%
BEVATEXPORT Export 0%
NLVAT21 Netherlands btw 21 % 21%
NLVAT9 btw 9% 9%
NLVAT0 btw 0% 0%
LUVAT17 Luxembourg TVA/MwSt 17% 17%
LUVAT14 TVA/MwSt 14% 14%
LUVAT8 TVA/MwSt 8% 8%
LUVAT3 TVA/MwSt 3% 3%
LUVAT0 TVA/MwSt 0% 0%
LUVATEXPORTS Internat. service 0%
LUVATEXPORT Export 0%
LUVATINTRA Intracomm livraison 0%
LUVATINTRAS Intracomm service 0%
LUVAT15 TVA/MwSt 15% 15%
LUVAT13 TVA/MwSt 13% 13%
LUVAT12 TVA/MwSt 12% 12%
LUVAT6 TVA/MwSt 6% 6%
FRVAT20 France TVA 20% 20%
FRVAT10 TVA 10% 10%
FRVAT5.5 TVA 5.5% 6%
FRVAT2.1 TVA 2.1% 2%
FRVAT0 TVA 0% 0%
FRVAT19.6 TVA 19.6% 20%
FRVAT7 TVA 7% 7%
ESVAT21 Spain IVA 21% 21%
ESVAT10 IVA 10% 10%
ESVAT4 IVA 4% 4%
ESVAT0 IVA 0% 0%
ESVATINTRAS Intracomunitario 0%
DEVAT19 Germany MwSt 19% 19%
DEVAT7 MwSt 7% 7%
DEVAT0 MwSt 0% 0%
DEVATINTRA Intra 0%

† obsolete tax rates kept in the application for compatibility purpose with older invoices

Pagination

All the resources indexes (/api/invoices, /api/debtors, /api/products) are paginated, meaning that you will receive objects by batches of 25.

You can go from page to page by adding a page parameter in the URL. For instance:

curl -H "Authorization: Bearer ..." https://connect.koalaboox.com/api/invoices?page=3

All paginated pages will contain a meta section with the following information:

  • current_page: the current page (default: 1)
  • last_page: the maximum value page can take. Higher values will return an empty set of object
  • per_page: number of objects on the page (default: 25)