factuursturen 0.3

a REST client class for the API of www.factuursturen.nl

====
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' : '[e-mail]',
'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
---------------------------