Buckbrowser will be the tool for creating, sending and paying invoices.

Note You need to have a webserver (apache) installed with php and mysql

Clone the server to a position where there is a web root. This means that it can be accessed by the browser from anywhere.

git clone git@github.com:Buckbrowser/buck-server.git

Next we need some composer packages. You need composer installed, if you do not have this then you can do that by checking out getcomposer.org.

composer install

Next, we need to create the database. We can do this by going into phpmyadmin or any other mysql client. Upload and execute database.sql.

Last thing to do is to edit config/db.php and fill it with the database credentials.

Introduction

This document describes the API, which defines the communication between the server and the client. It also determines for some situations who is responsible: the server or the client.

Usage

We use named parameters (dictionary 1.1) in this API.

Every request should contain the following:

• 'JSON-RPC'-version
• Method
• Parameters
• Request-ID

Responses contain the request-ID and either a success or error response as specified with the method. All methods can return the error codes 35964 and 36002.

Primitive parameters

token

Pseudo random key van 32 bytes

Tokens are specific to a user-company combination. When a user has multiple companies connected and wants to work on the other company, it needs to call User.switch_company which returns a new token.

Tokens expire after 168 hours.

Composite parameters

create_error

{empty_fields, already_exists, incorrect_fields}

• empty_fields array - Array containing the empty parameters
• already_exists array - Array containing the parameters which values are already in the database
• incorrect_fields array - Array containing the parameters which values are incorrect in some way which is not further defined

update_error

{incorrect_fields}

• incorrect_fields array - Array containing the parameters which values are incorrect in some way which is not further defined

Errorcodes

• 35964 - Method invocation faulted

• 36000 - Not logged in

• 36001 - Wrong permissions

• 36002 - Something else we cannot explain

• 36003 - Wrong login credentials

• 36004 - Identifier not known

Functions

User

Field list

• id - User identifier
• username - Username
• password - User's password
• first_name - User's first name
• last_name - User's last name
• email - Email address
• language - User's language
• registration_date - Timestamp of when the user registered
• last_active - Timestamp of when the user was last active

User.create

Parameters

• username
• password
• email
• language (optional)

On success

{token}

On error

{registration_error}

User.read

Parameters

• token

On succes

{username, email, language, registration_date, last_active}

On error

{36000 | 36003}

User.update

Parameters

• token
• username (optional)
• password (optional)
• email (optional)
• language (optional)

On success

{true}

On error

{36000 | edit_error}

User.delete

When only a token is given, the server will send an email to the user with a verification code. If the user is the last user connected to the company, it will also notify that in the email.

When a token and matching verification code are given, the user will be deleted from the database. If the user was the last user connected to the company, the entire company and all of its data will be deleted too.

Parameters

• token
• verification_code (optional)

On success

{true}

On error

{36000}

User.authenticate

Parameters

• username
• password

On success

{token}

On error

{36003}

User.get_all_companies

Parameters

• token

On success

{{Company.id, Company.name}}

On error

{36003}

User.switch_company

Parameters

• token
• company_id

On success

{token}

On error

{36000 | 36003 | 36001}

Country

Field list

• id - Country identifier
• name - Country name
• locale - Country abbreviation, such as 'es' for 'Spain'

Country.read

Parameters

• id

On success

{name}

On error

{36004}

Country.get_all

Parameters

None

On success

{{id, name, locale}}

On error

{}

Company

Field list

• id - Identifier of the company

• name - Name of the company

• street_name - Street name of company's location

• house_number - House number of company's location

• zipcode - Zipcode of company's location

• place_name - Place name of company's location

• id_country - Identifier of the country the company is located

• email - Email address of the company

• tax_number - Tax identification number

• company_registration_number - The registration number of the company

• default_payment_term - Default payment term used on invoices

• default_invoice_number_prefix - A default string used to prepend invoice numbers

• registration_date - Timestamp of the registration with the API

Company.create

Parameters

• token

• name

• street_name (optional)

• house_number (optional)

• zipcode (optional)

• place_name (optional)

• id_country (optional)

• email

• tax_number (optional)

• company_registration_number (optional)

• default_invoice_number_prefix (optional)

• default_payment_term (optional)

On success

{Company.id}

On error

{36000}

Company.read

Parameters

• token

On success

{name, street_name, house_number, zipcode, place_name, id_country, email, tax_number, company_registration_number, default_payment_term, default_invoice_number_prefix, registration_date}

On error

{36000, 36004}

Company.update

Parameters

• token

• name (optional)

• street_name (optional)

• house_number (optional)

• zipcode (optional)

• place_name (optional)

• id_country (optional)

• email (optional)

• tax_number (optional)

• company_registration_number (optional)

• default_invoice_number_prefix (optional)

• default_payment_term (optional)

On success

{true}

On error

{36000}

Company.delete

