API Introduction

The viigii API is organized around REST, and all API responses are returned as JSON, including errors. The API endpoint located at https://viigii.it/api/v1.

Vendor Authentication

All requests must come from a registered account so it is essential that you provide the correct website URL in your account details when you sign up. The vendor_auth method will test that the request originated from your domain and authenticate accordingly.

  • Method name: VendorAuth
  • Definition: GET https://viigii.it/api/v1/vendor_auth

Example request

curl -k https://viigii.it/api/v1/vendor_auth

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/vendor_auth',
  :method => :get,
  :verify_ssl => false
)

Example request

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/vendor_auth"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
$output=curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {}
}

Create a Customer

To send a virtual gift with viigii, you'll need to create a customer object. If the vendor token is present with a valid request, then the request will succeed. Otherwise we'll match the URL that originated the request with the vendor website URL.

  • Method name: AddCustomers
  • Definition: POST https://viigii.it/api/v1/customers
  • Request parameters:
    • sender_fname
      String
    • -

    • receiver_fname
      String
    • -

    • sender_email
      String
    • -

    • receiver_email
      String
    • -

    • cart_token
      String
    • -

    • vendor_token
      String
    • [Optional] Token received after signing up for viigii

    • virtual_gift_id
      String
    • [Optional]

  • Response parameters:
    • access_token
      String
    • The access_token will be used for creating gifts

Example request

curl \
  -k https://viigii.it/api/v1/customers \
  --data "sender_fname=Jane&sender_email=jane.doe@gmail.com&receiver_fname=John&receiver_email=john.doe@gmail.com&cart_token=425ced06a33b826c9286b085aa57fdc8&vendor_token=YOUR_VENDOR_TOKEN"

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/customers/',
  :method => :post,
  :payload => {
    sender_fname: 'Jane',
    sender_email: 'jane.doe@gmail.com',
    receiver_fname: 'John',
    receiver_email: 'john.doe@gmail.com',
    cart_token: '425ced06a33b826c9286b085aa57fdc8',
    vendor_token: 'YOUR_VENDOR_TOKEN'
  }.to_json,
    :headers => {:content_type => :json, :accept => :json},
    :verify_ssl => false
)

Example request

$params = array(
  "sender_fname" => "Jane",
  "sender_email" => "jane.doe@gmail.com",
  "receiver_fname" => "John",
  "receiver_email" => "john.doe@gmail.com",
  "cart_token" => "425ced06a33b826c9286b085aa57fdc8",
  "vendor_token": "YOUR_VENDOR_TOKEN"
);

$queryString = '';
foreach($params as $key => $value) {
  $queryString .= $key . '='.$value.'&';
}
$queryString = rtrim($queryString, '&');

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch,CURLOPT_URL, "https://viigii.it/api/v1/customers");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $queryString);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {
    "access_token": "5487b8ff16cca29559be2470da293cf1caed509a"
  }
}

Retrieve Customer Details

Retrieves the customer details of a viigii that has previously been created. Supply the cart token that was used for creating the customer and viigii will return the corresponding customer details.

  • Method name: GetCustomerDetails
  • Definition: GET https://viigii.it/api/v1/customers
  • Request parameters:
    • cart_token
      String
    • Cart token of the customer

  • Response parameters:
    • sender_name
      String
    • -

    • receiver_name
      String
    • -

    • sender_email
      String
    • -

    • receiver_email
      String
    • -

    • items
      Array
      • product_id
        Integer
      • -

      • product_name
        String
      • -

      • product_image_url
        String
      • -

Example request

curl -k https://viigii.it/api/v1/customers?cart_token=425ced06a33b826c9286b085aa57fdc8

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/customers/',
  :method => :get,
  :headers => {
    :params => {cart_token: '425ced06a33b826c9286b085aa57fdc8'},
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/customers?cart_token=425ced06a33b826c9286b085aa57fdc8"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
$output=curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {
    "sender_name": "Jane",
    "receiver_name": "John",
    "sender_email": "jane.doe@gmail.com",
    "receiver_email": "john.doe@gmail.com",
    "items": {
      "product_id": 650,
      "product_name": "Ulysses",
      "product_image_url": "https://upload.wikimedia.org/wikipedia/commons/a/ab/JoyceUlysses2.jpg"
    }
  }
}

