Quaderno

Quaderno

This connector calls the Quaderno API (https://<account>.quadernoapp.com/api, API version 20241028) with the user's own API key: contacts, invoices, credit notes, quotes (proformas), expenses, products, tax calculation, tax id validation, tax jurisdictions and tax codes, and tax reports. It can create a contact, issue an invoice, email an invoice and request a report.

Tax and customer data are sensitive. Invoices, credit notes and contacts hold customers' names, addresses and tax ids, and they are legal tax records. Show them only to people who handle the account's billing, and never copy them elsewhere unasked.

Writes need a yes. An issued invoice is a legal document: Quaderno numbers it in sequence and it cannot be deleted, only voided or credited in the Quaderno app. Before quaderno_create_invoice, quaderno_create_contact, quaderno_deliver_invoice (it emails the customer at once) or quaderno_request_report, show the user what will happen and wait for their confirmation. quaderno_delete_contact is installed switched off.

Setup (about 2 minutes)

1. Sign in at https://quadernoapp.com and open Profile, API keys (https://quadernoapp.com/users/api-keys).
2. Copy the private key (it starts with sk_) into QUADERNO_API_KEY. It is sent as the HTTP Basic user name with an empty password, only to your Quaderno account.
3. Put your account name into QUADERNO_ACCOUNT_NAME: the part between https:// and .quadernoapp.com in the API URL on the same page (for example acme-1234 for https://acme-1234.quadernoapp.com/api/).

Amounts: fields ending in _cents are in cents (12345 = 123.45); unit_price, amount and tax amounts from quaderno_calculate_tax are in the currency unit. Rates are percentages.

Workflow

• Check the key: quaderno_ping.
• Customers: quaderno_list_contacts, quaderno_get_contact, quaderno_create_contact, quaderno_delete_contact (off).
• Sales documents: quaderno_list_invoices, quaderno_get_invoice, quaderno_create_invoice, quaderno_deliver_invoice, quaderno_list_credit_notes, quaderno_get_credit_note, quaderno_list_quotes, quaderno_get_quote. Purchases: quaderno_list_expenses. Catalog: quaderno_list_products.
• Tax: quaderno_calculate_tax for the rate on a sale to a location (no record is created), quaderno_validate_tax_id for a VAT number, quaderno_list_tax_jurisdictions and quaderno_list_tax_codes for reference.
• Reports: quaderno_request_report, then quaderno_get_report until state leaves pending (suceeded, spelled that way by the API, or failed); quaderno_list_reports shows earlier ones.

Paging: lists return the newest 25 records (limit up to 100). When _headers.x-pages-hasmore is true, call again with created_before set to the id of the last record.

Rate limit: 100 calls per 15 seconds; a 429 means wait until the window resets.

Common errors

• 401 Wrong API key or the user does not exist: the key is wrong, or it is the publishable key (pk_) instead of the private one, or it belongs to another account than QUADERNO_ACCOUNT_NAME.
• 404: no such record. 406: an invalid parameter value, such as an unknown tax code. 422: the document cannot be created or changed like that (for example a missing first_name or items).

Out of scope here: updating, voiding or marking invoices uncollectible, recording payments, receipts, recurring documents, transactions, checkout sessions and coupons, evidence, tax id records, webhooks, the Sandbox, and Quaderno Connect accounts.