Factuursturen - NL Api V1: About This Document
Factuursturen - NL Api V1: About This Document
Factuursturen - NL Api V1: About This Document
nl API v1
FactuurSturen.nl has an API so external programs can reach the FactuurSturen.nl account of
a user. To get access to our API, youll need to generate an unique key for your account.
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.
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');
Example
// 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
));
Method
URL
Define number of
results
GET
?count={number}
GET
?start={number}
Example
In this api-call we specify the number of results we want.
// setup the API call with the URL and the method
$request = new
fsnl_api('https://www.factuursturen.nl/api/v1/invoices?count=5', 'GET');
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.
// setup the API call with the URL and the method
$request = new
fsnl_api('https://www.factuursturen.nl/api/v1/invoices?start=15&count=10'
, 'GET');
The Invoices API has even more exciting filter functions. Check the Invoices API chapter.
Clients API
To manage your clients, you can use the following commands.
Description
Method
URL
GET
/api/v1/clients
GET
/api/v1/clients/{id}
POST
/api/v1/clients/
Update a contact
PUT
/api/v1/clients/{id}
Delete a contact
DELETE
/api/v1/clients/{id}
Type
clientnr
required
integer
contact
string(50)
showcontact
boolean
company
string(50)
address
string(50)
zipcode
string(7)
city
string(50)
country
integer or
string
phone
string(13)
mobile
string(13)
string(255)
bankcode
string(32)
biccode
string(32)
Note
Country id. You can get a list of country id's with the
function api/v1/countrylist. When creating or updating
a client, you can supply a country id or a country name.
We'll then try to find the id of the country you supplied.
taxnumber
string(18)
tax_shifted
boolean
lastinvoice
date
string(11)
read only
sendmethod
string(10)
top
integer
stddiscount
integer
mailintro
string(128)
reference
array
notes
string
notes_on_invoice
boolean
active
boolean
default_doclang
string(2)
default_email
integer
currency
string(3)
mandate_id
string
mandate_date
date
read only
collecttype
string(4)
timestamp
date
read only
Response
Code: 200
Data: JSON or XML containing all attributes
Response
Code: 200
Data: JSON or XML containing all attributes
Example
// build the post body we are going to submit
$request->buildPostBody(array(
'contact' => 'John Doe',
'showcontact' => true,
'company' => 'Johnny Bravo Inc.',
'address' => 'Sir John Road 100',
'zipcode' => '1337 JB',
'city' => 'Johnsville',
'country' => 146,
'phone' => '010 123 4567',
'mobile' => '0612 34 56 78',
'email' => 'johnny@bravo.com',
'bankcode' => 'NL91INGB0001234567',
'biccode' => 'INGBNL2A',
'taxnumber' => 'NL001234567B01',
'tax_shifted' => false,
Response
Code: 201
Data: clientnr
Update a contact
PUT /api/v1/clients/12345
Create a PUT with at least the required attributes and fields you want to update. See the
example above for more help.
Example
Here we will update the e-mail address and phone number of a client.
// setup the API call with the URL and the method
$request = new
fsnl_api('https://www.factuursturen.nl/api/v1/clients/12345', 'PUT');
// build the post body we are going to submit
$request->buildPostBody(array(
'phone' => '010 123 4567',
'email' => 'johnny@bravo.com'
));
// execute the request
$request->execute();
Response
Code: 200
Data: null
Delete a contact
DELETE /api/v1/clients/12345
If there are documents set for this client, like invoices, the client cannot be deleted. The API
will return an error with HTTP code 403.
Response
Code: 200
Data: null
10
Products API
To manage your products, you can use the following commands.
Description
Method
URL
GET
/api/v1/products
GET
/api/v1/products/{id}
POST
/api/v1/products/
Update a product
PUT
/api/v1/products/{id}
Delete a product
DELETE
/api/v1/products/{id}
Type
Note
id
read only, required
integer
code
string(20)
name
string
price
float
taxes
integer
Response
Code: 200
Data: JSON or XML containing all attributes
11
Response
Code: 200
Data: JSON or XML containing all attributes
Example
// build the post body we are going to submit
$request->buildPostBody(array(
'code' => 'Soundboard-50S',
'name' => 'Flash Soundboard 50 Samples',
'price' => 39.95,
'taxes' => 21
));
Response
Code: 201
Data: id
Update a product
PUT /api/v1/products/12345
Response code: 200
Create a POST with at least the required attributes and attributes of fields you want to
update. Check the example above how to build the POST body.
Response
Code: 200
Data: null
Delete a product
DELETE /api/v1/products/12345
Response
Code: 200
Data: null
12
Invoices API
To manage your invoices, you can use the following commands.
Description
Method
URL
GET
/api/v1/invoices/
GET
/api/v1/invoices/{invoicenr}
POST
/api/v1/invoices/
Delete an invoice
DELETE
/api/v1/invoices/{invoicenr}
Type
Note
invoicenr
string
reference
array
lines
array
read only
Per line:
'amount'
'amount_desc'
'description'
'tax_rate'
'linetotal' (read only)
profile
id
discounttype
string(10)
discount
float
paymentcondition
string
paymentperiod
integer
collection
boolean
read only
13
taxes
array
read only
Per taxes:
'rate': tax rate
'sum': taxes on the invoice for this rate
'sum_of': amount where this taxes is relates to
tax
float
float
clientnr
integer
Client number
contact
string(50)
read only
totalintax
read
only
read only
company
string(50)
read only
address
string(50)
read only
zipcode
string(7)
read only
city
string(50)
read only
country
read
only
integer or
string
phone
string(13)
Country id. You can get a list of country id's with the
function api/v1/countrylist. When creating or updating a
client, you can supply a country id or a country name.
We'll then try to find the id of the country you supplied.
read only
mobile
string(13)
read only
invoicenote
string
date
date
date
float
date
read only
sent
read
only
uncollectible
read
only
lastreminder
read
only
open
read
only
paiddate
14
payment_url
string
date
read only
duedate
read
only
Response
Code: 200
Data: JSON or XML containing all attributes
Response
Code: 200
Data: JSON or XML containing all attributes
Method
URL
GET
?filter=open
GET
?filter=overdue
GET
?filter=sent
GET
?filter=partly
GET
?filter=toomuch
GET
?filter=paid
GET
?filter=uncollectible
15
Example
Receive all invoices that are overdue
// setup the API call with the URL and the method
$request = new
fsnl_api('https://www.factuursturen.nl/api/v1/invoices?filter=overdue',
'GET');
Type
Note
action
string(6)
required
string(11)
semi-required
savename
string(20)
boolean
semi-required
overwrite_if_exist
16
When planning a recurring invoice with the action 'repeat' there are several fields also
needed for us to process the invoice
Attribute
Type
Note
initialdate
date
date
Date when the last invoice must be sent. After this date
the recurring invoice entry is deleted.
Please use YYYY-MM-DD
string(10)
required
finalsenddate
optional
frequency
required
Possible options:
'weekly', 'monthly', 'quarterly', 'halfyearly', 'yearly',
'biweekly', 'bimonthly', 'fourweekly'
repeattype
string(6)
required
17
Response
Code: 201
Data: Invoice number
18
Response
Code: 201
Data: Invoice number
Delete an invoice
DELETE /api/v1/products/F012345
Response
Code: 200
Data: null
19
Method
URL
Mark payment
PUT
/api/v1/invoices_payment/{id or invoicenr}
Type
Note
date
date
string
required
amount
required
Mark payment
POST /api/v1/invoices_payment/F012345
Example
$request->buildPostBody(array(
'date' => '2013-01-30',
'amount' => 'full'
));
Response
Code: 201
Data: null
20
Method
URL
GET
/api/v1/invoices_saved/
GET
/api/v1/invoices_saved/{id}
DELETE
/api/v1/invoices_saved/{id}
Type
Note
id
integer
Unique invoice id
string(20)
array
array
read only
name
read
only
reference
read
only
lines
read
only
Per line:
'amount'
'amount_desc'
'description'
'tax_rate'
'price'
'linetotal' (read only)
profile
id
string(10)
float
string
integer
read only
discounttype
read
only
discount
read
only
paymentcondition
read
only
paymentperiod
read
only
21
totaldiscount
float
float
integer
Client number
read only
totalintax
read
only
clientnr
read
only
contact
string(50)
read only
company
string(50)
read only
address
string(50)
read only
zipcode
string(7)
read only
city
string(50)
read only
country
read
only
integer or
string
Country id. You can get a list of country id's with the
function api/v1/countrylist. When creating or updating a
client, you can supply a country id or a country name.
We'll then try to find the id of the country you supplied.
Response
Code: 200
Data: JSON or XML containing all attributes
Response
Code: 200
Data: JSON or XML containing all attributes
22
Response
Code: 200
Data: null
23
Method
URL
GET
/api/v1/invoices_repeated/
GET
/api/v1/invoices_ repeated/{id}
DELETE
/api/v1/invoices_ repeated/{id}
Type
Note
id
integer
Unique invoice id
string
array
array
read only
name
read
only
reference
read
only
lines
read
only
Per line:
'amount'
'amount_desc'
'description'
'tax_rate'
'price'
'linetotal' (read only)
profile
id
string
float
string
integer
read only
discounttype
read
only
discount
read
only
paymentcondition
read
only
paymentperiod
read
only
24
datesaved
date
float
date
The date when the first invoice was sent (or is going to
be sent)
date
date
The date when the last invoice is sent. After this date,
this invoice will be deleted.
string
string
integer
Client number
read only
totalintax
read
only
initialdate
read
only
nextsenddate
read
only
finalsenddate
read
only
frequency
read
only
repeattype
read
only
clientnr
read
only
contact
string
read only
company
string
read only
address
string
read only
zipcode
string
read only
city
string
read only
country
read
only
integer
or string
Country id. You can get a list of country id's with the
function api/v1/countrylist. When creating or updating a
client, you can supply a country id or a country name.
We'll then try to find the id of the country you supplied.
Response
Code: 200
Data: JSON or XML containing all attributes
25
Response
Code: 200
Data: JSON or XML containing all attributes
Response
Code: 200
Data: null
26
Method
URL
GET
/api/v1/invoices_pdf/{id or invoicenr}
Response
Code: 200
Data: PDF
27
Profiles API
To get a list of used profiles, you can use the following commands
Description
Method
URL
GET
/api/v1/profiles/
Type
Note
id
integer
string
read only
name
read
only
Response
Code: 200
Data: JSON or XML containing all attributes
28
Balance API
To read the current balance of the FactuurSturen.nl account, you can use this command
Description
Method
URL
Get balance
GET
/api/v1/balance/
Response
Code: 200
Data: Balance
29
Method
URL
GET
/api/v1/countrylist/{language}
Type
Note
id
integer
string
read only
name
read
only
Response
Code: 200
Data: JSON or XML containing all attributes
30
Taxes API
Get a list of alles taxes defined by the user in his account
Description
Method
URL
GET
/api/v1/taxes
Type
Note
percentage
integer
string
read only
type
read
only
boolean
read only
Response
Code: 200
Data: JSON or XML containing all attributes
31
Search API
Search within FactuurSturen.nl
Description
Method
URL
Execute a search
GET
/api/v1/{search_area}/{search_query}
Type
Note
search_area
string
string
search_query
Execute a search
Search of client "john"
GET /api/v1/search/clients/john
Search for a client with a specific email address
GET /api/v1/search/clients/pete@acme.com
Search of clients in Amsterdam
GET /api/v1/search/clients/amsterdam
Response
Code: 200
Data: JSON or XML containing all attributes
32