create_object(name, url) | CREATES a single object in Vingd Object registry. |
create_order(oid, price[, context, expires]) | CREATES a single order for object oid, with price set to price and validity until expires. |
verify_purchase(oid, tid) | VERIFIES token tid and returns token data associated with tid and bound to object oid. |
commit_purchase(purchaseid, transferid) | DECLARES a purchase defined with purchaseid (bound to vingd transfer referenced by transferid) as finished, with user being granted the access to the service or goods. |
create_voucher(amount[, expires, message, gid]) | CREATES a new preallocated voucher with amount vingd cents reserved until expires. |
revoke_vouchers([vid_encoded, uid_from, ...]) | REVOKES/INVALIDATES a filtered list of vouchers. |
reward_user(huid_to, amount[, description]) | PERFORMS a single reward. |
Creates Vingd user (profile & account), links it with the provided identities (to be verified later), and sets the delegate-user permissions (creator being the delegate). Returns Vingd user’s huid (hashed user id).
Example:
vingd.authorized_create_user(
identities={"facebook": "12312312", "mail": "user@example.com"},
primary="facebook",
permissions=["get.account.balance", "purchase.object"]
)
If identities and primary are unspecified, a “zombie” (“headless”) account is created (i.e. account with no identities associated, user-unreachable).
Return type: | dict |
---|---|
Returns: | {'huid': <huid>} |
Raises GeneralException: | |
Resource: | id/objects/<oid>/purchases |
Access: | authorized users with ACL flag user.create |
FETCHES the account balance for the user defined with huid.
Return type: | bigint |
---|---|
Returns: | <amount_in_cents> |
Raises GeneralException: | |
Resource: | fort/accounts/<huid> |
Access: | authorized users; delegate permission required for the requester to read user’s balance: get.account.balance |
Does delegated (pre-authorized) purchase of oid in the name of huid, at price price (vingd transferred from huid to consumer’s acc).
Raises GeneralException: | |
---|---|
Resource: | objects/<oid>/purchases |
Access: | authorized users with ACL flag purchase.object.authorize + delegate permission required for the requester to charge the user: purchase.object |
DECLARES a purchase defined with purchaseid (bound to vingd transfer referenced by transferid) as finished, with user being granted the access to the service or goods.
If seller fails to commit the purchase, the user (buyer) shall be refunded full amount paid (reserved).
Parameters: |
|
---|---|
Return type: | dict |
Returns: | {'ok': <boolean>}. |
Raises: |
|
See: | verify_purchase. |
Resource: | purchases/<purchaseid> |
Access: | authorized users (ACL flag: type.business) |
CREATES a single object in Vingd Object registry.
Parameters: |
|
---|---|
Return type: | bigint |
Returns: | Object ID for the newly created object. |
:raises GeneralException:s
Resource: | registry/objects/ |
---|---|
Access: | authorized users |
CREATES a single order for object oid, with price set to price and validity until expires.
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Order dictionary: order = {
'id': <order_id>,
'expires': <order_expiry>,
'context': <purchase_context>,
'object': {
'id': <oid>,
'price': <amount_in_cents>
},
'urls': {
'redirect': <url_for_failsafe_redirect_purchase_mode>,
'popup': <url_for_popup_purchase_mode>
}
}
|
Raises GeneralException: | |
Resource: | objects/<oid>/orders/ |
Access: | authorized users |
CREATES a new preallocated voucher with amount vingd cents reserved until expires.
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Created voucher description: voucher = {
'vid': <voucher_integer_id>,
'vid_encoded': <voucher_string_id>,
'amount_allocated': <int_cents | None if not allocated>,
'amount_vouched': <int_cents>,
'id_fort_transfer': <id_of_allocating_transfer |
None if not allocated>,
'fee': <int_cents>,
'uid_from': <source_account_uid>,
'uid_proxy': <broker_id>,
'uid_to': <destination_account_id | None if not given>,
'gid': <voucher_group_id | None if undefined>,
'ts_valid_until': <iso8601_timestamp_absolute>,
'description': <string | None>,
'message': <string | None>
}
combined with voucher redeem urls on Vingd frontend. |
Raises GeneralException: | |
Resource: | vouchers/ |
Access: | authorized users (ACL flag: voucher.add) |
FETCHES the account balance for the authenticated user.
Return type: | bigint |
---|---|
Returns: | <amount_in_cents> |
Raises GeneralException: | |
Resource: | fort/accounts/ |
Access: | authorized users; authenticated user’s account data will be fetched |
FETCHES a single object, referenced by its oid.
Parameters: | oid (bigint) – Object ID |
---|---|
Return type: | dict |
Returns: | The object description dictionary. |
Raises GeneralException: | |
Note: | get_objects can be used instead, but then specifying any other (conflicting) constraint (except oid) yields a non-existing resource exception (NotFound). |
Resource: | registry/objects/<oid> |
Access: | authorized users (only objects owned by the authenticated user are returned) |
FETCHES a filtered collection of objects created by the authenticated user.
Parameters: |
|
---|---|
Return type: | list/dict |
Returns: | A list of object description dictionaries. If oid is specified, a single dictionary is returned instead of a list. |
Raises GeneralException: | |
Resource: | registry/objects[/<oid>] [/since=<since>][/until=<until>][/last=<last>][/first=<first>] |
Access: | authorized users (only objects owned by the authenticated user are returned) |
FETCHES a single order defined with orderid, or fails if order is non-existing (with NotFound).
Parameters: | orderid (bigint) – Order ID |
---|---|
Return type: | dict |
Returns: | The order description dictionary. |
Raises GeneralException: | |
See: | get_orders (orderid=...) |
Resource: | orders/<orderid> |
Access: | authorized users (authenticated user MUST be the object/order owner) |
FETCHES filtered orders. All arguments are optional.
Parameters: |
|
---|---|
Return type: | list/dict |
Returns: | (A list of) order(s) description dictionary(ies). |
Raises GeneralException: | |
Resource: | [objects/<oid>/]orders/[<all>/]<orderid> |
Access: | authorized users (authenticated user MUST be the object/order owner) |
FETCHES profile dictionary of the authenticated user.
Return type: | dict |
---|---|
Returns: | A single user description dictionary. |
Raises GeneralException: | |
Resource: | /id/users/<uid> |
Access: | authorized users; only authenticated user’s metadata can be fetched (UID is automatically set to the authenticated user’s UID) |
FETCHES a filtered list of vouchers.
Parameters: |
|
---|---|
Note: | If first or last are used, the vouchers list is sorted by time created, otherwise it is sorted alphabetically by vid_encoded. |
Return type: | list/dict |
Returns: | A list of voucher description dictionaries. If vid_encoded is specified, a single dictionary is returned instead of a list. |
Raises GeneralException: | |
Resource: | vouchers[/<vid_encoded>][/from=<uid_from>][/to=<uid_to>] [/valid_after=<valid_after>][/valid_before=<valid_before>] [/last=<last>][/first=<first>] |
Access: | authorized users (ACL flag: voucher.get) |
FETCHES a filtered list of vouchers log entries.
Parameters: |
|
---|---|
Note: | If first or last are used, the vouchers list is sorted by time created, otherwise it is sorted alphabetically by id. |
Return type: | list/dict |
Returns: | A list of voucher log description dictionaries. |
Raises GeneralException: | |
Resource: | vouchers/history[/<vid_encoded>][/from=<uid_from>][/to=<uid_to>] [/vid=<vid>][/action=<action>][/last=<last>][/first=<first>] [/valid_after=<valid_after>][/valid_before=<valid_before>] [/create_after=<create_after>][/create_before=<create_before>] [/gid=<group_id>] |
Access: | authorized users (ACL flag: voucher.history) |
Key-value query url builder (of the form: “base/v0/k1=v1/k2=v2”).
Generic Vingd-backend authenticated request (currently HTTP Basic Auth over HTTPS, but OAuth1 in the future).
Returns: | Data dict, or raises exception. |
---|
REVOKES/INVALIDATES a filtered list of vouchers.
Parameters: |
|
---|---|
Note: | As with get_vouchers, filters are restrictive, narrowing down the set of vouchers, which initially includes complete voucher collection. That means, in turn, that a naive empty-handed revoke_vouchers() call shall revoke all un-used vouchers (both valid and expired)! |
Return type: | dict |
Returns: | A dictionary of successfully revoked vouchers, i.e. a map vid_encoded: refund_transfer_id for all successfully revoked vouchers. |
Raises GeneralException: | |
Resource: | vouchers[/<vid_encoded>][/from=<uid_from>][/to=<uid_to>] [/valid_after=<valid_after>][/valid_before=<valid_before>] [/last=<last>][/first=<first>] |
Access: | authorized users (ACL flag: voucher.revoke) |
PERFORMS a single reward. User defined with huid_to is rewarded with amount cents, transfered from the account of the authenticated user.
Parameters: |
|
||||
---|---|---|---|---|---|
Return type: | dict |
||||
Returns: | {'transfer_id': <transfer_id>} Fort Transfer ID packed inside a dict. |
||||
Raises: |
|
||||
Resource: | rewards/ |
||||
Access: | authorized users (ACL flag: transfer.outbound) |
UPDATES a single object in Vingd Object registry.
Parameters: |
|
---|---|
Return type: | bigint |
Returns: | Object ID of the updated object. |
Raises GeneralException: | |
Resource: | registry/objects/<oid>/ |
Access: | authorized user MUST be the object owner |
VERIFIES token tid and returns token data associated with tid and bound to object oid. At the same time decrements entitlement validity counter for oid and uid bound to this token.
Parameters: |
|
---|---|
Return type: | dict |
Returns: | A single token data dictionary: token = {
"object": <object_name>,
"huid": <hashed_user_id_bound_to_seller> / None,
"context": <order_context> / None,
...
}
where:
|
Raises: |
|
See: | commit_purchase. |
Resource: | objects/<oid>/tokens/<tid> |
Access: | authenticated user MUST be the object’s owner |
General exception signifies that an Vingd error has been caught, but reasons/details were not understood/propagated well enough.
Verification of user data failed.
User’s request resulted with a forbidden action and was therefore cancelled.
User’s request did not yield any reasonable result.
Internal server error: it’s our fault. :)