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
- 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.