clearbooks 0.16.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/AUTHORS.md +31 -0
- data/CHANGELOG.md +0 -0
- data/COPYING.md +12 -0
- data/FAQ.md +8 -0
- data/Gemfile +105 -0
- data/LICENSE.md +14 -0
- data/MAINTAINERS.md +40 -0
- data/README.md +549 -0
- data/Rakefile +94 -0
- data/Thorfile +80 -0
- data/bin/clearbooks +28 -0
- data/clearbooks.gemspec +119 -0
- data/examples/demo.rb +8 -0
- data/lib/clearbooks.rb +92 -0
- data/lib/clearbooks/core_ext.rb +8 -0
- data/lib/clearbooks/core_ext/array.rb +51 -0
- data/lib/clearbooks/core_ext/hash.rb +47 -0
- data/lib/clearbooks/core_ext/io_binary_read.rb +20 -0
- data/lib/clearbooks/core_ext/string.rb +21 -0
- data/lib/clearbooks/error.rb +8 -0
- data/lib/clearbooks/error/errors.rb +228 -0
- data/lib/clearbooks/interface/rake/cucumber.rb +36 -0
- data/lib/clearbooks/interface/rake/default.rb +28 -0
- data/lib/clearbooks/interface/rake/documentation.rb +45 -0
- data/lib/clearbooks/interface/rake/guard.rb +13 -0
- data/lib/clearbooks/interface/rake/helpers.rb +27 -0
- data/lib/clearbooks/interface/rake/library.rb +126 -0
- data/lib/clearbooks/interface/rake/metric.rb +15 -0
- data/lib/clearbooks/interface/rake/rspec.rb +31 -0
- data/lib/clearbooks/interface/thor/info.thor +292 -0
- data/lib/clearbooks/interface/thor/mixin/config_choice.rb +27 -0
- data/lib/clearbooks/interface/thor/mixin/configuration.rb +28 -0
- data/lib/clearbooks/interface/thor/mixin/default.rb +30 -0
- data/lib/clearbooks/interface/thor/mixin/default_config.rb +31 -0
- data/lib/clearbooks/interface/thor/mixin/guess.rb +57 -0
- data/lib/clearbooks/interface/thor/mixin/shell.rb +225 -0
- data/lib/clearbooks/interface/thor/version.thor +34 -0
- data/lib/clearbooks/library/client.rb +257 -0
- data/lib/clearbooks/library/configuration.rb +34 -0
- data/lib/clearbooks/model/account_code.rb +65 -0
- data/lib/clearbooks/model/base.rb +67 -0
- data/lib/clearbooks/model/entity.rb +225 -0
- data/lib/clearbooks/model/invoice.rb +163 -0
- data/lib/clearbooks/model/item.rb +78 -0
- data/lib/clearbooks/model/journal.rb +74 -0
- data/lib/clearbooks/model/ledger.rb +52 -0
- data/lib/clearbooks/model/payment.rb +113 -0
- data/lib/clearbooks/model/project.rb +58 -0
- data/lib/clearbooks/version.rb +12 -0
- data/spec/clearbooks/clearbooks_spec.rb +27 -0
- data/spec/clearbooks/model/account_code_spec.rb +52 -0
- data/spec/clearbooks/model/entity_spec.rb +107 -0
- data/spec/clearbooks/model/invoice_spec.rb +109 -0
- data/spec/clearbooks/model/journal_spec.rb +77 -0
- data/spec/clearbooks/model/payment_spec.rb +103 -0
- data/spec/clearbooks/model/project_spec.rb +72 -0
- data/spec/fixtures/response/allocate_payment.xml +12 -0
- data/spec/fixtures/response/create_entity.xml +12 -0
- data/spec/fixtures/response/create_invoice.xml +11 -0
- data/spec/fixtures/response/create_journal.xml +12 -0
- data/spec/fixtures/response/create_payment.xml +12 -0
- data/spec/fixtures/response/create_project.xml +12 -0
- data/spec/fixtures/response/delete_entity.xml +12 -0
- data/spec/fixtures/response/delete_journal.xml +12 -0
- data/spec/fixtures/response/list_account_codes.xml +168 -0
- data/spec/fixtures/response/list_entities.xml +45 -0
- data/spec/fixtures/response/list_invoices.xml +56 -0
- data/spec/fixtures/response/list_projects.xml +16 -0
- data/spec/fixtures/response/no_api_key_fault.xml +8 -0
- data/spec/fixtures/response/well_formed_request.xml +10 -0
- data/spec/fixtures/response/wrong_api_key_fault.xml +8 -0
- data/spec/spec_helper.rb +26 -0
- metadata +212 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 540a736e7bc2040a84a2a925faef7060ece6f179
|
4
|
+
data.tar.gz: 6b74558286b48bea1b1e7864e35ce83a8996c684
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 6d8fdc185c2d7fac8b79113c40f4a17282f556f9a62e60fe00b633eae0f2f25f7c20799838ffb05c23961df875d7a57da60bc1a20039348f887faa07b3ea99cb
|
7
|
+
data.tar.gz: c85174c759dc0de9031108c2972407148ffb2c8b38b129b55c943c4d315547c83c1988c1f41d509777344b25293f38cabd889a1dfa64722c066b2d8e812288de
|
data/AUTHORS.md
ADDED
@@ -0,0 +1,31 @@
|
|
1
|
+
Please refer to the MAINTAINERS file for more information.
|
2
|
+
|
3
|
+
AUTHORS
|
4
|
+
|
5
|
+
The following list is a narration of persons who contributed to this project.
|
6
|
+
|
7
|
+
P: Person
|
8
|
+
M: Mail patches to
|
9
|
+
L: Mailing list that is relevant to this area
|
10
|
+
W: Web-page with status/info
|
11
|
+
S: Status, one of the following:
|
12
|
+
|
13
|
+
BDFL: Benevolent Dictator for Life, http://en.wikipedia.org/wiki/Benevolent_dictator_for_life
|
14
|
+
Creator: Original Developer and Maintainer of the code, please refer first to Maintainer.
|
15
|
+
Associated: Has some relevance to the project and is referable to specific parts of the project.
|
16
|
+
|
17
|
+
|
18
|
+
CLEARBOOKS
|
19
|
+
P: Oleg Kukareka
|
20
|
+
M: oleg AT kukareka DOT com
|
21
|
+
L: -
|
22
|
+
W: https://github.com/kukareka
|
23
|
+
S: Creator
|
24
|
+
|
25
|
+
CLEARBOOKS
|
26
|
+
P: Bjoern Rennhak
|
27
|
+
M: bjoern AT greylon DOT com
|
28
|
+
L: -
|
29
|
+
W: http://github.com/rennhak
|
30
|
+
S: BDFL, Creator
|
31
|
+
|
data/CHANGELOG.md
ADDED
File without changes
|
data/COPYING.md
ADDED
@@ -0,0 +1,12 @@
|
|
1
|
+
|
2
|
+
These files are part of the CLEARBOOKS solution.
|
3
|
+
|
4
|
+
Copyright 2015, Bjoern Rennhak
|
5
|
+
Greylon Ltd.
|
6
|
+
|
7
|
+
This project is open source software under MIT license.
|
8
|
+
|
9
|
+
This software is distributed in the hope that it will be useful,
|
10
|
+
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
12
|
+
|
data/FAQ.md
ADDED
@@ -0,0 +1,8 @@
|
|
1
|
+
|
2
|
+
Q: Why do you have a Gemfile and a gemspec if this is a gem?
|
3
|
+
A: For local development its quite convenient to have a Gemfile and Gemfile.lock, but once done for
|
4
|
+
publishing etc. you just need the gemspec. This kind of hybrid approach is a bit unorthodox but
|
5
|
+
useful. Once the software is mature its ok to remove gemfile, lock file, and other pinnings since
|
6
|
+
your gem is supposed to run everywhere.
|
7
|
+
|
8
|
+
|
data/Gemfile
ADDED
@@ -0,0 +1,105 @@
|
|
1
|
+
# File: Gemfile
|
2
|
+
|
3
|
+
|
4
|
+
# Sources to draw gems from
|
5
|
+
source "https://rubygems.org"
|
6
|
+
|
7
|
+
group :production do # {{{
|
8
|
+
|
9
|
+
########
|
10
|
+
#
|
11
|
+
# Do not add production gems here, but instead use
|
12
|
+
# clearbooks.gemspec file !
|
13
|
+
#
|
14
|
+
####
|
15
|
+
|
16
|
+
end # }}}
|
17
|
+
|
18
|
+
group :default do # {{{
|
19
|
+
|
20
|
+
# System
|
21
|
+
gem 'bundler'
|
22
|
+
gem 'rake'
|
23
|
+
gem 'thor'
|
24
|
+
|
25
|
+
end # }}}
|
26
|
+
|
27
|
+
group :development do # {{{
|
28
|
+
|
29
|
+
# Generate manuals
|
30
|
+
gem 'ronn', '<= 0.7.2'
|
31
|
+
gem 'rdiscount'
|
32
|
+
|
33
|
+
# REPL
|
34
|
+
gem 'racksh'
|
35
|
+
|
36
|
+
platforms :ruby_19, :ruby_20 do
|
37
|
+
gem 'pry-debugger'
|
38
|
+
gem 'pry-stack_explorer'
|
39
|
+
end
|
40
|
+
|
41
|
+
gem 'shotgun'
|
42
|
+
gem 'rerun'
|
43
|
+
|
44
|
+
gem 'guard'
|
45
|
+
gem 'guard-shell'
|
46
|
+
gem 'ptools'
|
47
|
+
gem 'os'
|
48
|
+
gem 'awesome_print'
|
49
|
+
|
50
|
+
# Notifications from live-reload etc.
|
51
|
+
gem 'growl'
|
52
|
+
gem 'ruby-growl'
|
53
|
+
gem 'rb-inotify' unless RUBY_PLATFORM=~ /darwin/
|
54
|
+
|
55
|
+
end # }}}
|
56
|
+
|
57
|
+
group :test do # {{{
|
58
|
+
|
59
|
+
# # Testing / Development
|
60
|
+
gem 'aruba'
|
61
|
+
gem 'rspec', '~> 2.0'
|
62
|
+
gem 'guard-rspec', require: false
|
63
|
+
gem 'nyan-cat-formatter'
|
64
|
+
gem 'simplecov', '~> 0.8.1'
|
65
|
+
gem 'simplecov-rcov'
|
66
|
+
gem 'simplecov-rcov-text'
|
67
|
+
gem 'metric_fu', '>= 4.5.x'
|
68
|
+
gem 'cucumber'
|
69
|
+
|
70
|
+
end # }}}
|
71
|
+
|
72
|
+
group :security do # {{{
|
73
|
+
|
74
|
+
# 0-days?
|
75
|
+
gem 'bundler-audit'
|
76
|
+
|
77
|
+
end # }}}
|
78
|
+
|
79
|
+
group :profiling do # {{{
|
80
|
+
|
81
|
+
gem 'stackprof'
|
82
|
+
|
83
|
+
end # }}}
|
84
|
+
|
85
|
+
group :docs do # {{{
|
86
|
+
|
87
|
+
gem 'yumlcmd'
|
88
|
+
gem 'coderay' # syntax highlighting and code formatting in html
|
89
|
+
gem 'redcarpet'
|
90
|
+
gem 'github-markup'
|
91
|
+
gem 'htmlentities'
|
92
|
+
|
93
|
+
# Documentation
|
94
|
+
gem 'yard'
|
95
|
+
gem 'wicked_pdf'
|
96
|
+
gem 'wkhtmltopdf'
|
97
|
+
|
98
|
+
end # }}}
|
99
|
+
|
100
|
+
|
101
|
+
# Declare clearbooks.gemspec
|
102
|
+
gemspec
|
103
|
+
|
104
|
+
|
105
|
+
# vim:ts=2:tw=100:wm=100
|
data/LICENSE.md
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
|
2
|
+
These files are part of the CLEARBOOKS solution.
|
3
|
+
|
4
|
+
Copyright 2015, Bjoern Rennhak
|
5
|
+
Greylon Ltd.
|
6
|
+
|
7
|
+
This project is open source software under MIT license.
|
8
|
+
|
9
|
+
This software is distributed in the hope that it will be useful,
|
10
|
+
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
11
|
+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
12
|
+
|
13
|
+
|
14
|
+
|
data/MAINTAINERS.md
ADDED
@@ -0,0 +1,40 @@
|
|
1
|
+
ATTENTION
|
2
|
+
|
3
|
+
Please make sure before E-Mailing any of the person below that you have made sure
|
4
|
+
that the changes are tested and releasable as submitted by you. If you want to report
|
5
|
+
a bug please make sure that it is reproducable and be sure to include all necessary
|
6
|
+
information to fix it.
|
7
|
+
|
8
|
+
If you supply changes please prefer the Unix/Linux patch system (diff -u) as it will be least
|
9
|
+
problematic to test and modify the development code. Again please be sure to submit
|
10
|
+
your Hard-/Software configuration as patches will be rechecked by us and need to be
|
11
|
+
mergable into the tree.
|
12
|
+
|
13
|
+
Please do not forget to include credits or other acknowledgements in your submission.
|
14
|
+
Before submitting anything please make sure that you have the proper rights to submit them
|
15
|
+
and be prepared to submit all rights to Clothes Network Ltd.
|
16
|
+
|
17
|
+
|
18
|
+
MAINTAINERS
|
19
|
+
|
20
|
+
The following list is a narration of person currently in charge of this project.
|
21
|
+
|
22
|
+
P: Person
|
23
|
+
M: Mail patches to
|
24
|
+
L: Mailing list that is relevant to this area
|
25
|
+
W: Web-page with status/info
|
26
|
+
S: Status, one of the following:
|
27
|
+
|
28
|
+
Maintainer: Project Maintainer and general assistance for project coordination
|
29
|
+
Creator: Original Developer and Maintainer of the code, please refer first to Maintainer.
|
30
|
+
Associated: Has some relevance to the project and is referable to specific parts of the project.
|
31
|
+
|
32
|
+
|
33
|
+
CLEARBOOKS
|
34
|
+
P: Bjoern Rennhak
|
35
|
+
M: bjoern AT greylon DOT com
|
36
|
+
L: -
|
37
|
+
W: http://www.greylon.com
|
38
|
+
S: Creator, Maintainer
|
39
|
+
|
40
|
+
|
data/README.md
ADDED
@@ -0,0 +1,549 @@
|
|
1
|
+
# Clearbooks
|
2
|
+
Version 0.16.3
|
3
|
+
|
4
|
+
[![Gem Version](https://badge.fury.io/rb/clearbooks.svg)](http://badge.fury.io/rb/clearbooks)
|
5
|
+
[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://img.shields.io/badge/license-MIT-brightgreen.svg)
|
6
|
+
|
7
|
+
This is an unofficial Clear Books [1] API gem to handle any kind of interaction of their SOAP
|
8
|
+
Service [2] via a native Ruby interface. Clear Books is an online accounting software usable as a
|
9
|
+
Software as a Service (SaaS). Their official API works via SOAP and WSDL and currently is only officially supported
|
10
|
+
via PHP [3].
|
11
|
+
|
12
|
+
It allows the handling of invoices, expenses, financial accounts and mobile accounting as well as online HR and payroll.
|
13
|
+
|
14
|
+
|
15
|
+
[1] Clear Books PLC, https://www.clearbooks.co.uk
|
16
|
+
|
17
|
+
[2] https://www.clearbooks.co.uk/support/api
|
18
|
+
|
19
|
+
[3] https://www.clearbooks.co.uk/support/api/code-examples/php/
|
20
|
+
|
21
|
+
[4] https://github.com/clearbooks
|
22
|
+
|
23
|
+
|
24
|
+
## Features
|
25
|
+
|
26
|
+
- Application
|
27
|
+
- Ruby VM (2.2 or better)
|
28
|
+
- Feature Providing Base Libraries
|
29
|
+
- Savon
|
30
|
+
- Thor
|
31
|
+
- Development
|
32
|
+
- Development Base Libraries
|
33
|
+
- RVM
|
34
|
+
- Rake
|
35
|
+
- Thor
|
36
|
+
- Code Quality
|
37
|
+
- Code review
|
38
|
+
- Yard & related (gem install yard --no-ri --no-rdoc ; gem install rdiscount --no-ri --no-rdoc)
|
39
|
+
- MetricFu/RSpec/Cucumber
|
40
|
+
|
41
|
+
|
42
|
+
## Installing
|
43
|
+
|
44
|
+
To install the `Clearbooks` gem, run the `gem` command:
|
45
|
+
|
46
|
+
```sh
|
47
|
+
gem install clearbooks
|
48
|
+
```
|
49
|
+
|
50
|
+
Or update your `Gemfile`:
|
51
|
+
|
52
|
+
```ruby
|
53
|
+
gem 'clearbooks', github: 'greylon/clearbooks'
|
54
|
+
```
|
55
|
+
|
56
|
+
## Configuration
|
57
|
+
|
58
|
+
To use the Clearbooks API, you need to get an API key on http://clearbooks.co.uk.
|
59
|
+
|
60
|
+
Login to the site and choose `Settings` > `API`.
|
61
|
+
|
62
|
+
Save the API key in `~/.clearbooks/config.yml`.
|
63
|
+
|
64
|
+
|
65
|
+
```sh
|
66
|
+
$ echo "api_key: {your_api_key}" >> ~/.clearbooks/config.yml
|
67
|
+
```
|
68
|
+
|
69
|
+
Or provide the API key in `ENV['CLEARBOOKS_API_KEY']`
|
70
|
+
|
71
|
+
```sh
|
72
|
+
$ CLEARBOOKS_API_KEY=your_api_key clearbooks
|
73
|
+
```
|
74
|
+
|
75
|
+
Or use `Clearbooks.configure` block:
|
76
|
+
|
77
|
+
```ruby
|
78
|
+
require 'clearbooks'
|
79
|
+
|
80
|
+
Clearbooks.configure do |config|
|
81
|
+
config.api_key = 'your_api_key' # Unless you have key in ~/.clearbooks/config.yml
|
82
|
+
# or ENV['CLEARBOOKS_API_KEY']
|
83
|
+
config.log = true # If you need logging
|
84
|
+
config.logger = Logger.new(STDOUT) # Or any other logger of your choice
|
85
|
+
end
|
86
|
+
```
|
87
|
+
|
88
|
+
## Usage
|
89
|
+
|
90
|
+
### Ruby code
|
91
|
+
|
92
|
+
```ruby
|
93
|
+
|
94
|
+
Clearbooks.list_invoices # returns Array of existing invoices
|
95
|
+
Clearbooks.list_entities # returns Array of existing entities
|
96
|
+
Clearbooks.list_projects # returns Array of existing projects
|
97
|
+
Clearbooks.list_account_codes # returns Array of available account codes
|
98
|
+
|
99
|
+
Clearbooks.create_invoice Clearbooks::Invoice.new(date_created: Date.today,
|
100
|
+
credit_terms: 30,
|
101
|
+
entity_id: 1,
|
102
|
+
type: :purchases,
|
103
|
+
items: [
|
104
|
+
Item.new(description: 'Item 1', unit_price: '9.99',
|
105
|
+
quantity: 5, type: '1001001', vat: 0, vat_rate: '0.00:Out'),
|
106
|
+
Item.new(description: 'Item 2', unit_price: '19.99',
|
107
|
+
quantity: 7, type: '1001001', vat: 0, vat_rate: '0.00:Out')]
|
108
|
+
])
|
109
|
+
```
|
110
|
+
See the API reference below or visit the official Clearbooks site: https://www.clearbooks.co.uk/support/api/docs/soap/
|
111
|
+
|
112
|
+
### Command line
|
113
|
+
Type `clearbooks` or `clearbooks console` in the command line to launch [pry](https://github.com/pry/pry) in context of Clearbooks:
|
114
|
+
```sh
|
115
|
+
$ clearbooks
|
116
|
+
[1] pry(Clearbooks)> list_invoices
|
117
|
+
# ...
|
118
|
+
[1] pry(Clearbooks)> create_invoice Invoice.new(params)
|
119
|
+
# ...
|
120
|
+
[1] pry(Clearbooks)> exit
|
121
|
+
```
|
122
|
+
|
123
|
+
# Clearbooks API reference
|
124
|
+
|
125
|
+
Detailed API reference can be obtained from official Clearbooks site: https://www.clearbooks.co.uk/support/api/docs/soap/
|
126
|
+
|
127
|
+
## Managing invoices
|
128
|
+
|
129
|
+
### Clearbooks.list_invoices
|
130
|
+
|
131
|
+
Example:
|
132
|
+
|
133
|
+
```ruby
|
134
|
+
Clearbooks.list_invoices(
|
135
|
+
id: [1, 2, 3], # Optional. Filter invoices by invoice id
|
136
|
+
entity_id: [1, 2, 3], # Optional. Filter invoices by entity id
|
137
|
+
ledger: :sales, # Optional. One of [:sales, :purchases]
|
138
|
+
status: :all, # Optional. One of
|
139
|
+
# [:draft, :voided, :bad_debt, :valid, :paid, :unpaid,
|
140
|
+
# :credited, :credit_note, :refund, :recurring]
|
141
|
+
modified_since: '2015-01-01', # Optional.
|
142
|
+
offset: 0 # Optional. It returns 100 invoices a time.
|
143
|
+
) # Clearbooks.list_invoices
|
144
|
+
|
145
|
+
# Returns an Array of Invoice objects with attributes according to official API docs.
|
146
|
+
```
|
147
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/listinvoices/
|
148
|
+
|
149
|
+
### Clearbooks.create_invoice
|
150
|
+
|
151
|
+
Example:
|
152
|
+
|
153
|
+
```ruby
|
154
|
+
Clearbooks.create_invoice Clearbooks::Invoice.new(
|
155
|
+
date_created: Date.today, # Reqiured. The tax point of the invoice.
|
156
|
+
date_due: Date.today, # The date the invoice is due.
|
157
|
+
credit_terms: 30, # The number of days after the tax point that the invoice is due.
|
158
|
+
# Either :date_due or :credit_terms is required.
|
159
|
+
entity_id: 1, # Required. The customer or supplier id.
|
160
|
+
date_accrual: Date.today, # Optional. The invoice accrual date.
|
161
|
+
description: 'desc' # Optional.
|
162
|
+
type: :purchases, # Optional. One of [:purchases, :sales, :cn-sales, :cn-purchases]
|
163
|
+
bank_payment_id: 200, # Optional. The bank account code.
|
164
|
+
# Can be extracted from the bank account URL:
|
165
|
+
# 1. Go to Clearbooks site > Money > Bank accounts > All
|
166
|
+
# 2. Click the bank account.
|
167
|
+
# 3. In the address bar you will see the url like:
|
168
|
+
# https://secure.clearbooks.co.uk/company/accounting/banking/statement/7502001/
|
169
|
+
# 4. The last number (7502001) is the bank account code.
|
170
|
+
|
171
|
+
items: [
|
172
|
+
Item.new(
|
173
|
+
description: 'Item 1', # Reqiured.
|
174
|
+
unit_price: '9.99', # Required.
|
175
|
+
quantity: 5, # Required.
|
176
|
+
type: '1001001', # Required. The item account code.
|
177
|
+
# Use Clearbooks.list_account_codes
|
178
|
+
# to get available account codes.
|
179
|
+
vat: 0, # Reqiured.
|
180
|
+
vat_rate: '0.00:Out' # Required.
|
181
|
+
)] # items
|
182
|
+
) # Clearbooks.create_invoice
|
183
|
+
|
184
|
+
# returns a Hash:
|
185
|
+
|
186
|
+
{
|
187
|
+
invoice_id: 1,
|
188
|
+
invoice_prefix: 'INV',
|
189
|
+
invoice_number: '1'
|
190
|
+
}
|
191
|
+
```
|
192
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/createinvoice/
|
193
|
+
|
194
|
+
## Managing entities
|
195
|
+
### Clearbooks.list_entities
|
196
|
+
|
197
|
+
Example:
|
198
|
+
|
199
|
+
```ruby
|
200
|
+
Clearbooks.list_entities(
|
201
|
+
id: [1, 2, 3], # Optional. Filter entities by id.
|
202
|
+
type: :customers, # Optional. One of [:customers, :suppliers]
|
203
|
+
modified_since: '2015-01-01', # Optional.
|
204
|
+
offset: 0 # Optional.
|
205
|
+
) # Clearbooks.list_entities
|
206
|
+
|
207
|
+
# returns an Array of Entity objects with attributes according to official API docs.
|
208
|
+
```
|
209
|
+
|
210
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/list-entities/
|
211
|
+
|
212
|
+
### Clearbooks.create_entity
|
213
|
+
|
214
|
+
Example:
|
215
|
+
|
216
|
+
```ruby
|
217
|
+
Clearbooks.create_entity Clearbooks::Entity.new(
|
218
|
+
company_name: 'Company',
|
219
|
+
contact_name: 'John Doe',
|
220
|
+
supplier: {
|
221
|
+
default_account_code: '1001001', # See Clearbooks.list_account_codes
|
222
|
+
default_credit_terms: 30,
|
223
|
+
default_vat_rate: 0
|
224
|
+
}
|
225
|
+
) # Clearbooks::Entity.new
|
226
|
+
```
|
227
|
+
Full list of options: https://www.clearbooks.co.uk/support/api/docs/soap/createentity/
|
228
|
+
|
229
|
+
### Clearbooks.delete_entity
|
230
|
+
|
231
|
+
Example:
|
232
|
+
```ruby
|
233
|
+
Clearbooks.delete_entity(1) # Delete entity by id.
|
234
|
+
```
|
235
|
+
|
236
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/deleteentity/
|
237
|
+
|
238
|
+
|
239
|
+
## Managing payments
|
240
|
+
### Clearbooks.create_payment
|
241
|
+
|
242
|
+
Example:
|
243
|
+
|
244
|
+
```ruby
|
245
|
+
Clearbooks.create_payment Payment.new(
|
246
|
+
accounting_date: Date.today, # Optional
|
247
|
+
type: :sales, # Optional. One of [:purchases, :sales]
|
248
|
+
description: 'description', # Optional.
|
249
|
+
amount: 19.99, # Optional.
|
250
|
+
entity_id: 1, # Optional.
|
251
|
+
payment_method: 2, # Optional.
|
252
|
+
bank_account: 200, # Optional. See Clearbooks.create_invoice
|
253
|
+
invoices: [ # Optional.
|
254
|
+
{id: 1, amount: 9.99}
|
255
|
+
] # invoices
|
256
|
+
) # Payment.new
|
257
|
+
```
|
258
|
+
|
259
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/createpayment/
|
260
|
+
|
261
|
+
### Clearbooks.allocate_payment
|
262
|
+
|
263
|
+
Example:
|
264
|
+
```ruby
|
265
|
+
Clearbooks.allocate_payment(
|
266
|
+
payment_id: 1, # Reqiured.
|
267
|
+
entity_id: 1, # Required.
|
268
|
+
type: :sales, # Required. One of [:sales, :purchases]
|
269
|
+
invoices: [
|
270
|
+
{id: 1, amount: 9.99}
|
271
|
+
]
|
272
|
+
) # Clearbooks.allocate_payment
|
273
|
+
```
|
274
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/allocatepayment/
|
275
|
+
|
276
|
+
## Managing projects
|
277
|
+
### Clearbooks.list_projects
|
278
|
+
|
279
|
+
Example:
|
280
|
+
|
281
|
+
```ruby
|
282
|
+
Clearbooks.list_projects { offset: 0 }
|
283
|
+
# returns an Array of Project objects with attributes according to official API docs.
|
284
|
+
```
|
285
|
+
|
286
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/listprojects/
|
287
|
+
|
288
|
+
### Clearbooks.create_project
|
289
|
+
|
290
|
+
Example:
|
291
|
+
```ruby
|
292
|
+
Clearbooks.create_project Project.new(
|
293
|
+
description: 'Description', # Required.
|
294
|
+
project_name: 'Project name', # Optional.
|
295
|
+
status: :open # Optional. One of [:open, :closed, :deleted]
|
296
|
+
) # Clearbooks.create_project
|
297
|
+
```
|
298
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/createproject/
|
299
|
+
|
300
|
+
|
301
|
+
## Managing journals
|
302
|
+
### Clearbooks.create_journal
|
303
|
+
|
304
|
+
Example:
|
305
|
+
|
306
|
+
```ruby
|
307
|
+
Clearbooks.create_journal Journal.new(
|
308
|
+
description: 'Desc', # Required.
|
309
|
+
accounting_date: Date.today, # Optional.
|
310
|
+
entity: 1, # Optional.
|
311
|
+
project: 1, # Optional
|
312
|
+
ledgers: [ # Optional
|
313
|
+
{
|
314
|
+
account: '1001001', # Optional. See Clearbooks.list_account_codes
|
315
|
+
amount: 19.99, # Optional.
|
316
|
+
] # ledgers
|
317
|
+
) # Journal.new
|
318
|
+
```
|
319
|
+
|
320
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/createjournal/
|
321
|
+
|
322
|
+
### Clearbooks.delete_journal
|
323
|
+
|
324
|
+
Example:
|
325
|
+
```ruby
|
326
|
+
Clearbooks.delete_journal(1) # Delete journal by id
|
327
|
+
```
|
328
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/deletejournal/
|
329
|
+
|
330
|
+
## Managing account codes
|
331
|
+
### Clearbooks.list_account_codes
|
332
|
+
|
333
|
+
Example:
|
334
|
+
|
335
|
+
```ruby
|
336
|
+
Clearbooks.list_account_codes
|
337
|
+
# returns an Array of AccountCode objects with attributes according to official API docs.
|
338
|
+
```
|
339
|
+
|
340
|
+
Reference: https://www.clearbooks.co.uk/support/api/docs/soap/listaccountcodes/
|
341
|
+
|
342
|
+
## On what Hardware does it run?
|
343
|
+
|
344
|
+
This Software was originally developed and tested on 32-bit x86 / SMP based PCs running on
|
345
|
+
Gentoo GNU/Linux 3.13.x. Other direct Linux and Unix derivates should be viable too as
|
346
|
+
long as all dynamical linking dependencys are met.
|
347
|
+
|
348
|
+
|
349
|
+
## Documentation
|
350
|
+
|
351
|
+
A general developers API guide can be extracted from the Yardoc subdirectory which is able to
|
352
|
+
generate HTML as well as PDF docs. Please refer to the [Rake|Make]file for additional information
|
353
|
+
how to generate this documentation.
|
354
|
+
|
355
|
+
```sh
|
356
|
+
~# rake docs:generate
|
357
|
+
```
|
358
|
+
|
359
|
+
## Software Requirements
|
360
|
+
|
361
|
+
This package was developed and compiled under Gentoo GNU/Linux 3.x with the Ruby 2.x.x.
|
362
|
+
interpreter. It uses several libraries and apps as outlied in the INSTALLING section.
|
363
|
+
|
364
|
+
- e.g. Debian/GNU Linux or Cygwin for MS Windows
|
365
|
+
- Ruby
|
366
|
+
- RVM or Rbenv
|
367
|
+
- Bundler
|
368
|
+
|
369
|
+
## Configuration
|
370
|
+
|
371
|
+
Configuration is handled at run-time via $HOME/.clearbooks/config.yaml file.
|
372
|
+
|
373
|
+
## Build & Packaging
|
374
|
+
|
375
|
+
Package building such as RPM or DEB has not been integrated at this time.
|
376
|
+
|
377
|
+
To build the gem from this repository:
|
378
|
+
|
379
|
+
|
380
|
+
```sh
|
381
|
+
~# rake build
|
382
|
+
~# rake package
|
383
|
+
~# rake install
|
384
|
+
```
|
385
|
+
|
386
|
+
## Development
|
387
|
+
|
388
|
+
#### Software requirements
|
389
|
+
|
390
|
+
This package was developed and compiled under Gentoo GNU/Linux 3.x with the Ruby 2.x.x.
|
391
|
+
interpreter.
|
392
|
+
|
393
|
+
#### Setup
|
394
|
+
|
395
|
+
If you got this package as a packed tar.gz or tar.bz2 please unpack the contents in an appropriate
|
396
|
+
folder e.g. ~/clearbooks/ and follow the supplied INSTALL or README documentation. Please delete or
|
397
|
+
replace existing versions before unpacking/installing new ones.
|
398
|
+
|
399
|
+
Get a copy of current source from SCM
|
400
|
+
|
401
|
+
```sh
|
402
|
+
~# git clone ssh://github.com/greylon/clearbooks.git clearbooks
|
403
|
+
```
|
404
|
+
|
405
|
+
Install RVM (may not apply)
|
406
|
+
|
407
|
+
```sh
|
408
|
+
~# curl -sSL https://get.rvm.io | bash -s stable
|
409
|
+
```
|
410
|
+
|
411
|
+
Make sure to follow install instructions and also integrate it also into your shell. e.g. for ZSH,
|
412
|
+
add this line to your .zshrc.
|
413
|
+
|
414
|
+
```sh
|
415
|
+
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" ;
|
416
|
+
|
417
|
+
or
|
418
|
+
|
419
|
+
~# echo "source /usr/local/rvm/scripts/rvm" >> ~/.zshrc
|
420
|
+
|
421
|
+
```
|
422
|
+
|
423
|
+
or see `http://rvm.io` for more details.
|
424
|
+
|
425
|
+
|
426
|
+
Create proper RVM gemset
|
427
|
+
|
428
|
+
```sh
|
429
|
+
~# rvm --create use 2.2.2@clearbooks_project
|
430
|
+
```
|
431
|
+
|
432
|
+
Install Ruby VM 2.2.2 or better
|
433
|
+
|
434
|
+
```sh
|
435
|
+
~# rvm install 2.2.2
|
436
|
+
```
|
437
|
+
|
438
|
+
Install libraries via bundler
|
439
|
+
|
440
|
+
```sh
|
441
|
+
~# gem install bundler
|
442
|
+
~# bundle
|
443
|
+
```
|
444
|
+
|
445
|
+
#### Rake Tasks
|
446
|
+
|
447
|
+
For a full list of Rake tasks suported, use `rake -T`.
|
448
|
+
|
449
|
+
Here is a current listing of all tasks:
|
450
|
+
|
451
|
+
|
452
|
+
```
|
453
|
+
rake build # Build clearbooks-0.16.3.gem into the pkg directory
|
454
|
+
rake cucumber:pretty # Run Cucumber features
|
455
|
+
rake cucumber:progress # Run Cucumber features
|
456
|
+
rake default # Show the default task when executing rake without arguments
|
457
|
+
rake docs:generate # Generate Yardoc documentation for this project
|
458
|
+
rake docs:graph # Generate Yard Graphs for this project
|
459
|
+
rake guard:default # Execute Ruby Guard
|
460
|
+
rake help # Shows the usage help screen
|
461
|
+
rake install # Build and install clearbooks-0.16.3.gem into system gems
|
462
|
+
rake install:local # Build and install clearbooks-0.16.3.gem into system gems without network access
|
463
|
+
rake man:build # Build the manual pages
|
464
|
+
rake man:clean # Clean up from the built man pages
|
465
|
+
rake measurement:benchmark # When executing rake tasks measure elapsed time, used with other tasks
|
466
|
+
rake measurement:profiling # Run profiling over stack
|
467
|
+
rake metric:metric # Run metric fu for project
|
468
|
+
rake package:clean # Clean all files from pkg folder
|
469
|
+
rake readme # Generate proper README file from templates
|
470
|
+
rake readme:all # Generate proper README file from templates
|
471
|
+
rake readme:subdirs # Builds generates readme files in all sub-directories
|
472
|
+
rake readme:topdir # Generate top level README file from template
|
473
|
+
rake release # Create tag v0.16.3 and build and push clearbooks-0.16.3.gem to Rubygems
|
474
|
+
rake spec # RSpec Core Tasks
|
475
|
+
rake todo # Look for TODO and FIXME tags in the code
|
476
|
+
rake version # Git Tag number of this repo
|
477
|
+
rake yardgraph # Generate Yard Graphs for this project
|
478
|
+
rake yardoc # Generate Yardoc documentation for this project
|
479
|
+
|
480
|
+
```
|
481
|
+
|
482
|
+
#### Thor Tasks
|
483
|
+
|
484
|
+
For a full list of Thor tasks suported, use `thor -T`.
|
485
|
+
|
486
|
+
Here is a current listing of all tasks:
|
487
|
+
|
488
|
+
|
489
|
+
```
|
490
|
+
default
|
491
|
+
-------
|
492
|
+
thor :build # build
|
493
|
+
thor :clean # clean
|
494
|
+
thor :default # Show the default task when executing rake without arguments
|
495
|
+
thor :docs:generate # Generate Yardoc documentation for this project
|
496
|
+
thor :docs:graph # Generate Yard Graphs for this project
|
497
|
+
thor :guard:default # Execute Ruby Guard
|
498
|
+
thor :help # Shows the usage help screen
|
499
|
+
thor :install # Build and install clearbooks-0.16.3 .gem into system gems
|
500
|
+
thor :man:build # Build the manual pages
|
501
|
+
thor :man:clean # Clean up from the built man pages
|
502
|
+
thor :measurement:benchmark # When executing rake tasks measure elapsed time, used with other tasks
|
503
|
+
thor :measurement:profiling # Run profiling over stack
|
504
|
+
thor :metric:metric # Run metric fu for project
|
505
|
+
thor :package:clean # Clean all files from pkg folder
|
506
|
+
thor :readme:all # Generate proper README file from templates
|
507
|
+
thor :readme:subdirs # Builds generates readme files in all sub-directories
|
508
|
+
thor :readme:topdir # Generate top level README file from template
|
509
|
+
thor :release # release
|
510
|
+
thor :spec # Run RSpec code examples
|
511
|
+
thor :todo # Look for TODO and FIXME tags in the code
|
512
|
+
thor :version # Git Tag number of this repo
|
513
|
+
|
514
|
+
info
|
515
|
+
----
|
516
|
+
thor info:overview # Shows system overview
|
517
|
+
|
518
|
+
version
|
519
|
+
-------
|
520
|
+
thor version:show # Show version of this app
|
521
|
+
|
522
|
+
|
523
|
+
```
|
524
|
+
|
525
|
+
## If something goes wrong
|
526
|
+
|
527
|
+
In case you enconter bugs which seem to be related to the package please check in
|
528
|
+
the MAINTAINERS.md file for the associated person in charge and contact him or her directly. If
|
529
|
+
there is no valid address then try to mail Bjoern Rennhak <bjoern AT greylon DOT com> to get
|
530
|
+
some basic assistance in finding the right person in charge of this section of the project.
|
531
|
+
|
532
|
+
## Contributing
|
533
|
+
|
534
|
+
1. Fork it ( https://github.com/greylon/clearbooks/fork )
|
535
|
+
2. Create your feature branch (`git checkout -b my_new_feature`)
|
536
|
+
3. Commit your changes (`git commit -am 'Add some feature'`)
|
537
|
+
4. Push to the branch (`git push origin my_new_feature`)
|
538
|
+
5. Create a new Pull Request
|
539
|
+
|
540
|
+
## Authors
|
541
|
+
|
542
|
+
* [Oleg Kukareka](https://github.com/kukareka)
|
543
|
+
* [Bjoern Rennhak](https://github.com/rennhak)
|
544
|
+
|
545
|
+
## Copyright & License
|
546
|
+
|
547
|
+
Please refer to the COPYING.md and LICENSE.md file.
|
548
|
+
Unless otherwise stated in those files all remains protected and copyrighted by Bjoern Rennhak
|
549
|
+
(bjoern AT greylon DOT com).
|