This will delete the company and all data related to it, such as invoices, products etc.

Notice: this will delete the current token of the users since tokens are company specific.

Parameters

• token

On success

{true}

On error

{36000 | 36001}

Company.get_all_bank_accounts

Parameters

• token

On success

{{BankAccount.id, BankAccount.account_holder, BankAccount.iban, BankAccount.bic}}

On error

{36000 | 36001}

Company.get_all_contacts

Parameters

• token

On success

{{Contact.id, Contact.company}}

On error

{36000 | 36001}

Company.get_all_invoices

Parameters

• token

On success

{{Invoice.id, Invoice.id_contact, Invoice.invoice_number}}

On error

{36000 | 36001 | 36004}

Company.add_payment_method

Parameters

• token

• id_payment_method

On success

{true}

On error

{36000 | 36001 | 36004}

BankAccount

Field list

• id - Identifier of the bank account
• id_company - Identifier of the company this bank account belongs to
• account_holder - Name of the owner of the account
• iban - International Bank Account Number
• bic - Business Identifier Code

BankAccount.create

Parameters

• token
• account_holder
• iban
• bic

On success

{BankAccount.id}

On error

{36000 | 36001}

BankAccount.read

Parameters

• token
• id

On success

{account_holder, iban, bic}

On error

{36000 | 36001 | 36004}

BankAccount.update

Parameters

• token
• id
• account_holder (optional)
• iban
• bic

On success

{true}

On error

{36000 | 36001 | 36004}

BankAccount.delete

Parameters

• token
• id

On success

{true}

On error

{36000 | 36001 | 36004}

TaxCategory

Field list

• id_country - Identifier of the country this tax rate belongs to
• id_company - Identifier of the company this tax rate belongs to
• description - Describes what the tax rate is used for
• percentage - Representation of the tax rate percentage as a double

TaxCategory.create

Parameters

• token

• id_country (optional)

• description

• percentage

On success

{TaxCategory.id}

On error

{36000 | 36001 | 36004}

TaxCategory.read

Parameters

• token

• id

On success

{country_name, description, percentage}

On error

{36000 | 36004}

TaxCategory.update

Parameters

