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
Entity List
Entry
Global Unit
Global Unit List
Ledger Row
Price
Session
Side
Tx Version List
Tree Node
Type
User
User List

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

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

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

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