Ubiregi API allows third parties to develop systems which interact with Ubiregi data, including menus, tags, customers, and checkouts.
Using Ubiregi API, you can develop your own application for:
and, such features essential for your or your clients' business.
Ubiregi API provides almost full access to Ubiregi's data. Everything except authentication is the same with what the Ubiregi app is doing. (In fact, the API v3 is essentially more powerful than API v2, which is used by Ubiregi 2.x)
Methods to retrieve data from the Ubiregi API requires a GET request. Methods to create new things requires a POST request. And to update things requires a PUT request. Most methods requires a particular HTTP method and will return an error if you do not make your request with the correct one.
The API is almost RESTful. Every operations are update of attributes of resources.
We use Ruby on Rails to develop ubiregi.com web app. You may find something odd our api. It should be because of Rails requirements.
We carefully described things non-rails-developer should mention about, but may be insufficient. If you have some problem, you may need to check Rails related documents.
We use JSON for every structured data. It implies that binary data are encoded with base64 and non-ascii characters are UTF8 encoded.
POST request should be send with HTTP header Content-Type: application/json.
All requests to Ubiregi API must be HTTPS requests.
Ubiregi API provides very simple authentication mechanism using pre-shared token. This way is recommended to start developing your own apps which is integrated with Ubiregi. However, if you are planning to allow many users to use your app, it is recommended to use OAuth2 for authentication.
Ubiregi users can generate API access tokens, in Ubiregi web app.
新しく作成 button of APIアクセストークン section作成 button表示 button of new added item on the page to see the token stringYour user, who is trying to use your app with a Ubiregi account, have to share the token with your app. The simplest way to do that should be the following.
Put the following http request header in all your API requests.
X-Ubiregi-Auth-Token |
The authentication token of the user for your app installation. This is used for authentication. |
|---|
There is no expiration. The exception is when your user explicitly canceled the authorization to your app.
Ubiregi API access is managed in the OAuth2 manner. You should consult to OAuth2 spec for details.
Visit Ubiregi Developer Dashboard to register your app.
https redirect URI (http can be used; although it is not recommended.)
Make your user's UA to access at https://ubiregi.com/oauth2/authorize endpoint.
The endpoint accepts several query parameters.
| client_id | Your client's ID (OAuth2) |
|---|---|
| state | To pass a parameter to your callback. (OAuth2) |
| force_login | Give true if you want your user to input their username and password. (Default: false) |
| force_authorize | Give true if you want your user to click "Authorize" button before your app got authorized. (Default: false; if your user is trying to authorize your app again, it skips to prompt "Authorize" button.) |
| mobile | Give true if your user's UA is mobile device (small screen). (Default: false) |
https://ubiregi.com/oauth2/token is the token endpoint.
POST HTTP request following OAuth2 protocol to:
The token endpoint access response is a JSON object like the following.
{
"access_token": $token,
"token_type": "bearer",
"expires_in": $seconds,
"refresh_token": $token,
"refresh_token_expires_in": $seconds,
"account_id": $account_id
}
Most fields are ones of OAuth2, but refresh_token_expires_in and account_id are extension by Ubiregi API.
bearer.Access token and refresh token will expire. Access token expiration is in 24 hours, and refresh token expiration is in 14 days in current implementation. This is just because of implementation. We may change them.
POST a request with grant_type=authorization_code to obtain an access_token.
This is standard OAuth2 request and other parameters specified by OAuth2 will be accepted.
Ubiregi API issues new access token for each authorization_code request.
This might be annoying to your client since one account may have many access tokens.
account_id field is a remedy to this.
Invalidate all access tokens associated with the account_id already issued and stored in your database, and you can keep your DB clean.
POST a request with grant_type=refresh_token to refresh an access_token.
This is standard OAuth2 request and other parameters specified by OAuth2 will be accepted.
It is completely okay if you refresh your token even if it is not expired. It invalidates the old access token, and issues new access token and refresh token pair.
Give an Authorization HTTP request header in the following syntax.
Authorization: Bearer 2948or823934y8w9dfit834
If the token is invalid or expired, the request will result in 401 and WWW-Authenticate header will be Bearer error="invalid_token".
You may refresh access token using refresh token previously issued.
paid_at and closed.
paid_at is less than 3 days (72 hours) ago from t is visible, even if they are expired.The definition of checkout visibility is described in the following figure. Green and gray dots are visible and invisible checkouts respectively (assume all checkouts are closed). Group of visible checkouts in left is because the existence of a subscription. Another group of visible checkouts in right is because its paid_at is new.
These definitions about checkout visibility may cause a problem, when your user’s account is expired and your user is using CRM. Customer’s history may have a reference to invisible checkouts.
The field definition may have following attributes:
readonlyCalculation of the value of the field is a task of server. Client can not set the value.
writeonlyThe server never send the value of the attribute.
immutableThe client may post the value on creating a object, but it can not update the value once the object is created.
We use the following meta variables in the JSON examples.
sMost resource collections provides the following set of APIs.
Indexing actions take a set of parameters; since, until, and glb.
They are used to limit the size of the result sets.
since |
Limits the result set to contain only updated items since the parameter. |
|---|---|
until |
Limits the result set to reject items updated since the parameter. |
glb |
Greatest lower bound of id of the result set. This is used to retrieve next batch of the collection. |
limit |
Limits the number of objects contained in the result set. |
verbose=true |
Retrieve optional information of the resource. You are able to use this parameter in the indexing actions related to |
image=blob |
Retrieve Base64 encoded image if the resource has image data such as |
total_count=true |
Retrieve the number of objects which is actially contained in the result set. By using this parameter, You can know the total count of reccords without reading whole collection. |
The result set can be described as follows:
{ item | since ≤ item.updated_at ⋀ item.updated_at < until ⋀ glb < item.id }
The items are sorted by their ids.
The result will be on following pattern.
{
"timestamp": timestamp,
"next-url": url,
"last_updated_at": timestamp,
rows: [ objects ]
}
The timestamp value that it should be passed as a since query parameter in the next batch request. If until parameter is specified, timestamp will be the requested until.
timestamp instead.
Array of objects. The name will be different, items for MenuItems, categories for Categories, and checkouts for Checkouts.
verbose=true |
Retrieve optional information about the resource. You are able to use this parameter in the actions related to |
|---|---|
image=blob |
Retrieve Base64 encoded image if the resource has image data such as |
There are limitation on the number of objects contained in one request; this is the reason we accept glb parameter. You might have a question that how to get the whole collection? A set of requests to fetch collections can be interleaved by requests which updates objects which is contained in the collection. In that case, the updated_at field will be updated and because of the until parameter included in the fetch request, the updated objects can not be fetched.
last_updated_at field is to handle such case. If there are no next-url field sent, which means there are no more object for the parameters you specified, check if the timestamp field is newer than last_updated_at.
until and glb parameters.next-url field.next-url and go step 2 again.since = timestamp, and go step 2 again.POST actions to collection create or update more than one items. This helps to make updating many items faster.
The request will be like the following:
[
{ "name": "new object", ... },
{ "name": "another new object", ...},
{ "id": 123, "name": "object to be updated" }
]
id field in an object, it will create new item.id field in an object, it will update an existing item.The post action is transactional. If there are an error processing an item, all creation or update of items will be canceled. There will be one of everything ok or nothing changed.
There is no limitation on number of objects in one request, but you should take care of it. 100 items in a request will be ok. 10,000 items in a request should cause a problem. We will ask you to stop posting too big request, if there are some problem.
ch1#object-account AccountAccount object represents an Ubiregi account. This is one of the most fat object such that it has most related data with the account including tables, cashiers, payment types. Fetching an Account object should be the entry point for most API clients.
Account objects are readonly. There are no API to update.
"JPY", "USD", "Unknown 2", and "Unknown 3".6, the date changes at 6 AM, ie 2012年01月01日T05:59:00Z is December 31, 2011 (If the timezone is UTC).
Menu.Tables.CustomerTags.PaymentTypes.Cashiers.PriceBooks."plain"(default), "down" or "up""plain"(default), "down" or "up""checkout"(default) or "checkout_item"{
"id": 123,
"created_at": "2011年12月31日:00:00:31Z",
"updated_at": "2012年01月30日:00:30:11Z",
"login": "ubiregi-cafe",
"email": "cafe@ubiregi.com",
"name": "Ubiregi Cafe",
"expire_at": "2011年11月13日T00:00:00Z",
"subscription": "trial",
"currency": "JPY",
"date_offset": 6,
"timezone": "Asia/Tokyo",
"receipt_title": "RECEIPT",
"receipt_footer": "Footer to be printed in receipts",
"receipt_logo": $base64Encoded,
"menus": [ 8 ],
"tables": [ $tables ],
"customer_tags": [ $customer_tags ],
"payment_types": [ $payment_types ],
"cashiers": [ $cashiers ],
"parent_ids": [ 100 ],
"child_ids": [ 200, 124 ],
"sibling_ids": [ 100, 2031, 581 ],
"price_books": [ $price_books ],
"calculation_option": {
"tax_rounding_mode": "down",
"price_rounding_mode": "plain",
"tax_calculation_level": "checkout"
}
}
Retrieves an Account object with account_id.
account_id can be either the ID of account or an string "current". If "current" is specified, it is understood as the ID of current account.
GET /accounts/133 GET /accounts/current
{
"account": $account,
"timestamp": "2011年11月02日T09:11:34Z"
}
The access is only allowed to current, parent, and child accounts. In other case, your request will result in 404 (not found) error.
Table object is deprecated. It is working now but will be obsoleted soon.
Table objects represent tables. Table is special mark for restaurants tables. However, it will be deprecated soon. Using CustomerTag instead of Table is encouraged.
Since it will soon be deprecated, there are no API to update. The only way to edit Table is logging in to the Ubiregi web app.
Retrieving Tables can be done through Account objects.
{
"id": 123,
"name": "Table 1"
}
Tags to give various information on checkouts. This can be used to record that the customer is 20th girl, they came for dating, and so on.
null in the case the tag is inactive.
The interpretation depends on client, however the value should be from 1 to 12.
There is no validation on ubiregi.com server on the uniqueness of position.
image/png.{
"id": 123,
"name": "Dating",
"position": null,
"icon": $base64Encoded,
"icon_mime": "image/png"
}
Icons can be set through icon_name attribute. The value of icon_name should be one of the following list.
*** FIXME ***
Icons are sent from server as its binary image in Base64 encoded form.
Thus, icon_name is a writeonly attribute and icon and icon_mime are readonly attributes.
Update the customer_tags of an account specified by account_id.
{
"customer_tags": [
{
"name": "Dating",
"position": 10,
"icon_name": "F1",
},
{
"id": 31,
"position": null,
}
]
}
CustomerTag objects.
{
"timestamp": "2011年11月02日T09:11:12Z",
"customer_tags" : $customer_tags
}
CustomerTags defined.
Cashier object represents the person who operated the cash register.
true if the cashier is enabled. false if the cashier is disabled."image/png" or "image/jpeg".{
"id": 385,
"name": "Soutaro Matsumoto",
"enabled": true,
"icon": $base64Encoded,
"icon_mime": "image/png"
}
Update the cashiers of an account specified by :account_id. The child account’s cashiers can be updated by parents.
{
"cashiers": [
{
"name": "New cashier",
"enabled":true,
"icon":$base64Encoded
},
{
"id": 1,
"enabled": false
}
]
}
Cashier objects to be updated/created.
null, the icon will be removed.
{
"timestamp": "2011年11月02日T09:11:12Z",
"cashiers" : $cashiers
}
Cashiers.
PaymentType represents how the bill is payed by; cash? or credit card?
null in the case the payment methods is disabled.
true if customers will receive change.
"cash", "card", or "other".
"cash" kind payment type exists in all accounts.
{
"id": 111,
"name": "Credit card",
"position": 3,
"change": true,
"kind": "card"
}
Change payment type of the account specified by :account_id.
{
"payment_types": [
{
"name": "Book Coupon",
"enabled":true,
"change": true,
"kind": "other"
},
{
"id": 123,
"change": false
}
]
}
PaymentType objects to update/create.
{
"timestamp": "2012年02月14日T09:00:00Z",
"payment_types" : $payment_types
}
Category is set of MenuItems to organize and help user to input checkouts.
null if the category is disabled.
{
"id": 371,
"name": "Coke",
"position": 1021,
"price_books": [ $price_books ]
}
Retrieves Categorys defined in menu specified by menu_id.
GET /menus/13/categories?since=2011年01月01日T18:00:13Z
{
"timestamp": "2012年01月03日T03:11:03Z",
"next-url": "https://ubiregi.com/api/3/menus/13/categories?since=2011年01月01日T18:00:13Z&until=2011年01月03日T03:11:03Z&glb=13476",
"last_updated_at": "2012年01月02日T21:14:08Z",
"categories": [ $categories ]
}
Update/Create the categories of the menu specified by menu_id.
{
"categories": [
{
"name": "Soft drinks",
"position": 102,
"price_book_ids": [100, 101]
},
{
"id": 1022,
"position": null
}
]
}
Category objects to be updated/created.
{
"timestamp": "2011年11月02日T09:11:12Z",
"categories" : [ $categories ]
}
Item in menus, which represents one product/service you sell.
variation value is appended unless group parameter is true."intax", "outtax", "percentage", "nosales" and "discount".
"intax" is used for normal items, such that the VAT is included in the price.
"outtax" is to mark that the VAT is not included in the price.
"percentage" is for discounting/premiums.
If "20" is the price of the item and the price_type is "percentage", the price is 20% of premier.
"nosales" is mark that the total sales with this item is not included in sales.
"discount" is used for discounting items.
price_type is "intax" or "outtax".
null if the item is disabled.
null if the item is disabled.
StockEvents.
Stock will not be updated unless inventory management feature is enabled.
StockEvents.
group parameter is true.
group parameter is true.
PriceBookEntry.
{
"id": 271,
"sku": "sku",
"name": "Coke",
"price_type": "intax",
"price": "105",
"vat": 5,
"position": 102,
"category_id": 105,
"stock": 103,
"last_inventory_at": "2012年02月13日T14:00:31Z",
"incoming_stock": 13,
"annotations": [],
"price_book_entries":[
{ $price_books_entry }
]
}
MenuItem can be annotated. Annotation is a pair of two strings, name and value. One MenuItem can have several annotations.
To put annotations to a menu item, POST json data with expected annotations.
{
"id": 271,
...
"annotations": [
{ "name": "name1", "value": "..." },
{ "name": "name2", "value": "..." }
]
}
Annotations not included in the POSTed "annotations" array will be removed. If you does not post "annotations" attribute, no annotations will be updated.
MenuItem with the annotation of value "X" will be ignored to calculate number of points for Rpoint card. "X" is the only one value allowed for this annotation.
{ "name": "rpoint:annotation", value: "X" }
`MenuItem` may take an optional group parameter.
group |
Set group=true to include group/variation fields in response. |
|---|
{
"id": 271,
...
"group": "Casual wear/T-shurt",
"variation": "red"
}
Retrieves the MenuItems defined in menu specified by menu_id.
GET /menus/13/items?since=2011年01月01日T18:00:13Z GET /menus/13/items?sku=item12345 GET /menus/13/items?id=123
{
"timestamp": "2012年01月03日T03:11:03Z",
"next-url": "https://ubiregi.com/api/3/menus/13/items?since=2011年01月01日T18:00:13Z&until=2011年01月03日T03:11:03Z&glb=13476",
"last_updated_at": "2012年01月02日T21:14:08Z",
"items": [ $menu_items ]
}
Update/Create the menu item of the menu specified by :menu_id.
{
"items": [
{
"sku": "new_sku",
"name": "New menu item",
"price_type":"intax",
"price": "1000",
"vat": 5,
"position": 102,
"category_id": 105
},
{
"id": 1022,
"name": "Renamed menu item",
"price_type":"percentage",
"price": "1500",
"position": 103,
}
]
}
MenuItem objects to be updated/created.
{
"timestamp": "2011年11月02日T09:11:12Z",
"items" : $items
}
PriceBook object represents an Ubiregi price book.
{
"id": 123,
"account_id": 9744,
"name": "Take Out",
"tax_rate": "8.0",
"receipt_symbol": "※(注記)",
"receipt_text": "※(注記)印は軽減税率対象商品",
"tax_type": null,
"position": 1,
"valid_since": "2019年10月01日",
"valid_until": "2020年09月30日"
}
PriceBookEntry object represents an Ubiregi price book entry.
{
"id": 123,
"price_book_id": 12,
"price": 10000
}
Event object related to stock control. The object is used to tell someone that stock-related event has occured. Type of a stock event is either "inventory", "arrival", "shipping", or "order".
app_created_at."inventory", "arrival", "shipping", and "order".true or false.null if there is no checkout to be associated with.
{
"id" : 1,
"menu_item_id" : 2,
"app_created_at" : "2012年02月14日T00:00:00Z",
"inventory_at" : "2012年02月14日T01:00:00Z",
"event_type" : "arrival",
"amount" : 55,
"guid" : $UUID-like-sequence,
"body" : { "note" : "This object represents that 55 items specified by `menu_item_id` has arrived" },
"deleted": false,
"checkout_guid": $UUID-like-sequence
}
The interpretation of amount depends on the event’s event_type.
Assume there is a StockEvent object with amount = 55. It says the following facts depending on event_type:
GET /accounts/current/stocks/events?since=...
{
"timestamp": "2011年11月02日T09:11:34Z",
"next-url": "https://ubiregi.com/api/3/accounts/1032/stocks/events?since=.....",
"last_updated_at": "2011年12月31日T00:00:31Z",
"events": [ $stock_events ]
}
Create StockEvent objects of Account specified by account_id. Since there is no mutable field in StockEvent, it is impossible to update.
{
"events": [
{
"menu_item_id" : 21,
"app_created_at" : "2012年02月14日T00:00:00Z",
"inventory_at" : "2012年02月14日T01:00:00Z",
"event_type" : "arrival",
"amount" : 55,
"guid" : $UUID-like-sequence,
"body" : {
"author": "Soutaro Matsumoto"
},
"deleted": false,
"checkout_guid": null
}
]
}
StockEvents objects which will be created.
deleted in the request, it will be treated as if false is specified.{
"timestamp": "2012年02月14日T09:00:00Z",
"events" : [ $stock_events ]
}
Checkout object represents an checkout/bill.
guid, paid_at, and account_id is used to identify a checkout.
paid_at with respect to its account's timezone and date_offset.
(The example here assumes account's timezone is "Asia/Tokyo" and date_offset is 0.)
"close", "open", "deleted", or "cancel".
"close" is for closed checkout, such that the cashier already finished editing the checkout.
"open" is for open checkout, such that the cashier is continuing editing the checkout.
"cancel" is for deleted checkout, such that the checkout once was closed, but later canceled.
"deleted" is for canceled checkout, such that the checkout was deleted without closing it.
null if input skipped.CheckoutPayment, which describes how the checkout is got paid.CheckoutTax, which describes taxes included or added to the checkout.CheckoutItem, which describes which items are sold.Table.CustomerTags."plain"(default), "down" or "up""plain"(default), "down" or "up""checkout"(default) or "checkout_item"RpointTansaction associated with the checkout.{
"id": 1,
"guid": "8928309238-d987aerkeh-9847tdfkzhg4",
"deivce_id": "710b52d6-9d8f-11e5-9aac-af957c6aaf43",
"account_id": 1,
"paid_at": "2011年12月24日T16:20:20Z",
"sales_date": "2011年12月25日",
"price": "385.0",
"change": "4000.0",
"status": "close",
"cashier_id": null,
"customers_count": 0,
"payments": [ $Payments ],
"taxes": [ $CheckoutTaxes ],
"items": [ $CheckoutItems ],
"table_ids": [ 99, 8 ],
"customer_tag_ids": [ 10, 1003 ],
"modifier": "0.0",
"calculation_option": {
"tax_rounding_mode": "down",
"price_rounding_mode": "plain",
"tax_calculation_level": "checkout"
}
}
Retrieves the checkouts of the account which specified with account_id. The account should be one of current account, parent, children, or siblings. In other case, the request will result in 404 not found.
GET /accounts/current/checkouts GET /accounts/113/checkouts?since=....
{
"timestamp": "2011年11月02日T09:11:34Z",
"next-url": "https://ubiregi.com/api/3/accounts/31/checkouts?since=.....",
"last_updated_at": "2011年12月31日T00:00:31Z",
"checkouts": [ $checkouts ]
}
Checkouts for the request.Retrieves the closed checkouts of the account which specified with account_id. Checkout which status is "close" or "cancel" is closed checkout.
GET /accounts/current/checkouts/close GET /accounts/113/checkouts/close?since=....
{
"timestamp": "2011年11月02日T09:11:34Z",
"next-url": "https://ubiregi.com/api/3/accounts/31/checkouts/close?since=.....",
"last_updated_at": "2011年12月31日T00:00:31Z",
"checkouts": [ $checkouts ]
}
updated_at.Checkouts for the request.Create/update checkout of account with account_id.
Checkouts of current account and its child accounts are writable. Otherwise, the post request to checkouts will result in 400 error.
{
"checkouts": [
{
"items": [
{
"menu_item_id": 123,
"count": 1,
"sales": "100",
"tax": "5",
"discount_sales": "20",
"discount_tax": "1"
}
],
"change" : "26",
"guid" : $UUID-like-sequence,
"paid_at": $Time,
"payments": [
{ "payment_type_id": 101, "amount": "100" }
],
"customers_count': 1,
"customer_tag_ids': [ 20 ],
"cashier_id": 948,
"status": "Open"
},
{
"id": 4739,
"status": "Close"
}
]
}
Checkout objects to be created/updated.
CheckoutPayments.CheckoutItems.Tables.
CustomerTags.
There are validations on creating checkout objects. It should be good practice to send all attributes when creating new checkout.
{
"checkouts": [
{
"id": 123
"payments": [
{
"payment_type_id": 13,
"amount": "1032"
},
{
"id": 3112,
"amount": "809"
}
],
"items": []
}
]
}
Include an object without id. The first payments object is creating an CheckoutPayment.
Include an object with id and updating attributes. The second payments object is updating amount of a CheckoutPayment with its ID is 3112.
Objects which is not included in the array are deleted. All objects in items will be deleted.
{
"timestamp": "2011年11月02日T09:11:34Z",
"checkouts": [ $checkouts ]
}
CheckoutItem object represents each sold menu item in a checkout. It records how many the item sold and the price.
{
"id": 1,
"menu_item_id": 1,
"count": 3,
"sales": "330.0",
"tax": "0.0",
"discount_sales": "0.0",
"discount_tax": "0.0",
"guid" : $UUID-like-sequence,
"price_book_id": 1,
"price_type"; "intax",
"tax_rate": "8.0",
}
Make sure the amounts of currency; sales, tax, discount_sales, and discount_tax; are represented as a string, not a number. The price is calculated as follows: sales + tax - (discount_sales + discount_tax).
Tax rate and amount which are included or added to the checkout.
"included" or "excluded"{
"id": 1,
"tax_rate": "8.0",
"tax_type": "included",
"sales": "100.0",
"tax": "7.0",
"discount": "0.0",
"guid" : $UUID-like-sequence
}
Make sure numerical value is a string.
Pair of amount the customer paid, and method the payment maid with.
PaymentType{
"id": 1,
"payment_type_id": 1,
"amount": "5000.0",
"guid" : $UUID-like-sequence
}
Make sure amount value is a string.
Customer object represents a customer, which can be used in Customer Relation Management.
CustomerField object.
fields can not be empty.
true if and only if the customer is deleted.{
"id": 100,
"account_id": 2,
"fields": [ $customer_fields ],
"guid": $UUID-like-sequence,
"deleted": true
}
Retrieve collection of customers available for the account.
GET /customers?since=...
{
"timestamp": "2011年11月02日T09:11:34Z",
"next-url": "https://ubiregi.com/api/3/customers?since=.....",
"last_updated_at": "2011年12月31日T00:00:31Z",
"customers": [ $customers ]
}
An customer is available only if the customer is associated with one of the following:
The circles represent accounts and gray arrows represents parent-child associations. Accounts covered with purple background are accessible accounts, so that their accounts are available to current account (the red one).
Create an Customer objects, or update Customer objects available for current account.
{
"customers": [
{
"guid": $UUID-like-sequence,
"deleted": false,
"updated_fields": [ $customer_fields ]
}
]
}
Customer objects which will be updated/created.
CustomerFields.
{
"timestamp": "2012年02月14日T09:00:00Z",
"customers" : [ $customers ]
}
It is not allowed to destroy CustomerFields. Thus, fields attribute in POST requests are not defined, but updated_fields should be used instead. To (logically) destroy CustomerFields, set its deleted field to true.
A customer field belongs to a customer. This is mainly used to be included in a customer object.
{
"id": 1345,
"guid": $UUID-like-sequence,
"app_created_at": "2012年02月14日T00:00:00Z",
"name": "customer.field.name",
"value": "Ubiregi Taro",
"deleted": false
}
YYYY-MM-DD,
where YYYY is year in 4 digits, MM is month in 2 digits, and DD is day in 2 digits.
"F" and "M", for female and male, respectively.
@.address1 is expected to be an address.
address2 is expected to be additional information, like room number or building number.
Updating value of a CustomerField object is not recommended. Just create new field, and delete it (set deleted).
This is to avoid conflicting changes in two places, for example in your app and in the Ubiregi iPad app. If you do not update an existing CustomerField, the conflict will result in duplicated fields, and user can choose one, and then delete the other. This is safe.
A customer note belongs to a customer.
Checkout object, which the note is associated with."icon" or null.
"icon" in the case the photo is icon of the customer.
{
"id": 1,
"customer_id": 1,
"app_created_at": "2012年02月14日T00:00:00Z",
"guid": $UUID-like-sequence,
"checkout_id": 2,
"kind": "icon",
"note": "Memo Memo",
"photo": $base64Encoded,
"checkout_summary": "Summary"
}
Writing Photo When you are uploading CustomerNote, photo data is expected to be full size photo data.
Reading Photo When you are downloading CustomerNote, photo attribute is thumbnail generated in ubiregi.com server. The thumbnail is 256px x 256px size, JPEG data. The size should be convenient for many cases in your app to show a thumbnail to users. In the case you really need full size data, access the photo_url and download it.
GET /customers/notes?since=...
{
"timestamp": "2011年11月02日T09:11:34Z",
"next-url": "https://ubiregi.com/api/3/customers?since=.....",
"last_updated_at": "2011年12月31日T00:00:31Z",
"notes": [ $customer_notes ]
}
A CustomerNote is available only if the note is associated with available Customer.
Create a CustomerNote objects, or update CustomerNote objects available for current account.
{
"notes": [
{
"id": 1,
"customer_id": 1,
"app_created_at": "2012年02月14日T00:00:00Z",
"guid": $UUID-like-sequence,
"checkout_id": 2,
"kind": "icon",
"note": "Memo Memo",
"photo": $base64Encoded,
"checkout_summary": "Summary"
}
]
}
CustomerNote objects which will be updated/created.
Customer for the customer_id should be available from current account.Checkout of current account.{
"timestamp": "2012年02月14日T09:00:00Z",
"notes" : [ $customer_notes ]
}
PaidInOut object represents paid in and paid out to/from the cash register.
{
"id": 856,
"amount": "-123450.0",
"title": "Bank payment",
"account": 385,
"guid": "B15C25EB-32DF-435A-A010-50601BB444AA",
"device_id": "25D21F84-66F4-4197-B89C-D09470EB27E8",
"recorded_by_id: 231,
"canceled_by_id: 232,
"recorded_at": "2015年12月02日T13:21:12Z",
"canceled_at": "2015年12月02日T14:01:23Z"
}
Retrieves the PaidInOuts of an account specified by account_id.
GET /accounts/current/paid_inouts GET /accounts/113/paid_inouts?since=2015年01月01日T18:00:13Z
{
"timestamp": "2015年01月03日T03:11:03Z",
"next-url": "https://ubiregi.com/api/3/accounts/113/items?since=2015年01月01日T18:00:13Z&until=2015年01月03日T03:11:03Z&glb=13476",
"last_updated_at": "2015年01月02日T21:14:08Z",
"paid_inouts": [ $paid_inouts ]
}
Create a PaidInOut objects, or update PaidInOut objects of the account specified by :account_id.
{
"paid_inouts": [
{
"guid": "59516b4e-9d8f-11e5-9d2e-c3f422ef8fcf",
"amount": "-123450.0",
"title": "Bank payment",
"device_id": "710b52d6-9d8f-11e5-9aac-af957c6aaf43",
"recorded_by_id": 231,
"recorded_at": "2015年12月02日T13:21:12Z"
},
{
"id": 857,
"canceled_by_id: 232,
"canceled_at": "2015年12月02日T14:01:23Z"
}
]
}
PaidInOut objects to be updated/created.
{
"timestamp": "2015年12月02日T14:11:12Z",
"paid_inouts" : $paid_inouts
}
PaidInOuts.
null when the transaction is not canceled.RpointTransactionItem.{
"guid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"card_id": "1234-5678-9012-3456",
"use_amount": 10,
"checkout_guid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"canceled_at": null,
"items": [ ... ]
}
RpointKind.RpointItem for the item, or null.{
"kind": "const10",
"amount": 10,
"item_id": 123,
"price": null
}
{
"kind": "default",
"amount": 11,
"item_id": null,
"price": 1105
}
| kind | item | price |
|---|---|---|
"default" |
null |
Price which is used to calculate value of amount |
| * | Object representing RpointItem |
null |
null if the item is hidden.{
"id": 123,
"name": "MyCampaign",
"kind": "const10",
"display_name": "...",
"note": "...",
"default_item": false,
"position": 1,
"updated_at": "...",
"created_at": "..."
}
"default""const10""const50""const100""const500""percentage1""percentage2""percentage4""percentage9"There are only one scope of ID, Universal.
If this doc says ID, it is an one origin integer value which uniquely determines an object on ubiregi server.
Most objects have special fields, created_at and updated_at.
Ubiregi API permission model is very simple. The permission to a object is decided by its owner account’s role.
There are three permissions, nothing, readonly and writable.
There are five roles, current, children, parents, siblings, and others.
The permission is defined as following:
and it is figured out as following.
Each circle represents an Account. Gray arrows represent parent-child links between accounts. Red, green, blue, purple, and gray circles represent current, children, parents, siblings, and others accounts respectively. Green background is for the object which owns objects with writable permission, and light-pink background is for readonly permission.
Note that Customers have their own permission model.
Each MenuItem has its own stock count. stock, last_inventory_at, and incoming_stock are updated when new StockEvent is created.
inventory event, and set its inventory_at.
last_inventory_amount - shipped_amount + arrived_amount
where:last_inventory_amount = latest_inventory_event.amount
shipped_amount = Σ following_shipping_events.amount
arrived_amount = Σ arrival_events.amount
Σ order_events.amount- Σ arrival_events.amount
app_created_at field is to remember when the object is created in the iPad app. It generally meaningless; iPad clock may be inaccurate, the clock can easily changed.
It is recommended to record some time, or just use the time of post.
There may be private fields, not defined in this document but you find in the response from server. It is okay if you use these fields, but keep in your mind they are private so that it may be removed without any announcement.
Image fields including icon and photo are null by default. This is to reduce the size of data transmission.
To download the image data, give an http query parameter image=blob.
GET /accounts/current?image=blob
GET /accounts/customer/notes?image=blob
Errors are notified via HTTP response status. Error code are following the standard HTTP error code convention. If there are something bad in your request, you will get 4xx. If there are something wrong happen on the server, you will get 5xx.
We define following status codes, where the meaning is shared between all requests.
If-Modified-Since HTTP header with the same value as since parameter in request JSON.
The error response contains JSON object which represents the detail of the error. The format of Error object is as the followings:
{
"errors": [
{
"object" : {
"name": "Existing Cashier",
"enabled":true,
"icon":"hogehoge"
},
"messages": ["invalid icon"]
}
],
"timestamp": "2012年03月11日T09:00:00Z"
}