Introduction
API Endpoint
https://plugin.buycraft.net
Welcome to the Buycraft Plugin API documentation.
The Plugin API is for implementing command execution on Minecraft Servers or other custom clients - an example of this would be the official Buycraft Bukkit Plugin.
Are you a developer? If you’ve created an SDK in your favourite language we’d love to officially support it. Drop us an email via support@buycraft.net.
Authentication
To access the API all requests need to be authenticated via a Servers secret key.
Supply the secret key by setting the X-Buycraft-Secret
header in all requests to the API.
Error Handling
Example Error
{
"error_code": 403,
"error_message": "No server could be found with the specified secret key."
}
Errors are JSON format and are based around the standard HTTP status codes.
For example when an invalid secret key is provided the HTTP status code 403 Forbidden
will
be returned along with the JSON error as shown on the right.
The error_message
object will always be user friendly and should be shown directly to the client.
Information
Endpoint
GET https://plugin.buycraft.net/information
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/information"
Example Response
{
"account": {
"id": 123,
"domain": "http://example.buycraft.net",
"name": "Example Webstore",
"currency": {
"iso_4217": "GBP",
"symbol": "£"
},
"online_mode": true
},
"server": {
"id": 123,
"name": "Minecraft Server"
},
"analytics": {
"internal": {
"project": "<internal usage only>",
"key": "<internal usage only>"
}
}
}
Returns general information about the authenticated account and server.
Command Queue
Get due players
Endpoint
GET https://plugin.buycraft.net/queue
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue"
Example Response
{
"meta": {
"execute_offline": false,
"next_check": 90,
"more": false
},
"players": [
{
"id": 1,
"name": "Notch",
"uuid": "365bfa21803249ee9b634fe890c9d43f"
},
{
"id": 2,
"name": "7n",
"uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
},
{
"id": 3,
"name": "hfmx",
"uuid": "897a2737777a4776909a0148919c376a"
}
]
}
List the players who have commands due to be executed when they next login to the Minecraft Server.
This endpoint also returns if there are any offline commands to be processed and the amount of seconds
to wait before performing the queue check again. All clients should strictly follow the response of next_check
,
failure to do so would result in your secret key being revoked or IP address being banned from accessing the API.
Results are paginated using the page
and limit
request parameters. The more
parameter returned in the response body
indicates if there is another page to request.
Get offline commands
Endpoint
GET https://plugin.buycraft.net/queue/offline-commands
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue/offline-commands"
Example Response
{
"meta": {
"limited": false
},
"commands": [
{
"id": 1,
"command": "say Thank you for purchasing, {name}.",
"payment": 123,
"package": 123,
"conditions": {
"delay": 60
},
"player": {
"id": 1,
"name": "Notch",
"uuid": "365bfa21803249ee9b634fe890c9d43f"
}
},
{
"id": 2,
"command": "say Thank you for purchasing, {name}.",
"payment": 123,
"package": 123,
"conditions": {
"delay": 0
},
"player": {
"id": 2,
"name": "7n",
"uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
}
},
{
"id": 3,
"command": "say Thank you for purchasing, {name}.",
"payment": 123,
"package": 123,
"conditions": {
"delay": 0
},
"player": {
"id": 3,
"name": "hfmx",
"uuid": "897a2737777a4776909a0148919c376a"
}
}
]
}
Get the offline commands which are due to be executed.
These commands should be executed immediately and no checks are required against the related players.
Get online commands
Endpoint
GET https://plugin.buycraft.net/queue/online-commands/{player-id}
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue/online-commands/50"
Example Response
{
"commands": [
{
"id": 1,
"command": "give {name} TNT",
"payment": 123,
"package": 123,
"conditions": {
"delay": 0,
"slots": 0
}
},
{
"id": 2,
"command": "give {name} DIRT",
"payment": 123,
"package": 123,
"conditions": {
"delay": 0,
"slots": 0
}
},
{
"id": 3,
"command": "give {name} STONE",
"payment": 123,
"package": 123,
"conditions": {
"delay": 0,
"slots": 0
}
}
]
}
List the due online commands for a specific player.
These commands should only be executed when the player is online and all conditions have been met (such as if the player has the required amount of inventory slots).
Delete commands
Endpoint
DELETE https://plugin.buycraft.net/queue
Example Request
curl -X DELETE -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue?ids[]=1&ids[]=2&ids[]=3"
Example Response
Delete one or more commands which have been executed on the Minecraft Server.
An empty response consisting of a 204 No Content
status code will be returned on completion.
Parameters:
Name | Type | Description |
---|---|---|
ids | array | An array of one or more command IDs to delete. |
Listing
Endpoint
GET https://plugin.buycraft.net/listing
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/listing"
Example Response
{
"categories": [
{
"id": 1,
"order": 0,
"name": "Ranks",
"only_subcategories": false,
"subcategories": [],
"packages": [
{
"id": 1,
"order": 0,
"name": "Premium Membership",
"price": "4.99",
"sale": {
"active": false,
"discount": "0.00"
}
},
{
"id": 2,
"order": 1,
"name": "Ultimate Membership",
"price": "9.99",
"sale": {
"active": true,
"discount": "1.99"
}
}
]
}
]
}
Get the categories and packages which should be displayed to players in game.
The returned order of this endpoint does not reflect the desired order of the category/packages - please order based
on the order
object.
Payments
Endpoint
GET https://plugin.buycraft.net/payments
Example Request
curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/payments"
Example Response
[
{
"id": 1,
"amount": "4.99",
"date": "2016-01-27T15:40:19+0000",
"currency": {
"iso_4217": "GBP",
"symbol": "£"
},
"player": {
"id": 1,
"name": "Notch",
"uuid": "365bfa21803249ee9b634fe890c9d43f"
}
},
{
"id": 2,
"amount": "9.99",
"date": "2016-01-18T11:37:38+0000",
"currency": {
"iso_4217": "GBP",
"symbol": "£"
},
"player": {
"id": 2,
"name": "7n",
"uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
}
}
]
Get the recent payments for displaying on in-game payment signs.
A limit
parameter can be specified to restrict the amount of payments returned.
Please note that no more than 100 latest payments will be returned.
Checkout
Endpoint
POST https://plugin.buycraft.net/checkout
Example Request
curl -X POST -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/checkout?username=Notch&package_id=123"
Example Response
{
"url": "http://blocktastic.buycraft.net/buy/gj48f",
"expires": "2015-11-30T18:10:18+0000"
}
Creates a URL which will redirect the player to the webstore and add the package to their basket.
Parameters:
Name | Type | Description |
---|---|---|
username | string | The username of the Minecraft player. |
package_id | int | The ID of the package the player wants to purchase. |