Warning! Construction underway! Amatino is in an 'alpha' state. Not all features are operational. See roadmap

Primary
Account
Entity
Object
Create
Retrieve
Update
Delete
Restore
Derived
Balance
Ledger
Performance
Position
Recursive Balance
Recursive Ledger
Tree
Ancillary
Custom Unit
Entry
Global Unit
Global Unit List
Ledger Row
Session
Side
Tx Version List
Tree Node
Type
User

Transaction

A Transaction is an exchange of value between two or more Accounts. For example, the raising of an invoice, the incrurring of a liability, or the receipt of a payment. Many Transactions together, each touching the same Account, form an Account Ledger, and the cumulative sum of the Transactions form an Account Balance.

Transactions are composed of Entries, each of which includes a debit or credit (The fundamental Sides). The sum of all debits and credits in all the Entries that compose a Transaction must always equal zero.

Transactions may be retrieved and created in arbitrary units, either a Global Units or Custom Units. Amatino will transparently handle all unit conversions. For example, a Transaction could be created in Australian Dollars, touch an Account denominated in Pounds Sterling, and be retrieved in Bitcoin.

The Transaction Object

When returning a Transaction to you, Amatino uses the following JSON object structure.

Root Type

JSON Array

Object Structure

description A unique identifier for this transaction within the Entity
key "transaction_id"
example 95348572
type JSON Number
description The time at UTC that the transaction occured, in the format YYYY-MM-DD_HH24:MI:SS.US
key "transaction_time"
example 2017-01-07_17:22:16.51245
type JSON String
description The time at UTC when the transaction was stored in Amatino, in the format YYYY-MM-DD_HH24:MI:SS.US
key "version_time"
example "2018-01-31_20:45:42.02001"
type JSON String
description A description of the transaction
key "description"
example "Receipt of payment for exquisite accounting services"
type JSON String
description Incrementing integer recording the version of the transaction
key "version"
example 4
type JSON Number
description The global unit denomination of this transaction, if one exists
key "global_unit_denomination"
example 5
type JSON Number or JSON Null
description The custom unit denomination of this transaction, if one exists
key "custom_unit_denomination"
example null
type JSON Number or JSON Null
description The integer identifier of the Amatino user account that authored this version of the transaction
key "author"
example 76
type JSON Number
description A boolean indication of whether this transaction is in a deleted state (false) or an active state (true)
key "active"
example True
type JSON Boolean
description A list of Entry objects party to this transaction
minimum length 2
listed_object Entry
key "entries"
maximum length 100
type JSON Array

Create Transaction

API Path /transactions
HTTP Method POST
Description Descr. Create a new entity or entities

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The entity id of the entity in which you wish to store the transaction
Example oB3cjSNKXklkJ4Tb
Repeatable No

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

description Time at which the transaction occured, or is to occur, in the format YYYY-MM-DD_HH24:MI:SS.US
key "transaction_time"
example "2017-01-17_17:22:16.51245"
type JSON String
max char length 1024
description A friendly description of the transaction
key "description"
example Receipt of payment for exquisite accounting services
type JSON String
description The ID of the global unit in which this transaction is denominated, if desired. Either a custom or global unit must be specified.
key "global_unit_denomination"
example 5
source /units/list
type JSON Number or JSON Null
description The ID of the custom unit in which this transaction is denominated, if desired. Either a custom or global unit must be specified.
key "custom_unit_denomination"
example null
source /custom_units/list
type JSON Number or JSON Null
description A list of Entry objects that comprise the transaction
minimum length 2
example See Entries
key "entries"
list objects Entry
maximum length 100
type JSON String or JSON Null

Returns

Root Type

JSON Array

Object

Transaction

Retrieve Transaction

API Path /transactions
HTTP Method GET
Description Descr. Retrieve a transaction or transactions

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The entity id of the entity from which you wish to retrieve a transaction
Example oB3cjSNKXklkJ4Tb
Repeatable No

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

description The unique integer identifier of the transaction within the target entity
key "transaction_id"
example 512415
type JSON Number
description The global unit denomination in which you would like to view the transaction, if desired. Specify JSON Null both here and in the custom unit to retrieve the transaction in the underlying account unit.
key "global_unit_denomination"
example "eur"
source /units/list
type JSON String or JSON Null
description The custom unit denomination in which you would like to view the transaction, if desired. Specify JSON Null both here and in the custom unit to retrieve the transaction in the underlying account unit.
key "custom_unit_denomination"
example "btc"
source /custom_units/list
type JSON String or JSON Null
description The integer version identifier of the version of the transaction you wish to retrieve. Specify JSON Null to retrieve the latest version.
key "version"
example 12
source '/transactions/version/list'
type JSON Number or JSON Null

Returns

Root Type

JSON Array

Object

Transaction

Update Transaction

API Path /transactions
HTTP Method PUT
Description Descr. Update an existing transaction or transaction

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

None.

Required JSON Data

Root type

JSON Array

Max Array Length

10

Object Structure

description The unique integer identifier of the transaction you wish to update
key "transaction_id"
example 512415
type JSON Number
description Time at which the transaction occured, or is to occur, in the format YYYY-MM-DD_HH24:MI:SS.US
key "transaction_time"
example "2017-01-07_17:22:16.51245"
type JSON String
max char length 1024
description A friendly description of the transaction
key "description"
example Receipt of payment for exquisite accounting services
type JSON String
description The global unit in which this transaction is denominated, if desired. Either a custom or global unit must be specified.
key "global_unit_denomination"
example "usd"
source /units/list
type JSON String or JSON Null
description The custom unit in which this transaction is denominated, if desired. Either a custom or global unit must be specified.
key "custom_unit_denomination"
example "xrp"
source /custom_unit/list
type JSON String or JSON Null
description A list of entry objects that comprise the transaction
minimum length 2
example See Entries
key "entries"
list objects Entry
maximum length 100
type JSON String or JSON Null

Returns

Root Type

JSON Array

Object

Transaction

Delete Transaction

API Path /transactions
HTTP Method DELETE
Description Descr. Delete an entity or entities

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The entity id of the entity in which you wish to delete transactions
Example oB3cjSNKXklkJ4Tb
Repeatable No
Key transaction_id
Type Integer
Description Descr. The transaction id or ids of the transaction(s) you wish to delete
Example 151
Repeatable Yes

Required JSON Data

None.

Returns

Root Type

JSON Array

Object

Transaction

Restore Transaction

API Path /transactions
HTTP Method PATCH
Description Descr. Restore a deleted transaction or transactions

Required Headers

Key X-Signature
Value Your Session signature
Example "yxATCPRKAAXHNiPctNQPHEGGVJF"...
Key X-Session-ID
Value An an integer Session ID
Example 7449059267091272858

Required URL Parameters

Key entity_id
Type string
Description Descr. The id of the entity in which you would like to restore transactions
Example oB3cjSNKXklkJ4Tb
Repeatable No
Key transaction_id
Type Integer
Description Descr. The transaction id or ids of the transaction(s) you wish to restore
Example 151
Repeatable Yes

Required JSON Data

None.

Returns

Root Type

Object

Transaction