• token
• id
• id_country (optional)
• description (optional)
• percentage (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

TaxCategory.delete

Parameters

• token
• id

On success

{true}

On error

{36000 | 36001 | 36004}

TaxCategory.getAll

Parameters

• token

On success

{{TaxCategory.id, TaxCategory.id, TaxCategory.description, TaxCategory.percentage}}

On error

{36000}

Contact

Field list

• id - Contact identifier
• company - Name of the company
• first_name - First name of the contact person
• last_name - Last name of the contact person
• street_name - Street name of the company
• house_number - House number
• zipcode - Zipcode
• place_name - Place name
• id_country - Id of the country
• default_payment_term - Default payment term for the contact in days
• default_auto_reminder - Boolean for automatic sending of reminders

Contact.create

Parameters

• token

• id

• company

• first_name

• last_name

• street_name

• house_number

• zipcode

• place_name

• id_country (optional)

• default_payment_term (optional)

• default_auto_reminder (optional)

On success

{id}

On error

{36000 | 36001 | 36004}

Contact.read

Parameters

• token

• id

On success

{company, first_name, last_name, street_nane, house_number, zipcode, place_name, id_country, default_payment_term, default_auto_reminder}

On error

{36000 | 36004}

Contact.update

Parameters

• token

• id

• company (optional)

• first_name (optional)

• last_name (optional)

• street_name (optional)

• house_number (optional)

• zipcode (optional)

• place_name (optional)

• id_country (optional)

• default_payment_term (optional)

• default_auto_reminder (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

Contact.delete

Parameters

• token

• id

On success

{true}

On error

{36000 | 36001 | 36004}

Contact.get_all_invoices

Parameters

• token

• id

On success

{{Invoice.id, Invoice.invoice_number}}

On error

{36000 | 36001 | 36004}

Invoice

Field list

• id - Invoice identifier
• id_company - Company this invoice belongs to
• id_contact - Contact this invoice will be send to
• invoice_date - Send timestamp of the invoice
• payment_term - Term in which the invoice should be payed
• description - Description of the invoice
• products - Array of products on the invoice
• invoice_number - Administrational number identifying the invoice
• paid - Timestamp at which the invoice was paid
• auto_reminder - Whether or not id_contact should automatically be reminded if the payment_term expires

Invoice.create

If payment_term is not given, the default_payment_term from the contact will be used.

If auto_reminder is not given, the default_auto_reminder from the contact will be used.

Product must be in an array, so multiple products can be added.

Parameters

• token

• id_contact

• payment_term (optional)

• description

• products

• auto_reminder (optional)

On success

{Invoice.id, invoice_number}

On error

{36000 | 36001 | 36004}

Invoice.read

Parameters

• token

• id

On success

{id_contact, invoice_date, payment_term, description, products, invoice_number, paid, auto_reminder}

On error

{36000 | 36001 | 36004}

Invoice.update

Product must be in an array, so multiple products can be updated.

Parameters

• token

• id

• id_contact (optional)

• invoice_date (optional)

• payment_term (optional)

• products (optional)

• description (optional)

• paid (optional)

• auto_reminder (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

Invoice.delete

Parameters

• token

• id

On success

{true}

On error

{36000 | 36001 | 36004}

Expense

Field list

• id - Expense identifier
• id_company - Company this expense belongs to
• id_contact - Contact this expense will be send to
• expense_date - Send timestamp of the expense
• payment_term - Term in which the expense should be payed
• products - Array of products on the expense
• description - Description of the expense
• payment_reference - Administrational information the contact wishes to see on the banktransfer you make when paying the expense
• paid - Timestamp at which the expense was paid

Expense.create

Product must be in an array, so multiple products can be added.

Parameters

• token

• id_contact

• expense_date

• payment_term

• products

• description

• payment_reference (optional)

• paid (optional)

On success

{Expense.id}

On error

{36000 | 36001}

Expense.read

Parameters

• token

• id

On success

{id_contact, expense_date, payment_term, products, description, payment_reference, paid, auto_reminder}

On error

{36000 | 36001 | 36004}

Expense.update

Product must be in an array, so multiple products can be updated.

Parameters

• token

• id

• id_contact (optional)

• expense_date (optional)

• payment_term (optional)

• description (optional)

• products (optional)

• payment_reference (optional)

• paid (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

Product

Field list

• id - Product identifier
• id_company - Company the product is used with
• amount - Price of the product in cents
• description - Description of the product
• id_tax_category - Identifier of the tax category that is applied
• id_product_category - Identifier of the product category this product belongs to

Product.create

Parameters

• token

• amount

• description

• id_tax_category

• id_product_category (optional)

On success

{Product.id}

On error

{36000 | 36001}

Product.read

Parameters

• token
• id

On success

{amount, description, id_tax_category, id_product_category}

On error

{36000 | 36001 | 36004}

Product.update

Parameters

• token
• id

On success

{amount, description, id_tax_category, id_product_category}

On error

{36000 | 36001 | 36004}

Product.delete

Parameters

• token
• id

On success

{true}

On error

{36000 | 36001 | 36004}

ProductCategory

Field list

• id - Product category identifier
• name - Name of the product category
• id_company - Identifier of the company this product category belongs to

ProductCategory.create

Parameters

• token

• name

On success

{ProductCategory.id}

On error

{36000 | 36001}

ProductCategory.read

Parameters

• token

• id

On success

{name, id_company}

On error

{36000 | 36001 | 36004}

ProductCategory.update

Parameters

• token

• id

• name (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

ProductCategory.delete

Parameters

• token

• id

On success

{true}

On error

{36000 | 36001 | 36004}

ProductCategory.get_all

Parameters

• token

On success

{{name}}

On error

{36000 | 36001 | 36004}

ProductCategory.get_all_products

Parameters

• token

• id

On success

{{Product.id, Product.description, Product.amount, Product.id_tax_category}}

On error

{36000 | 36001 | 36004}

PaymentMethod

Field list

• id - Payment method identifier
• name - Name of the payment method
• method_name - Methodname

PaymentMethod.get_all

Parameters

• token

On success

{{id, name, method_name}, {bank_name, bank_id}}

On error

{36000 | 36001 | 36004}

Payment

Field list

• id - Payment identifier
• id_invoice - Invoice identifier
• payment_id - Payment identifier of the payment provider
• id_payment_method - Payment method identifier

Payment.create

Parameters

• token
• id_invoice
• id_payment_method
• bank_id (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

Payment.delete

Parameters

• token
• id

On success

{true}

On error

{36000 | 36001 | 36004}

Template

Field list

• id - Template identifier
• name - Name of the template
• id_company - Identifier of the company who's template it is
• content - The base64-encoded template

Template.create

Parameters

• token
• name
• content

On success

{true}

On error

{36000 | 36001 | 36004}

Template.read

Parameters

• token
• id

On success

{name, content}

On error

{36000 | 36001 | 36004}

Template.update

Parameters

• token
• name (optional)
• content (optional)

On success

{true}

On error

{36000 | 36001 | 36004}

Template.delete

Parameters

• token
• id

On success

{true}

On error

{36000 | 36001 | 36004}

Template.get_all

Parameters

• token

On success

{id, name}

On error

{36000 | 36001 | 36004}

Dictionary

1.1 Named parameters

Named parameters, or keyword arguments, is a means of using arguments that avoids the need of order. Every parameter is given a name, which ensures easy parameter use and creates more secureness on the server side.