Modify Customer Details

Edit the customer details of a viigii that has previously been created. Supply the cart token that was used to create the customer in the URL.

  • Method name: EditCustomers
  • Definition: PUT https://viigii.it/api/v1/customers/:cart_token
  • Request parameters:
    • sender_fname
      String
    • [Optional]

    • receiver_fname
      String
    • [Optional]

    • sender_email
      String
    • -

    • receiver_email
      String
    • [Optional]

    • cart_token
      String
    • This must be present in the url

Example request

curl \
  -k https://viigii.it/api/v1/customers/425ced06a33b826c9286b085aa57fdc8 \
  -X PUT \
  --data "sender_email=janet.doe@gmail.com&sender_fname=Janet"

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/vendor_auth/425ced06a33b826c9286b085aa57fdc8',
  :method => :put,
  :payload =>{
    sender_fname: 'Janet',
    sender_email: 'janet.doe@gmail.com'
  }.to_json,
  :headers => {
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$params = array(
  'sender_email' => 'janet.doe@gmail.com,'
  'sender_fname' => 'Janet'
);

$queryString = '';
foreach($params as $key => $value) {
  $queryString .= $key . '='.$value.'&';
}
$queryString = rtrim($queryString, '&');

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = 'https://viigii.it/api/v1/vendor_auth/425ced06a33b826c9286b085aa57fdc8'
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, PUT);
curl_setopt($ch,CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $queryString);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {}
}

Delete a Customer

Delete the customer details of a viigii that has previously been created. Supply the cart token that was used to create the customer in the URL.

  • Method name: DeleteCustomers
  • Definition: DELETE https://viigii.it/api/v1/customers/:cart_token
  • Request parameters:
    • cart_token
      String
    • This must be present in the url

Example request

curl \
  -k https://viigii.it/api/v1/customers/425ced06a33b826c9286b085aa57fdc8 \
  -X DELETE

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/vendor_auth/425ced06a33b826c9286b085aa57fdc8',
  :method => :delete,
  :headers => {
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/vendor_auth/425ced06a33b826c9286b085aa57fdc8"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, DELETE");
curl_setopt($ch,CURLOPT_HEADER, false);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {}
}

Add a Gift

Add a gift to an existing customer object.

  • Method name: AddGift
  • Definition: POST https://viigii.it/api/v1/gift_item
  • Request parameters:
    • access_token
      String
    • The access_token of a customer received from AddCustomer API response

    • product_name[]
      Array[String]
    • Comma separated product names

    • product_image_url
      Array[String]
    • Comma separated product image urls

Example request

curl \
  -k https://viigii.it/api/v1/gift_item \
  --data "access_token=5487b8ff16cca29559be2470da293cf1caed509a&product_name[]=Ulysses&product_image_url[]=https://upload.wikimedia.org/wikipedia/commons/a/ab/JoyceUlysses2.jpg"

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/gift_item/',
  :method => :post,
  :payload => body.to_json,
  :headers => {
    :content_type =>
    :json, :accept => :json
  },
  :verify_ssl => false
)

Example request

$params = Array(
  'access_token'=> '5487b8ff16cca29559be2470da293cf1caed509a',
  'product_name' => ['Ulysses'],
  'product_image_url' => ['https://upload.wikimedia.org/wikipedia/commons/a/ab/JoyceUlysses2.jpg'],
);

$queryString = '';
$queryString .= 'access_token='.$params['access_token'];
$image_url = '';
$name = '';
foreach($params['product_name'] as $item) {
  $name .='product_name[]='.$item.'&';
}
foreach($params['product_image_url'] as $image) {
  $image_url .= 'product_image_url[]='.$image.'&';
}
$image_url = rtrim($image_url,'&');
return $queryString.'&'.$name.$image_url;

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/gift_item"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $queryString);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {
    "redirect_url": "https://viigii.it/..."
  }
}

