README.md

factuursturen

The factuursturen package is a client for the dutch webservice www.factuursturen.nl API.

To be able to use the API, you will need an API key. You can get one with these steps:

• log in on http://www.factuursturen.nl
• click 'Instellingen'
• click 'Verbindingen'
• click 'Maak API Sleutel'

API documentation can be found at http://www.factuursturen.nl/docs/api_v0_beta.pdf (or there might be a newer version present at the moment you read this)

Synopsis

Typical usage is something like this:

#!/usr/bin/env python
import factuursturen

username = 'foo'
apikey = 'some_long_string'


fact = factuursturen.Client(apikey, username)

clients = fact.get('clients')

new_product = {'code': 'Productcode',
               'name': 'Name of this product',
               'price': 123.45,
               'taxes': 21}
try:
    fact.post('products', data)
except FactuursturenWrongPostvalue as errormessage:
    print "oops! {errormessage}".format(errormessage=errormessage)

invoices = fact.get('invoices')

for invoice in invoices:
invoicenr = invoice[u'invoicenr']
try:
    pdf = fact.get('invoices_pdf', invoicenr)

    filename = '/tmp/{invoicenr}.pdf'.format(invoicenr=invoicenr)
    with open(filename, 'w') as f:
        f.write(pdf)
    print "{} written".format(filename)
except factuursturenEmptyResult:
    print "factuur {invoicenr} is empty".format(invoicenr=invoicenr)

Installation:

Either:

* type this command:
sudo pip install factuursturen

or: * download source * extract * cd into directory containing setup.py * type this command python setup.py install

Changes from the API documentation

This client is pythonic, so some things are translated:

• booleans are returned as true booleans (not as strings with 'true')
• nested dictionaries can be used in posting (will be flattened automatically)
• returned dicts are the same structure as a dict that can be used for posting

Examples

Initialisation

You can either pass username and apikey when instantiating an object:

import factuursturen
username = 'foo'
apikey = 'some_long_string'
fact = factuursturen.Client(apikey, username)

or create a file named .factuursturen_rc in the current directory or your home directory like this:

[default]
username = foo
apikey = some_long_string

(note: no quotes!), and create the object without explicitely passing them:

import factuursturen
fact = factuursturen.Client()

create a product

import factuursturen
fact = factuursturen.Client()
new_product = {'code': 'Productcode',
               'name': 'Name of this product',
               'price': 123.45,
               'taxes': 21}
try:
    fact.post('products', new_product)
except factuursturen.FactuursturenWrongPostvalue as errormessage:
    print "oops! {errormessage}".format(errormessage=errormessage)

create a client

client = {'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' : '[email protected]',
          'bankcode' : '123456789',
          'taxnumber' : 'NL001234567B01',
          'tax_shifted' : False,
          'sendmethod' : 'email',
          'paymentmethod' : 'bank',
          'top' : 3,
          'stddiscount' : 5.30,
          'mailintro' : 'Dear Johnny,',
          'reference' : {'line1': 'Your ref: ABC123',
                         'line2': 'Our ref: XZX0029/2932/001',
                         'line3': 'Thank you for your order'},
          'notes' : 'This client is always late with his payments',
          'notes_on_invoice' : False
         }

try:
    clientid = fact.post('clients', client)
    print "client added with id {id}".format(id=clientid)
except factuursturen.FactuursturenError as errormessage:
    print "oops! {errormessage}".format(errormessage=errormessage)

send an invoice to a client