clearbooks 0.16.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|
+
[](http://badge.fury.io/rb/clearbooks)
|
5
|
+
[](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).
|