Ordering New Services
=====================

Index {#index}
-----------------------------

Listing of available services:

 - [List of available services](#list)
 - [Service details](#detail)

Validating services and loading prices:

 - [Validate a domain](#post-validate-domain)
 - [Validate credit](#post-validate-credit)
 - [Validate vps](#post-validate-vps)
 - [Validating multiple services](#post-validate)

Ordering a new service:

 - [Ordering services](#post-order)

Credit card, internet banking and credit payments:

 - [Pay it](#get-order-pay)
 - [Pay with a stored card](#put-pay)
 - [Pay with credit](#put-credit-pay)
 - [List of all payment cards](#paymentcards)
 - [Get a payment card detail](#paymentcard)
 - [Add payment card](#put-paymentcard)


List of available services {#list}
-----------------------------
Every item has its name and a list of prices. The price is identified by an identifier/plan name (string), for example domain TLD.
Currency is based on `market` identifier. WebSupport is currently on Slovak (`sk`), Czech (`cz`), Hungarian (`hu`) and Austrian (`at`) market.

#### URL parameters:

 - `market` - 2-letter country identifier, values: `sk` (Slovakia), `cz` (Czech Republic), `hu` (Hungary) or `at` (Austria). See more about [identifiers](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market" -v
```

>Request
```http
GET https://rest.websupport.sk/v1/order/:market HTTP/1.1

Accept: application/json
```

>Response `200`
```json
[
	{
		"type": "domain",
		"prices": [
			{
			   "tld": "sk",
			   "price": 12.3
			},
			{
			   "tld": "eu",
			   "price": 9.95
			},
			{
			   "tld": "cz",
			   "price": 10.95
			},
			{
			   "tld": "com",
			   "price": 9.95
			},
			{
			   "tld": "co",
			   "price": 29.95
			},
			{
			   "tld": "net",
			   "price": 9.95
			},
			{
			   "tld": "info",
			   "price": 9.95
			},
			{
			   "tld": "biz",
			   "price": 9.95
			}
			// and other supported domains
		],
		"discounts": [
			{
               "tld": "eu",
               "price": 1
			}
		],
		"currency": "eur"
	},
	{
		"type": "credit",
		"prices": [],
		"discounts": [],
		"currency": "eur"
	},
    {
       "type": "vps",
       "prices":
       [
           {
               "ram": 512,
               "disk": 15,
               "vcpus": 1,
               "price": 13
           },
           {
               "ram": 1024,
               "disk": 25,
               "vcpus": 2,
               "price": 20
           },
           {
               "ram": 2048,
               "disk": 50,
               "vcpus": 2,
               "price": 35
           },
           {
               "ram": 4096,
               "disk": 100,
               "vcpus": 4,
               "price": 57
           }
       ],
       "discounts":
       [
       ],
       "currency": "eur",
       "templates":
       [
           {
               "name": "ubuntu 12.04 minimal",
               "version": "1.1"
           },
           {
               "name": "ubuntu 12.04 webadmin",
               "version": "1.1"
           },
           {
               "name": "ubuntu 12.04 LAMP",
               "version": "1.1"
           }
       ]
   }
]
```

>Response `404` (not found)
```json
{
	"message": "Unknown market!",
	"code": 404
}
```

Service details {#detail}
-----------------

#### URL parameters:

 - `market` - 2-letter country identifier, values: `sk` (Slovakia), `cz` (Czech Republic), `hu` (Hungary) or `at` (Austria). See more about [identifiers](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
 - `type` - service name, values: `domain` etc.

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market/:type" -v
```

>Request
```http
GET https://rest.websupport.sk/v1/order/:market/:type HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
  "type": "vps",
  "prices": [
    {
      "ram": 512,
      "disk": 15,
      "vcpus": 1,
      "price": 9.75,
      "priceWithVat": 11.7
    },
    {
      "ram": 1024,
      "disk": 25,
      "vcpus": 2,
      "price": 18.25,
      "priceWithVat": 21.9
    },
    {
      "ram": 2048,
      "disk": 50,
      "vcpus": 2,
      "price": 26.5,
      "priceWithVat": 31.8
    },
    {
      "ram": 4096,
      "disk": 100,
      "vcpus": 4,
      "price": 53,
      "priceWithVat": 63.6
    }
  ],
  "discounts": [],
  "currency": "eur",
  "templates": [
    {
      "name": "Windows Server 2022",
      "version": null
    },
    {
      "name": "Windows Server 2019",
      "version": null
    },
    {
      "name": "Windows Server 2016",
      "version": null
    },
    {
      "name": "Ubuntu 22.04",
      "version": null
    },
    {
      "name": "Ubuntu 20.04",
      "version": null
    },
    {
      "name": "Ubuntu 18.04",
      "version": null
    },
    {
      "name": "Debian 12",
      "version": null
    },
    {
      "name": "Debian 11",
      "version": null
    },
    {
      "name": "Debian 10",
      "version": null
    }
  ]
}
```

>Response `404` (not found)
```json
{
	"message": "Unknown order type!",
	"code": 404
}
```

-----------------


Validate a domain {#post-validate-domain}
---------------------------------------

This method is responsible for validating order attributes. The same attributes are used for real ordering.
You can use this method as domain name validator, for checking domain availibility and for getting service prices.

#### Input fields:

| Name             | Type   | Supported TLDs | Required | Comment                                                                                     |
|------------------|--------|----------------|----------|---------------------------------------------------------------------------------------------|
| **domain**       | string | all            | yes      | the full domain name with TLD, i.e. `scaledo.com`                                           |
| dnsServers       | string | sk, cz, eu     | no       | list of DNS servers separated by semicolon (`;`), ex. `ns1.websupport.sk;ns2.websupport.sk` |
| domainProfileId  | int    | all            | no       | id of domain profile, see [Domain profiles](#domainProfiles)                                |
| contactId        | string | all            | no       | custom contact id                                                                           |


Method may throw `500` error response if something is wrong.

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market/validate/domain" -H "Content-Type: application/json" \
 -X POST -d '{"domain":"testingdomain.sk"}'
```

>Request
```http
POST https://rest.websupport.sk/v1/order/:market/validate/domain HTTP/1.1

Accept: application/json
Content-Type: application/json

{
  "domain":"testingdomain.sk"
}
```

>Response `200` (ok)
```json
{
	"status": "success",
	"item":
	{
		"domain": "testingdomain.sk",
		"suggest": true,
		"dnsServers": "",
		"contactId": "",
		"domainProfileId": 155,
		"price": 12.3,
		"priceWithVat": 14.76,
		"currency": "eur",
		"period": 1,
		"periodLength": "year"
	},
	"errors":
	[
	]
}
```
>Response `200` (validation failed)
```json
{
	"status": "error",
	"item":
	{
		"domain": "aaa.com",
		"suggest": true,
		"price": null,
		"priceWithVat": null,
		"currency": null,
		"period": null,
		"periodLength": null
	},
	"errors":
	{
		"domain":
		[
			"Domain is taken."
		]
	}
}
```

Validate credit {#post-validate-credit}
---------------------------------------

This method is responsible for validating order attributes. The same attributes are used for real ordering.
You can use this method for getting service price.

#### Input fields:

| Name       | Type | Required | Comment                                     |
|------------|------|----------|---------------------------------------------|
| **amount** | int  | yes      | amount to order, 1 credit is 1 EUR, HUF or CZK (depending on market) |

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market/validate/credit" -H "Content-Type: application/json" \
 -X POST -d '{"amount":20}'
```

>Request
```http
POST https://rest.websupport.sk/v1/order/:market/validate/credit HTTP/1.1

Accept: application/json
Content-Type: application/json

{
  "amount":20
}
```

>Response `200` (ok)
```json
{
    "status": "success",
	"item":
	{
		"amount": 10,
		"price": 10,
		"price": 12,
		"currency": "eur",
		"period": null,
		"periodLength": null
	},
	"errors": {}
}
```

>Response `200` (validation error)
```json
{
   "status": "error",
   "item":
   {
		"amount": 0,
		"price": null,
		"priceWithVat": null,
		"currency": null,
		"period": null,
		"periodLength": null
   },
   "errors":
   {
	   "amount":
	   [
		   "Amount is too small (minimum is 5)."
	   ]
   }
}
```

Validate VPS {#post-validate-vps}
---------------------------------------

This method is responsible for validating order attributes. The same attributes are used for real ordering.
You can use this method for getting service price.

#### Input fields:

| Name       | Type   | Required | Comment                                     |
|------------|--------|----------|---------------------------------------------|
| **name**   | string | yes      | vps hostname - only alphanumeric chars |
| **ram**    | int    | yes      | ram size in MB |
| **disk**   | int    | yes      | hdd size in GB |
| **vcpus**  | int    | yes      | number of virtual CPUs |
| **templateName**  | string    | yes      | template name, list of all templates is in [Service details](#detail) |
| **templateVersion**  | string    | yes      | version |
| period     | int  | no       | service billing period in months, range 1~12, default is 1 |
| secondaryIp | bool | no       | default false |
| backups     | bool | no       | default true |

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market/validate/vps" -H "Content-Type: application/json" \
 -X POST -d '{"name":"test","ram":1024, "disk":10, "vcpus":1, "templateName":"ubuntu-12.04", "templateVersion":"v1", "period": 1}'
```

>Request
```http
POST https://rest.websupport.sk/v1/order/:market/validate/vps HTTP/1.1

Accept: application/json
Content-Type: application/json

{
	"name":"test",
	"ram":1024,
	"disk":10,
	"vcpus":1,
	"templateName":"ubuntu 12.04 webadmin",
	"templateVersion":"1.1",
	"period": 1
}
```

>Response `200` (ok)
```json
{
  "status": "success",
  "item": {
    "name": "test",
    "ram": 1024,
    "disk": 10,
    "vcpus": 1,
    "templateName": "ubuntu 12.04 webadmin",
    "templateVersion": "1.1",
    "backups": true,
    "secondaryIp": true,
    "price": 39.37,
    "priceWithVat": 47.24,
    "currency": "eur",
    "period": 1,
    "periodLength": "month",
	"priceDetail": {
		"prices": {
			"vps": 24.97,
			"serverManager": 5,
			"backups": 8.4,
			"secondaryIp": 1
		},
		"pricesWithVat": {
			"vps": 29.96,
			"serverManager": 6,
			"backups": 10.08,
			"secondaryIp": 1.2
		}
	}
  },
  "errors": {}
}
```

>Response `200` (validation error)
```json
{
   "status": "error",
   "item":
   {
		"name": "test",
		"ram": 1,
		"disk": 10,
		"vcpus": null,
		"templateName": "ubuntu 12.04 webadmin",
		"templateVersion": "1.1",
		"backups": true,
		"secondaryIp": true,
		"price": 9.2,
		"priceWithVat": null,
		"currency": null,
		"period": null,
		"periodLength": null
   },
   "errors":
   {
	   "vcpus":
	   [
		   "Vcpus cannot be blank."
	   ],
	   "name":
	   [
		   "Virual server name is already taken."
	   ],
       "ram":
       [
           "Ram is too small (minimum is 512)."
       ]
   }
}
```

Validating multiple services {#post-validate}
---------------------------------------------

Method for validating multiple services is identical to methods validating each service separately **except** for these two differences:

 - request body is now **list** of dictionaries of attributes used in [validate domain](#post-validate-domain)
 - property `type` is added to each dictionary of attributes to identify service type (previously defined in URL)

Response is also a **list** of responses used in validations. There is not a common status code, each services is validated separately.

>Curl
```sh
curl "https://rest.websupport.sk/v1/order/:market/validate" -H "Content-Type: application/json" \
 -X POST -d '[{"type":"domain", "domain":"testingdomain.sk"}]'
```

>Request
```http
POST https://rest.websupport.sk/v1/order/:market/validate HTTP/1.1

Accept: application/json
Content-Type: application/json

[
	{
		"type": "domain",
		"domain":"testingdomain.sk"
	}
}
```

>Response `200` (ok)
```json
[
	{
		"status": "success",
		"item":
		{
			"domain": "testingdomain.sk",
			"dnsServers": "",
			"sknicHandle": "WEBS-0001",
			"price": 12.3,
			"priceWithVat": 14.76,
			"currency": "eur",
			"period": 1,
			"periodLength": "year"
		},
		"errors":
		[
		]
	},
	{
		"status": "success",
		"item":
		{
			"limit": 1024,
			"price": 1.4,
			"priceWithVat": 1.68,
			"currency": "eur",
			"period": 1,
			"periodLength": "month"
		},
		"errors": {}
	}
]
```


Ordering services {#post-order}
-------------------------------

#### Input fields:

| Name     | Type   | Required | Comment |
|----------|--------|----------|---------|
| **services** | list   | yes      | list of services to order |
| note     | string | no       | additional information for our helpdesk team |

Please refer to [validate a domain](#post-validate-domain) for service format.

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:id/order" -H "Content-Type: application/json" -H "Date: request_date_time" \
 -X POST -d '{"services":[{"type":"domain", "domain":"testingdomain.sk"}]}' -u key:signature
```

>Request
```http
POST https://rest.websupport.sk/v1/user/:id/order HTTP/1.1

Accept: application/json
Content-Type: application/json

{
	"services": [
		{
			"type": "domain",
			"domain":"testingdomain.sk"
		}
	],
	"note":"note to our helpdesk team"
}
```

>Response `201` (ok)
```json
{
	"status": "success",
	"item":
	{
		"id": 384718,
		"services":
		[
			{
			   "status": "success",
			   "item":
			   {
				   "domain": "testingdomain.sk",
				   "dnsServers": "",
				   "sknicHandle": "WEBS-0001",
				   "price": 12.3,
				   "priceWithVat": 14.76,
				   "currency": "eur",
				   "period": 1,
				   "periodLength": "year"
			   },
			   "errors":
			   [
			   ]
			},
			{
				"status": "success",
				"item":
				{
					"limit": 1234,
					"price": 1.5,
					"priceWithVat": 1.8,
					"currency": "eur",
					"period": 1,
					"periodLength": "month"
				},
				"errors":
				[
				]
			}
		],
		"note": "note to our helpdesk team"
	},
	"errors":
	[
	]
}
```

>Response `200` (validation error)
```json
{
	"status": "error",
	"item":
	{
		"id": null,
		"services":
		[
			{
				"status": "error",
				"item":
				{
					"domain": "aaa.sk",
					"dnsServers": "",
					"sknicHandle": "WEBS-0001",
					"price": 12.3,
					"priceWithVat": 14.76,
					"currency": "eur",
					"period": 1,
					"periodLength": "year"
				},
                "errors":
				{
					"domain":
					[
						"Domain is taken."
					]
				}
			},
			{
				"status": "error",
				"item":
				{
					"limit": 1,
					"price": null,
					"priceWithVat": null,
					"currency": null,
					"period": null,
					"periodLength": null
				},
				"errors":
				{
					"limit":
					[
						"Limit is too small (minimum is 1024)."
					]
				}
			}
		],
		"note": "note to our helpdesk team"
	},
	"errors":
	{
		"services":
		[
			"There are invalid services in your order!"
		]
	}
}
```

>Response `200` (input format error)
```json
{
	"status": "error",
	"item":
	{
		"id": null,
		"services": [],
		"note": ""
	},
	"errors":
	{
		"services":
		[
			"Service type at position 1 is not set!"
		]
	}
}
```

>Response `500` (something went wrong)
```json
{
	"message": "Text of error message",
	"code": 500
}
```

### Ordering with custom billing profile

If you want to create order with custom billing information use URL:

`https://rest.websupport.sk/v1/user/:id/billing/:billingId/order`


### Testing order or running validation only

Just add parameter `?dryRun=1` to the end of the URL.
Response format will be the same and return code will be 200 not 201.


Pay it {#get-order-pay}
-----------------------------------

You can pay your order with **credit card** or using **internet banking**. At this moment we support
[TatraPay](http://www.tatrabanka.sk/en/business-banking/accounts-payments-cards/electronic-banking/tatrapay.html),
[VUB ePayments](http://www.vub.sk/en/for-companies/nonstop-banking/ecommerce-online-retailers/epayments/) internet banking
**ComfortPay** recurring payment system and Visa or MasterCard credit cards.

Payment URLs from this method are available few seconds after creating your order (usually up to 5s), but there can be problems with automatic order confirmation (for ex. your order contains note, so our helpdesk team needs to check it first). These orders are reviewed manually and confirmation can take hours. If you don't get response after 60s, ignore this method and wait for an e-mail with attached invoice.

Add `?mobile=1` at the end of each url, if you want mobile version of internet banking / credit card payment page.

**Note:** if you choose ComfortPay payment system, we will store your payment card so you can use it next time through [pay with a stored card](#put-pay) method. 
If you don't want to store your payment card, please use CardPay system (tbcardpay).

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay" -u key:signature -H "Date: request_date_time"
```

>Request
```http
GET https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
	"tbtatrapay": "https://admin.websupport.sk/sk/invoice/pay/invoiceId/109430586/type/tatrapay",
	"tbcardpay": "https://admin.websupport.sk/sk/invoice/pay/invoiceId/109430586/type/creditCard-0",
	"vubeplatby": "https://admin.websupport.sk/sk/invoice/pay/invoiceId/109430586/type/vubeplatby",
	"comfortpay": "https://admin.websupport.sk/sk/invoice/pay/invoiceId/109430586/type/creditCard-0"
}
```

>Response `404` (order not found, not confirmed or already paid)
```json
{
	"code": 404,
	"message": "Order is not confirmed."
}
```

Pay with a stored card {#put-pay}
-----------------------------

You can pay your order with **payment card** that you have assigned to your account in the past. List of available payment cards for logged user can be fetched with [/v1/user/:userId/paymentcard](#paymentcards) api method.

Payment for order is available few minutes after creating your order (usually up to 5m), but there can be problems with automatic order confirmation (for ex. your order contains note, so our helpdesk team needs to check it first). These orders are reviewed manually and confirmation can take hours. If you don't get response after 60s, ignore this method and wait for an e-mail with attached invoice.

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay/byPaymentCard/:paymentCardId" -u key:signature -H "Date: request_date_time" -X PUT
```

>Request
```http
PUT https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay/byPaymentCard/:paymentCardId HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
	"status": true
}
```

>Response `404` (order not found, not confirmed or already paid)
```json
{
	"code": 404,
	"message": "Order is not confirmed."
}
```

Pay with credit {#put-credit-pay}
---------------------------------

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay/byCredit" -u key:signature -H "Date: request_date_time" -X PUT
```

>Request
```http
PUT https://rest.websupport.sk/v1/user/:userId/order/:orderId/pay/byCredit HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
	"status": true
}
```

>Response `404` (order not found, not confirmed or already paid)
```json
{
	"code": 404,
	"message": "Order is not confirmed."
}
```


List of all payment cards {#paymentcards}
--------------------------

Method for listing all payment cards of logged user.

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:userId/paymentcard" -v -u key:signature -H "Date: request_date_time"
```

>Request
```http
GET https://rest.websupport.sk/v1/user/:userId/paymentcard HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
   "items":
   [
	   {
		   "id": 123,
		   "name": "4461********1234",
		   "defaultBillingId": 1234,
		   "createTime": 1279829310
	   },
	   {
		   "id": 234,
		   "name": "4406********9876",
		   "defaultBillingId": 2345,
		   "createTime": 1407915581
	   }
   ],
   "credit": 0
}
```


Get a payment card detail {#paymentcard}
-------------------------

You can get info by payment card ID.

>Curl
```sh
curl "https://rest.websupport.sk/v1/user/:userId/paymentcard/:id" -v -u key:signature -H "Date: request_date_time"
```

>Request
```http
GET https://rest.websupport.sk/v1/user/:userId/paymentcard/:id HTTP/1.1

Accept: application/json
```

>Response `200`
```json
{
   "id": 234,
   "name": "4406********9876",
   "defaultBillingId": 2345,
   "createTime": 1407915581
}
```

>Response `404` (not found)
```json
{
	"message": "Payment card not found.",
	"code": 404
}
```

Add payment card {#put-paymentcard}
-------------------------

To add new payment card, you need to pay your first inovoice/order with **ComfortPay** system.
More in [pay it](#get-order-pay) section.

Your card will be automatically added to your account and you can pay with [pay with a stored card](#put-pay) method.