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

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

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

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

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

type JSON Number
key "transaction_id"
example 512415
description The unique integer identifier of the transaction within the target entity
type JSON String or JSON Null
source /units/list
key "global_unit_denomination"
example "eur"
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.
type JSON String or JSON Null
source /custom_units/list
key "custom_unit_denomination"
example "btc"
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.
type JSON Number or JSON Null
source '/transactions/version/list'
key "version"
example 12
description The integer version identifier of the version of the transaction you wish to retrieve. Specify JSON Null to retrieve the latest version.

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

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

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