v1.0.4 stable
FactuurSturen.nl API

Getting Started

FactuurSturen.nl has an API so external programs can reach the FactuurSturen.nl account of a user. To get access to our API, you'll need to generate an unique key for your account.

About this document

This document is for version 1 of the API.

Changelog

07-07-2020 - 1.0.1

09-07-2020 - 1.0.2

19-01-2021 - 1.0.3

14-12-2021 - 1.0.4

Create API key

You'll find your key on your screen right now. With this key you have access to your account.

Revoke access

To revoke access to your account with the API, you can delete the key. The application using this key now has no access. If you want to temporarily disable a key, you can click the title of the key and remove the checkbox with the label Active. Your key will not be deleted, but the application now as no access.

Need a developer account?

If you need a developer account to test the API, contact support@factuursturen.nl.

How to use the API

The API of FactuurSturen.nl enables you to access the information inside a FactuurSturen.nl account. The API is RESTful and uses XML or JSON for the data representation. Default is XML.

PHP class library

To help you on the way and to make communicating with our API easier, we have a PHP-class to help you getting started and to help you with the API calls.

You can download the PHP-class here.

In this document, we'll use the PHP-class for the examples. Some examples will also include a JSON example.

Create a connection the the API

To start, we'll have to create a connection to our API with the PHP Class. The API is available on https://www.factuursturen.nl/api/v1. Be sure you are using HTTPS. The API isn't available for HTTP connections. Lets include the class and setup the API object.

Example

First, include the class in your script.

// include the api class at the top of your script
require_once("fsnl_api.class.php");

Example

Lets define the API url and method.

// setup the API call with the URL and the method
$request = new fsnl_api('https://www.factuursturen.nl/api/v1/clients', 'GET');

The $request object is now created. We can use this object for further communication.

Authentication

For accessing the API, we use HTTP Basic Authentication. Each request you make must contain your username and api-key.

You can add your username and api-key to the $request object.

Example

// set the username of the account where you want to connect to
$request->setUsername('myuser');

// enter the api-key as password
$request->setPassword('I3NimRMhrzPkmXWAi9KdnUN42n81CkyVhY8mndEp');

Or if you don't use the PHP-script, include the header Authorization in your call. The header consists of the word "Basic" and a base64 encoded string that contains your username, a colon : and your api-key. Like:

// a PHP example to show you what we mean:
$base64encodedString = base64_encode('myuser:I3NimRMhrzPkmXWAi9KdnUN42n81CkyVhY8mndEp');
// = bXl1c2VyOkkzTmltUk1ocnpQa21YV0FpOUtkblVONDJuODFDa3lWaFk4bW5kRXA

Add that to your Authorization-header:

Authorization: Basic bXl1c2VyOkkzTmltUk1ocnpQa21YV0FpOUtkblVONDJuODFDa3lWaFk4bW5kRXA

That's it!

Choose JSON or XML

JSON is the default format how we return data. If you would like to use XML, you can add this command to your script.

$request->setAcceptType('application/xml');

Or add this header to your call:

Accept: application/xml

Building the body for POST/PUT

When using the method POST and PUT, you'll need to send your payload to our API. Like product information, invoice lines, etc. To add the POST body to your request, add the following lines of code.

Example

Warning: This method has a maximum of 2500 input fields. Using the JSON method as shown below is highly recommended.

// build the post body we are going to submit
$request->buildPostBody(array(
  'code' => 'Soundboard-50S',
  'name' => 'Flash Soundboard 50 Samples',
  'price' => 39.95,
  'taxes' => 20
));

Use JSON

You can also use JSON to send your payload to our server. Send your JSON POST or PUT request with this extra header:

Content-Type: application/json

You can now provide your data as a JSON:

{
  "code": "Soundboard-50S",
  "name": "Flash Soundboard 50 Samples",
  "price": 39.95,
  "taxes": 20
}

Executing the command

If you want to execute a command, we have the right line of code for you.

$request->execute();

Read the response

After you have executed the command, we'll send you a response. To read the response, use the following command.

$request->getResponseBody();

You can save the results in a variable of something else.

Get more info about the response

To get more info about the response, like the HTTP status code, transfer times etc, you can use the command getResponseInfo();

$request->getResponseInfo();

You will receive an array holding more detailed information.

Rate limiting

In order to provide our web users with the best service, we limit the number of API requests to our services to 1.000 requests/hour. Please make sure your implementation respects these limits. The X-RateLimit-Limit and X-RateLimit-Remaining HTTP response headers contain information about the limit you are bound to. When you exceed the limit you will receive a 403 HTTP response code.

We may delay the call if you get close to the limit.

Defining the number of rows received

The Client API, Invoices API, Saved Invoices API, Products API, Repeating Invoices API and Search API have some extra options that can be set to control how many rows are returned. This way it's possible to build paging in your application to make sure the performance is at it's best.

There are two options possible:

Description Method URL
Define number of results (default: 100) GET {url}?count={number}
Define start record GET {url}?start={number}

Example

In this api-call we specify the number of results we want.

GET /api/v1/invoices?count=5

Example

In this api-call we'll also define a start record. Let's say we want to retrieve the records 15 till 25. We'll ask the api to start at record 15 and give us the next 10 records.

GET /api/v1/invoices?start=15&count=10

The Invoices API has more filter functions. Check the Invoices API chapter.

HTTP methods and response codes

The FactuurSturen.nl API will always respond with a HTTP status code. This code informs you about the outcome of the API call. The API can return the following HTTP status codes:

Code Name Reason
200 OK Request was successful
201 Created Entity creation was successful
204 No Content Entity deletion was successful
400 Bad request Parameters for the request are missing or malformed. Body contains the errors
401 Authorization required No authorization provided or invalid authorization information provided
402 Payment Required You do not have enough credits for the action
403 Forbidden IP is blacklisted for API usage, see Throttling information
404 Not found Entity not found
405 Method Not Allowed The endpoint with this HTTP method is not available in the API
406 Not accepted The requested content type is not supported by the API
422 Unprocessable entity Saving the entity in the database failed due to validation errors. Body contains the errors
429 Too many requests See Throttling information
500 Internal server error Something went wrong while processing the request. This is unexpected behaviour and requires FactuurSturen.nl to fix the scenario.

Most non-success error codes provide extra details in the body. Make sure to process this body, because they will provide valuable information while debugging.

Types and format

Here are the types you can use in the api. These types are defined in the attributes found in this documentation.

Type Format Notes
date YYYY-MM-DD
string string See the max length between the parentheses
boolean true or false
integer a number without decimals
float a number with decimals Use dot as decimal separator and no thousands separator. Like: 123456,70
array array See notes in the api what the array key/values may be

Need more help?

If you need more help, drop us a line at support@factuursturen.nl.
Thanks for your interest in our API.