Vulcan API Reference

The Vulcan API provides endpoints for managing redemption gifts in the TKM AI Agency Platform. It handles the creation, retrieval, updating, and deletion of gifts that users can redeem with their loyalty points.

Base URL

/api/gifts

Endpoints

Get All Gifts

GET /gifts

Retrieves a list of all available gifts.

Response

{
  "success": true,
  "gifts": [
    {
      "id": "string",
      "gift_name": "string",
      "gift_type": "string",
      "country": "string",
      "url_photo": "string",
      "telco_supplier": "string",
      "recharge_amount": "number",
      "points_value": "number",
      "supplier": "string",
      "electronic_pin_amount": "number",
      "service_provider": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

Get Gift by ID

GET /gifts/{gift_id}

Retrieves a specific gift by its ID.

Parameters

Name	Type	Description
gift_id	string	The unique identifier of the gift

Response

{
  "success": true,
  "gift": {
    "id": "string",
    "gift_name": "string",
    "gift_type": "string",
    "country": "string",
    "url_photo": "string",
    "telco_supplier": "string",
    "recharge_amount": "number",
    "points_value": "number",
    "supplier": "string",
    "electronic_pin_amount": "number",
    "service_provider": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

Create Gift

POST /gifts

Creates a new gift.

Request Body

{
  "gift_name": "string",
  "gift_type": "string",
  "country": "string",
  "url_photo": "string",
  "telco_supplier": "string",
  "recharge_amount": "number",
  "points_value": "number",
  "supplier": "string",
  "electronic_pin_amount": "number",
  "service_provider": "string"
}

Gift Types and Required Fields

Gift Type	Required Fields
mobile_top-ups	telco_supplier, recharge_amount, points_value
electronic_pins	supplier, electronic_pin_amount, points_value
service_payments	service_provider

Response

{
  "success": true,
  "gift": {
    "id": "string",
    "gift_name": "string",
    "gift_type": "string",
    "country": "string",
    "url_photo": "string",
    "telco_supplier": "string",
    "recharge_amount": "number",
    "points_value": "number",
    "supplier": "string",
    "electronic_pin_amount": "number",
    "service_provider": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

Update Gift

PUT /gifts/{gift_id}

Updates an existing gift.

Parameters

Name	Type	Description
gift_id	string	The unique identifier of the gift

Request Body

{
  "gift_name": "string",
  "gift_type": "string",
  "country": "string",
  "url_photo": "string",
  "telco_supplier": "string",
  "recharge_amount": "number",
  "points_value": "number",
  "supplier": "string",
  "electronic_pin_amount": "number",
  "service_provider": "string"
}

Response

{
  "success": true,
  "gift": {
    "id": "string",
    "gift_name": "string",
    "gift_type": "string",
    "country": "string",
    "url_photo": "string",
    "telco_supplier": "string",
    "recharge_amount": "number",
    "points_value": "number",
    "supplier": "string",
    "electronic_pin_amount": "number",
    "service_provider": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

Delete Gift

DELETE /gifts/{gift_id}

Deletes a specific gift.

Parameters

Name	Type	Description
gift_id	string	The unique identifier of the gift

Response

{
  "success": true,
  "message": "Gift deleted successfully"
}

Error Responses

All endpoints can return the following error responses:

{
  "success": false,
  "error": "Error message description"
}

Common error scenarios:

Gift not found (404)
Invalid gift type or missing required fields (400)
Server error (500)

Messor Yuno