Retrieve a Gift

Retrieve a gift object.

  • Method name: GetGiftDetails
  • Definition: GET https://viigii.it/api/v1/gift_item
  • Request parameters:
    • access_token
      String
    • The access_token of a customer received from AddCustomer API response

  • Response parameters:
    • product_id
      Integer
    • -

    • product_name
      String
    • -

    • product_image_url
      String
    • -

Example request

curl -k https://viigii.it/api/v1/gift_item?access_token=5487b8ff16cca29559be2470da293cf1caed509a

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/gift_item/',
  :method => :get,
  :headers => {
    :params => {
      access_token: '5487b8ff16cca29559be2470da293cf1caed509a'
    },
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/gift_item?access_token=5487b8ff16cca29559be2470da293cf1caed509a"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {
    "650": {
      "product_name": "Ulysses",
      "product_image_url": "https://upload.wikimedia.org/wikipedia/commons/a/ab/JoyceUlysses2.jpg"
    }
  }
}

Modify a Gift

Modify a gift object.

  • Method name: EditGift
  • Definition: PUT https://viigii.it/api/v1/gift_item/:product_id
  • Request parameters:
    • access_token
      String
    • The access_token of a customer received from AddCustomer API response

    • id
      Integer
    • The product id received from GetGiftDetails API response. It must be present in the url

    • product_name
      String
    • [Optional] If it is not present, then product_image_url must be present.

    • product_image_url
      String
    • [Optional] If it is not present, then product_name must be present.

Example request

curl \
-k https://viigii.it/api/v1/gift_item/650 \
-X PUT \
--data "access_token=5487b8ff16cca29559be2470da293cf1caed509a&product_name=Odysseus"

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/gift_item/650',
  :method => :put,
  :payload => {
    access_token: '5487b8ff16cca29559be2470da293cf1caed509a',
    product_name: 'Odysseus'
  }.to_json,
  :headers => {
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$params = array(
  "access_token" => "5487b8ff16cca29559be2470da293cf1caed509a",
  "product_name" => "Odysseus"
);

$queryString = '';
foreach($params as $key => $value) {
  $queryString .= $key . '='.$value.'&';
}
$queryString = rtrim($queryString, '&');

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/gift_item/650"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch,CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $queryString);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {}
}

Delete a Gift

Delete the gift details of a viigii that has previously been created. Supply the access token returned from your AddCustomer request and the product id returned from your item details request. Product id must be present in the URL.

  • Method name: DeleteGift
  • Definition: DELETE https://viigii.it/api/v1/gift_item/:product_id
  • Request parameters:
    • access_token
      String
    • The access_token of a customer received from AddCustomer API response

    • id
      Integer
    • The product id received from GetItemDetails API response. It must be present in the url.

Example request

curl \
-k https://viigii.it/api/v1/gift_item/650 \
-X DELETE \
--data "access_token=5487b8ff16cca29559be2470da293cf1caed509a"

Example request

RestClient::Request.execute(
  :url => 'https://viigii.it/api/v1/gift_item/650',
  :method => :delete,
  :payload => {
    access_token: '5487b8ff16cca29559be2470da293cf1caed509a'
  },
  :headers => {
    :content_type => :json,
    :accept => :json
  },
  :verify_ssl => false
)

Example request

$params = array(
  "access_token" => '5487b8ff16cca29559be2470da293cf1caed509a'
);

$queryString = '';
foreach($params as $key => $value) {
  $queryString .= $key . '='.$value.'&';
}
$queryString = rtrim($queryString, '&');

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$url = "https://viigii.it/api/v1/gift_item/650"
curl_setopt($ch,CURLOPT_URL,$url);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch,CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $queryString);
curl_exec($ch);
curl_close($ch);

Example response

{
  "result": 1,
  "data": {}
}