diff --git a/source/includes/_addresses.md b/source/includes/_addresses.md index a32337884fe..6b10508eb45 100644 --- a/source/includes/_addresses.md +++ b/source/includes/_addresses.md @@ -15,16 +15,14 @@ country | `string` | The country of Address geo | `array` | The geo position of Address raw | `object` | All information like address, country, zip code, etc... from service alias | `string` | The alias of Address +organization_name | `string` | The name of the organization at the given address if applicable service | `string` | The service used for Address _default google_ -### service +### Services -Possibilities | -------------- | -google | -pca | +We currently support localization with Google. -## Retrieves an Address +## Retrieving an Address > Definition @@ -35,126 +33,133 @@ GET https://api.kvass.ai/addresses/lookup > Example request: ``` http -GET /addresses/lookup HTTP/1.1 +GET /addresses/lookup?service=google&type=streetname&query=Karl%20Johans%20gate%2022 HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai { - "service_address_id":"ChIJR0HKYoduQUYRkho1K1zkZpA", - "alias":"", - "country":"Norway", - "zip_code":"0160", - "street_name":"Tordenskiolds gate 3", - "geo":[ - 59.9131976, - 10.7361056 - ], - "raw":{ - "address_components":[ - { - "types":[ - "street_number" - ], - "short_name":"3", - "long_name":"3" - }, - { - "types":[ - "route" - ], - "short_name":"Tordenskiolds gate", - "long_name":"Tordenskiolds gate" - }, - { - "types":[ - "political", - "sublocality", - "sublocality_level_1" - ], - "short_name":"Sentrum", - "long_name":"Sentrum" - }, - { - "types":[ - "postal_town" - ], - "short_name":"Oslo", - "long_name":"Oslo" - }, - { - "types":[ - "administrative_area_level_2", - "political" - ], - "short_name":"Oslo kommune", - "long_name":"Oslo kommune" - }, - { - "types":[ - "administrative_area_level_1", - "political" - ], - "short_name":"Oslo", - "long_name":"Oslo" - }, - { - "types":[ - "country", - "political" - ], - "short_name":"NO", - "long_name":"Norway" - }, - { - "types":[ - "postal_code" - ], - "short_name":"0160", - "long_name":"0160" - } - ], - "formatted_address":"Tordenskiolds gate 3, 0160 Oslo, Norway", - "types":[ - "premise" - ], - "geometry":{ - "location_type":"ROOFTOP", - "location":{ - "lat":59.9131976, - "lng":10.7361056 - }, - "viewport":{ - "northeast":{ - "lat":59.9145465802915, - "lng":10.7374546302915 + "alias": "", + "country": "Norway", + "service": "google", + "street_name": "Karl Johans gate 22", + "city": "Oslo", + "geo": [ + 59.9130629, + 10.7402665 + ], + "service_address_id": "ChIJ7ZkfWX1uQUYRLjlo7CGVLFo", + "raw": { + "geometry": { + "viewport": { + "northeast": { + "lat": 59.9143406802915, + "lng": 10.7415464302915 + }, + "southwest": { + "lat": 59.91164271970849, + "lng": 10.7388484697085 + } }, - "southwest":{ - "lat":59.91184861970849, - "lng":10.7347566697085 - } - }, - "bounds":{ - "northeast":{ - "lat":59.91333940000001, - "lng":10.736447 + "location": { + "lat": 59.9130629, + "lng": 10.7402665 + }, + "bounds": { + "northeast": { + "lat": 59.9134037, + "lng": 10.7410763 + }, + "southwest": { + "lat": 59.91257969999999, + "lng": 10.7393186 + } + }, + "location_type": "ROOFTOP" + }, + "place_id": "ChIJ7ZkfWX1uQUYRLjlo7CGVLFo", + "formatted_address": "Stortingsbygningen, Karl Johans gate 22, 0026 Oslo, Norway", + "types": [ + "premise" + ], + "address_components": [ + { + "long_name": "Stortingsbygningen", + "short_name": "Stortingsbygningen", + "types": [ + "premise" + ] + }, + { + "long_name": "22", + "short_name": "22", + "types": [ + "street_number" + ] + }, + { + "long_name": "Karl Johans gate", + "short_name": "Karl Johans gate", + "types": [ + "route" + ] + }, + { + "long_name": "Sentrum", + "short_name": "Sentrum", + "types": [ + "political", + "sublocality", + "sublocality_level_1" + ] + }, + { + "long_name": "Oslo", + "short_name": "Oslo", + "types": [ + "postal_town" + ] + }, + { + "long_name": "Oslo kommune", + "short_name": "Oslo kommune", + "types": [ + "administrative_area_level_2", + "political" + ] + }, + { + "long_name": "Oslo", + "short_name": "Oslo", + "types": [ + "administrative_area_level_1", + "political" + ] + }, + { + "long_name": "Norway", + "short_name": "NO", + "types": [ + "country", + "political" + ] }, - "southwest":{ - "lat":59.91305579999999, - "lng":10.7357643 + { + "long_name": "0026", + "short_name": "0026", + "types": [ + "postal_code" + ] } - } - }, - "place_id":"ChIJR0HKYoduQUYRkho1K1zkZpA" - }, - "service":"google", - "city":"Oslo" + ] + }, + "zip_code": "0026" } ``` Arguments | Type | Description --------- | ---- | ------ -service | `string` | Chose the service you want use -type | `string` | Define the type of your search, if it's street name, zip code, etc +**service** | `string` | Chose the service you want to use **query** | `string` | Query is what you want to search for e.g.: "Tordenskioldsgate 3, Oslo" +type | `string` | Define your search parameter, if it's street name, zip code, etc diff --git a/source/includes/_coupons.md b/source/includes/_coupons.md index 433920e05d7..31f80e43dd1 100644 --- a/source/includes/_coupons.md +++ b/source/includes/_coupons.md @@ -1,6 +1,6 @@ # Coupons -Coupons are a great way to offer discounts or vouchers to your Customers. They can be used together with multiple business models: Orders, Invoices and Subscriptions. +Coupons are a great way to offer discounts or credit vouchers to your customers. They can be used together with multiple business models: Orders, Invoices and Subscriptions. ## Coupon Object @@ -8,17 +8,17 @@ Coupons are a great way to offer discounts or vouchers to your Customers. They c Attributes | Types | Description ---------- | ----- | ----------- **name** | `string` | Name of the coupon -**code** | `string` | The code to be used by a costumer. By default, the code is automatically generated (a string of 6 characters long, e.g: Nz42kL), but you can also create our own. +**code** | `string` | The code to be used by a customer. By default, the code is automatically generated (a string of 6 characters long, e.g: Nz42kL), but you can also create our own. percent_off | `number` | The discount percentage, should be between `0.` and `1.`, for example: 0.2 means 20% of the total amount. amount_off | `number` | Discount amount, for example: 100.50, means that the next payment will be decreased by 100.50. currency | `string` | ISO 4217 code of currency, for example: "EUR" -starting_date | `object` | Define when can the coupon start being used. By default, it'll start at the time of creation, but it could be defined for the future. If defined in the future, it means the coupon could not be used before the `starting_date`, `timestamp` format. _Default `now`_ -ending_date | `object` | The date when the coupon will stop being available. `timestamp` format. +starting_date | `object` | Define when the coupon can start being used. By default, it'll start at the time of creation, but it could be defined for the future. If defined in the future, it means the coupon cannot be used before the `starting_date`. `timestamp` format. _Default `now`_ +ending_date | `object` | The expiry date of the coupon. `timestamp` format. max_redemptions | `integer` | The number of times a coupon can be used. When the `used_count` is equal to the `max_redemption` then the coupon becomes unusable. used_count | `integer` | Automatically incremented by each use. -As you can see, there are two type of discount: percent_off and amount_off. +As you can see, there are two types of discounts: percent_off and amount_off. It's important to remember: a coupon can only have one of them at the same time. But if you want to change the type of discount you can do it easily with a `PUT coupons/` (There is an example [here](#switch-the-discount-type))
@@ -210,7 +210,7 @@ date_filter | `string` | Date field used for filter results. _default is `create ## Coupons Search -Retrieves a list of Coupons associate with the company. +Retrieves a list of Coupons associated with the company. > Definition @@ -221,7 +221,7 @@ GET https://api.kvass.ai/coupons/search > Example request: ```http -GET /coupons/search/query=SUMMER HTTP/1.1 +GET /coupons/search?query=SUMMER HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: diff --git a/source/includes/_credits.md b/source/includes/_credits.md index 38a01aa08a6..526c26ea6fd 100644 --- a/source/includes/_credits.md +++ b/source/includes/_credits.md @@ -1,18 +1,19 @@ # Credits +A `Credit` is used to pay for an [`Order`](#orders) containing a [`Credit Product`](#credit-product-object). + Attribute | Type | Description --------- | ---- | ------- -uuid | `string` | The unique reference ID for the Voucher. -**initial_quantity** | `number` | The number of vouchers that will be deducted from a [User](#users). -expires | `number` | The expiration date of the Credits. +**initial_quantity** | `number` | The number of Credits that will be deducted from a [User](#users). This value has no unit of measurement and is thus self-defined. _default set to 0_ +uuid | `string` | The unique reference ID for the Credit. +expires | `number` | The expiration date of the Credits. _default is set to a year from the date of creation_ consumed | `number` | The number of Credits the user has consumed. -The `Voucher` or `Credit` is used to pay for an [`Order`](#orders) containing [`Credit Product`](#credit-product-object). -## Grant Vouchers to User +## Grant Credits to User + +Admins are able to update credits for the users. -Admins are able to update vouchers for the users. -Note that the number of vouchers is set to this value, not incremented by the value. > Definition @@ -23,7 +24,7 @@ PUT https://api.kvass.ai/users/?expand=voucher > Example request: ``` http -POST /users HTTP/1.1 +PUT /users/ HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: @@ -78,29 +79,375 @@ Content-Type: application/json Argument | Type | Description -------- | ---- | ------- **user_id** | `string` | The [`user`](#users)'s unique ID. -voucher | `number` | The new value of the `initial_amount`. +**voucher** | `number` | The new value of the `initial_quantity`. +expires | `number` | The expiration date of the Credits. _default is set to a year from the date of creation_ + + + +## Credit Product Object + +The Credit Product is a subclass of [`Products`](#products). The Credit Product is a type of product that can be bought with [`Credits`](#credits). + +Attribute | Type | Description +--------- | ---- | ------- +**name** | `string` | The name of the product +**currency** | `string` | Three letter currency code in standard ISO 4217 format. +**vouchers_required** | `number` | The quantity of credits necessary to purchase the Credit Product ([`Credits`](#credits)) _default is 60_ +price | `number` | The price of the product +price_change_percentage | `number`| If you have sub_products in an order with the `price_change_percentage` set, then the sub_products will change the **main product's** amount in the order accordingly to the `product.price * sub_product.price_change_percentage` +description | `string` | A full description of the product +short_description | `string` | A brief description of the product +main_product | `boolean` | Flag that marks whether or not it is a main product +_sub_products | `array` | A list of sub products under the main product +parents | `array` | The sub product's parent +default_position | `array` | The geo position for the product +tags | `array` | List of tags associated with the product +properties | `object` | The product's properties +vat | `number` | The percentage of VAT in the product price. Percent value between 0 and 1 +max_distance | `number` | +slug | `string` | + +A Credit Product is a special product that allows the user to redeem [`credits`](#credits) to pay for an [`order`](#orders) instead of their [`payment method`](#payment-methods). + +## Create a New Credit Product +> Definition + +``` +POST https://api.kvass.ai/credit_products +``` + +> Example request: + +``` http +POST /credit_products HTTP/1.1 +Content-Type: application/json +Authorization: Bearer +X-Kvass-Api-Key: +Host: api.kvass.ai + +{ + "name": "Credit Product Name", + "currency": "NOK", + "vouchers_required": 120, + "description": "It is a test product" +} +``` + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "_id":{"$oid":"58f9f856b70e2a56c4a0db35"}, + "max_distance":0, + "created":{"$date":1492777046366}, + "default_position":[-1, -1], + "_cls":"CreditProduct", + "description":"", + "modified":{"$date":1492777046369}, + "_sub_products":[], + "name":"Credit Product Name", + "properties":{}, + "vouchers_required": 120, + "active":false, + "tags":[], + "vat":0.0, + "company":{"$oid":"57ee9c71d76d431f8511142f"}, + "deleted":false, + "company_take":-1.0, + "parents":[], + "main_product":true, + "currency":"NOK", + "path":"/" +} +``` + +This creates a new Credit Product. + +Argument | Type | Description +-------- | ---- | ------- +**name** | `string` | Name of the product +**currency**| `string` | Currency of the product _default set to `NOK`_ +**voucher_required** | `number` | Sets how many [`Credits`](#credits) this Credit Products costs to acquire. +price | `number` | Price of the product +vat | `number` | Percentage of price to be paid for VAT _default set to `0.0`_ +description | `string` | Full description of the product +short_description | `string` | Short description for the product +path | `string` | URL for the product _default set to `'/'`_ +main_product | `boolean` | Flag that marks whether or not it is a main product _default set to `True`_ +_sub_product | `array` | List of sub products under the product. _default set to `[]`_ +parents | `array` | List of the parent products to the sub product. _default set to `[]`_ +tags | `string` | List of tags associated with the product +default_position | `array` | Geo position of the product _default set to `[-1, -1]`_ +properties | `object` | The product's properties +provider | `string` | The [`provider`](#providers) assigned to the product, defined by the provider's ID +expire_days | `number` | Sets how many days this Credit Product is available. + +## Update a Credit Product + +> Definition + +``` +PUT https://api.kvass.ai/credit_products/ +``` + +> Example request: + +``` http +PUT /credit_products/ HTTP/1.1 +Content-Type: application/json +Authorization: Bearer +X-Kvass-Api-Key: +Host: api.kvass.ai + +{ + "description": "It is a test credit product", +} +``` + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "_id":{"$oid":"58f9f856b70e2a56c4a0db35"}, + "max_distance":0, + "created":{"$date":1492777046366}, + "default_position":[-1, -1], + "_cls":"CreditProduct", + "description":"It is a test credit product", + "modified":{"$date":1492777046369}, + "_sub_products":[], + "name":"Credit Product Name", + "properties":{}, + "vouchers_required": 120, + "active":false, + "tags":[], + "vat":0.0, + "company":{"$oid":"57ee9c71d76d431f8511142f"}, + "deleted":false, + "company_take":-1.0, + "parents":[], + "main_product":true, + "currency":"NOK", + "path":"/" +} +``` + +This creates a new Credit Product. + +Argument | Type | Description +-------- | ---- | ------- +name | `string` | Name of the product +price | `number` | Price of the product +currency | `string` | Currency of the product _default set to `NOK`_ +vat | `number` | Percentage of price to be paid for VAT _default set to `0.0`_ +description | `string` | Full description of the product +short_description | `string` | Short description for the product +path | `string` | URL for the product _default set to `'/'`_ +main_product | `boolean` | Flag that marks whether or not it is a main product _default set to `True`_ +_sub_product | `array` | List of sub products under the product. _default set to `[]`_ +parents | `array` | List of the parent products to the sub product. _default set to `[]`_ +tags | `string` | List of tags associated with the product +default_position | `array` | Geo position of the product _default set to `[-1, -1]`_ +properties | `object` | The product's properties +provider | `string` | The [`provider`](#providers) assigned to the product, defined by the provider's ID +voucher_required | `number` | Sets how many [`Credits`](#credits) this Credit Products costs to acquire. +expire_days | `number` | Sets how many days this Credit Products is available. + + +## Get a Credit Product +> Definition + +``` +GET https://api.kvass.ai/credit_products/ +``` + +> Example request: + +``` http +GET /credit_products/ HTTP/1.1 +Content-Type: application/json +Authorization: Bearer +X-Kvass-Api-Key: +Host: api.kvass.ai +``` + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "_id":{"$oid":"58f9f856b70e2a56c4a0db35"}, + "max_distance":0, + "created":{"$date":1492777046366}, + "default_position":[-1, -1], + "_cls":"CreditProduct", + "description":"It is a test credit product", + "modified":{"$date":1492777046369}, + "_sub_products":[], + "name":"Credit Product Name", + "properties":{}, + "vouchers_required": 120, + "active":false, + "tags":[], + "vat":0.0, + "company":{"$oid":"57ee9c71d76d431f8511142f"}, + "deleted":false, + "company_take":-1.0, + "parents":[], + "main_product":true, + "currency":"NOK", + "path":"/" +} +``` + +Get a Credit Product based on the credit product's unique ID. +Attribute | Type | Description +--------- | ---- | ------- +**bulk_id** | `string` | The credit product's ID -## Voucher Plan -A [`user`](#users) could also get vouchers by [`subscribing`](#subscriptions) on a `Voucher plan`. -A voucher plan has a lot of commonalities as a normal [`Plan`](#plans), but uses strictly +## Get List of All Credit Products Associated with a Company + +> Definition + +``` +GET https://api.kvass.ai/credit_products +``` + +> Example request: + +``` http +GET /credit_products HTTP/1.1 +Content-Type: application/json +Authorization: Bearer +X-Kvass-Api-Key: +Host: api.kvass.ai + +[ + { + "_cls":"CreditProduct", + "parents":[], + "tags":["fuzz", "Foo", "Bar"], + "vouchers_required": 120, + "_sub_products":[], + "deleted":false, + "company_take":-1.0, + "max_distance":0, + "description":"description", + "created":{"$date":1492781492460}, + "vat":0.0, + "properties":{}, + "active":true, + "name":"Credit Product Name", + "modified":{"$date":1492781492461}, + "company":{"$oid":"57ee9c71d76d431f8511142f"}, + "currency":"NOK", + "path":"/", + "main_product":true, + "_id":{"$oid":"58f9f856b70e2a56c4a0db35"}, + "business_rules":[], + "default_position":[-1,-1] + } +] +``` + +Arguments | Type | Description +--------- | ---- | ----------- +size | `number` | Number of items to retrieve. _default is 10_ +page | `number` | Which page to retrieve. _default is 50_ +lat | `number` | Define the latitude. +lng | `number` | Define the longitude. +all | `boolean` | If `true`, would return both of active and deleted and doesn't care of the attribute `main_product` credit products. + + +## Search Credit Product + +Retrieves a list of all Credit Products associated with the search. + +> Definition + +``` +GET https://api.kvass.ai/credit_products/search +``` + +> Example request: + +``` http +GET /credit_products/search?query=description HTTP/1.1 +Content-Type: application/json +Authorization: Bearer +X-Kvass-Api-Key: +Host: api.kvass.ai +``` + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +[ + { + "_cls":"CreditProduct", + "parents":[], + "tags":["fuzz", "Foo", "Bar"], + "vouchers_required": 120, + "_sub_products":[], + "deleted":false, + "company_take":-1.0, + "max_distance":0, + "description":"description", + "created":{"$date":1492781492460}, + "vat":0.0, + "properties":{}, + "active":true, + "name":"Credit Product Name", + "modified":{"$date":1492781492461}, + "company":{"$oid":"57ee9c71d76d431f8511142f"}, + "currency":"NOK", + "path":"/", + "main_product":true, + "_id":{"$oid":"58f9f856b70e2a56c4a0db35"}, + "business_rules":[], + "default_position":[-1,-1] + } +] +``` + +Arguments | Type | Description +--------- | ---- | ----------- +**query** | `string` | What you want to search for, e.g., **name**, **description**, or **id**. +size | `number` | Number of items to retrieve. _default is 10_ +page | `number` | Which page to retrieve. _default is 0_ +sort | `string` | Field used for sorting results. _default is `created`_ +lat | `number` | Define the latitude. +lng | `number` | Define the longitude. +include_deleted| `boolean` | If `true`, deleted products are also listed. + + +## Credit Plan + +A [`user`](#users) can also get credits by [`subscribing`](#subscriptions) to a `Credit Plan`. +A credit plan shares a lot of commonalities with a normal [`Plan`](#plans), but uses only [`Credit Product`](#credit-products) in the `plan.items` instead of regular [`Products`](#products). -The [`user`](#users) will be incremented the number of vouchers corresponding to the sum of the - `plan.items.product.vouchers_required` at every billing interval. The `total_amount` in the plan, +The number of credits corresponding to the sum of the `plan.items.product.vouchers_required` will be charged at every billing interval for each [`user`](#users) . The `total_amount` in the plan, the amount that the user will be charged at every billing interval, will be the sum of all - `plan.items.product.price` + `plan.items.product.price`. -### Create a Voucher Plan +### Create a Credit Plan Argument | Type | Description -------- | ---- | ------- -**plan_method** | `string` | The type of Plan, in the case a `voucher_plan`. +**method** | `string` | The type of Plan, in this case a `voucher_plan`. +**name** | `string` | The name of the Plan, in this case a `VOUCHER_PLAN`. **interval_unit** | `string` | The frequency that the Subscription acts upon.
interval_unit choices: `DAY`, `WEEK`, `MONTH`, `MONTH_END`, `ANNUAL` **billing_interval** | `string`| Defines billing frequency.
Choices: `WEEK`, `MONTH`, `MONTH_END` **currency** | `string`| Three letter ISO currency code as defined by ISO 4217.7 -**items** | `array` | An array of [`credict products`](#credit-products) and `quantity`. +**items** | `array` | An array of [`credit products`](#credit-products) and `quantity`. > Definition @@ -162,10 +509,10 @@ Content-Type: application/json } ``` -## Redeem Vouchers in an Order +## Redeem Credits in an Order -The User could redeem their voucher to pay for Orders if all the [`Order.item`](#orders)'s -only contains [`Credit Products`](#credit-products) +The User can redeem their credits to pay for Orders only if all the [`Order.items`](#orders) +are of type [`Credit Products`](#credit-products) > Definition @@ -174,7 +521,7 @@ only contains [`Credit Products`](#credit-products) POST https://api.kvass.ai/orders//redeem?expand=user.voucher ``` -> Example request: +> Example request & response: ``` http POST /orders//redeem?expand=user.voucher HTTP/1.1 @@ -183,7 +530,6 @@ Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai -{} ``` diff --git a/source/includes/_events.md b/source/includes/_events.md index 22b97b8eb49..e1f01bc293a 100644 --- a/source/includes/_events.md +++ b/source/includes/_events.md @@ -7,7 +7,6 @@ and keeping a history of transactions on your data. Attribute | Type | Description --------- | ---- | ------- -_id | `object` | The event ID. **kind** | `string` | The kind of event. Can be any from the [`event type list`](#list-of-event-types) data | `object` | It is an `EventData` object. author | `object` | [`User`](#users) which triggers the event @@ -110,8 +109,8 @@ page | `number` | Which page to retrieve _default is 0_ sort | `string` | Field used to sort results _default is `-created`_ -## Receive Event by ID -Receive an event, based on its ID. +## Get Event by ID +Get an event, based on its ID. > Definition @@ -192,7 +191,8 @@ Content-Type: application/json ## Events Search -Retrieves a list of Events associated with search. +Gets a list of Events associated with search. The query value needs to be equal to a specific +kind of event (i.e. order.created) or a class of events (i.e. order). > Definition @@ -203,7 +203,7 @@ GET https://api.kvass.ai/events/search > Example request by account_number: ``` http -GET /events/search/query=order HTTP/1.1 +GET /events/search?query=order HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: diff --git a/source/includes/_intro.md b/source/includes/_intro.md index dd6f6049389..59b09055686 100644 --- a/source/includes/_intro.md +++ b/source/includes/_intro.md @@ -4,8 +4,6 @@ The KVASS API is a standard JSON RESTful API. The API follows the HTTP standards All responses from the API, including errors, are returned as JSON objects. -The API is separated into 2 different environments: - The **Endpoint** of the API is: `api.kvass.ai` ## Authentication @@ -13,20 +11,23 @@ The **Endpoint** of the API is: `api.kvass.ai` ``` http GET / HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` -> Make sure to replace `` with your API key. +> Make sure to replace `` with your personal bearer token and `` with your API key. + +KVASS uses these two identifiers to allow access to the API. If you want access to our APIs, please get in touch through our [website](https://www.kvass.ai/). -KVASS uses API keys to allow access to the API. If you want access to our APIs, please get in touch through our [website](https://www.kvass.ai/). +All API requests should include both identifiers in the headers: -All API requests should include this key in the headers*: +Authorization: Bearer ``
+X-Kvass-Api-Key: `` -`X-Kvass-Api-Key: ` ## Errors @@ -40,7 +41,7 @@ Error Code | Reason | Description ---------- | ------- | ------- 400 | Bad Request | Your request is malformed or missing mandatory data. 401 | Unauthorized | Your API key is either wrong, missing or you have no permissions for this request. -403 | Forbidden | Your request is trying to access data it has no credentials for +403 | Forbidden | Your request is trying to access data without the required credentials 404 | Not Found | The specified resource could not be found. 409 | Conflict | There was a conflict with processing your request. Try later or change the data being submitted 415 | Unsupported Media Type | The requests' payload is in a format that is not supported by this method on the target resource. @@ -52,8 +53,9 @@ Error Code | Reason | Description > Example request: ```http -GET /payment_methods//?expand=user HTTP/1.1 +GET /payment_methods/?expand=user HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` @@ -73,7 +75,7 @@ Content-Type: application/json } ``` -Many response objects will contain IDs for related objects in the response. For example, an Order might have a User ID associated. If you want to expand the actual user information, you can use the `expand` query parameter. +Many response objects will contain IDs for related objects in the response. For example, an Order might have an associated User ID. If you want to expand the actual user information, you can use the `expand` query parameter. You can also nest expand requests with the dot property. For example, requesting payments.payment_method on an order will expand the payments property into a list of Payment objects, and will then expand the payment method property into a full Payment Method object. @@ -82,7 +84,7 @@ in the URL query string param expand that defines which fields that you want to For example: -`GET /orders//?expand=user,provider,items.product` +`GET /orders/?expand=user,provider,items.product` ## Common Object fields @@ -105,17 +107,16 @@ user | User associated with the object ``` http GET /orders?size=10&page=1 HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` -> Example request using only `size`: +> Example response headers: ``` http GET /orders?size=100 HTTP/1.1 Content-Type: application/json -X-Kvass-Api-Key: -Host: api.kvass.ai X-Pagination-Total: 212 ``` @@ -129,23 +130,23 @@ The return of a response header contains the total count: `X-Pagination-Total: 2 ## Retrieve items The models ([Users](#users), [Invoices](#invoices), [Issuers](#issuers), etc.) -describe below can be retrieved by two different ways, *searching* or a usual GET API call. +described below can be retrieved in two different ways, *searching* or a usual GET API call. -In both ways, you can use pagination, sorting, and filter the results by date to navigate big lists. -Additionally, the search method is using the argument `query`. -Each model that has the ability to do a search will be explained more thoroughly their respective chapters, +In both ways, you can use pagination, sorting, and filtering of the results by date to navigate big lists. +Additionally, the search method uses the argument `query`. +Each model that has the ability to do a search will be explained more thoroughly in their respective chapters, but all the models have a search by `ID` in common. > Definition GET ``` -GET https://api.kvass.ai/model +GET https://api.kvass.ai/ ``` > Example GET request: ``` http -GET /model HTTP/1.1 +GET / HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: @@ -169,13 +170,13 @@ Content-Type: application/json > Definition SEARCH ``` -GET https://api.kvass.ai/model/search +GET https://api.kvass.ai//search ``` > Example SEARCH request: ``` http -GET /model/search?query=a0b1c2d3e4d5c6b7a8b94242 HTTP/1.1 +GET //search?query=a0b1c2d3e4d5c6b7a8b94242 HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: @@ -206,14 +207,27 @@ sort | `string` | Model specific attributes for sorting results ### Getting list of models -The `Get` method allows you to retrieve all items from a model in a list. -Some models give you additional arguments for filter the requests (e.g: status filter). +The `Get` method allows you to retrieve a list of all items of a certain model type. +Some models give you additional arguments for filtering the requests (e.g: status filter). + +The available models are: + ++ Coupons ++ Events ++ Invoices ++ Issuers ++ Metrics ++ Orders ++ Plans ++ Payments ++ Payment Methods ++ Products ++ Providers ++ Resources ++ Subscriptions ++ Users ++ Webhooks - | Invoices | Issuers | Orders | Payments | Products | Providers | Users | Resources -------- | -------- | ------- | ------ | -------- | -------- | --------- | ----- | ----- -*Filter by date* | x | x | x | x | x | x | x | x -*Pagination* | x | x | x | x | x | x | x | x -*Sorting* | x | x | x | x | x | x | x | x ### Search on model @@ -223,12 +237,6 @@ This method allows you to retrieve a list of items matching with a search query, like `user_name` or `account_number`, without specifying that you are searching for `user_name` or `account_number`. - | Invoices | Issuers | Orders | Payments | Products | Providers | Users | Resources -------- | -------- | ------- | ------ | -------- | -------- | --------- | ----- | ----- -*Filter by date* | x | x | x | x | x | x | x | x -*Pagination* | x | x | x | x | x | x | x | x -*Sorting* | x | x | x | x | x | x | x | x - ### Search model by tags @@ -239,15 +247,15 @@ There are 3 ways of getting models by tags: 1. Get all models that contain a specific tag. -*Code: `?tags=tag_1`* + *Code: `?tags=tag_1`* 2. Get models that match multiple tags by separating the different tags in the query by `+`. -*Code: `?tags=tag_1+tag_2`* + *Code: `?tags=tag_1+tag_2`* 3. Get models that contain only 1 specific tag. -*Code: `?tags=tag_1+`* + *Code: `?tags=tag_1+`* ###Tag Query Examples @@ -265,15 +273,15 @@ If you only want models that match both `tag1_` and `tag_2`, separate the tags b - `GET some-route?tags=tag_1,tag_2` -Here we have two expressions: `tag_1` and `tag_2`, which would you returns all models contain `tag_1` or `tag_2` +Here we have two expressions: `tag_1` and `tag_2`, which would return all models containing `tag_1` or `tag_2` -- `GET some-route?tags=tag_2+tag_3,tag_1,tag_4+tag_5+tag_3` +- `GET some-route?tags=tag_1+tag_2,tag_3,tag_4+tag_5` -Here we have three expressions: `tag_2+tag_3`, `tag_1` and, `tag_4+tag_5`, which would you returns all models contain `tag_1` and `tag_2`, models contain `tag_1` and, models contain `tag_4`, `tag_5` and, `tag_3`. +Here we have three expressions: `tag_1+tag_2`, `tag_3` and, `tag_4+tag_5`, which would return all models containing both `tag_1` and `tag_2`, models containing `tag_3` and, models containing both `tag_4` and `tag_5`. -- `Get some-route?tags=tag_2+` +- `Get some-route?tags=tag_1+` -In the query above, the query is 'tag_2+'. This query will return models that match the tag 'tag_2' +In the query above, the query is 'tag_1+'. This query will return models that match the tag 'tag_1'