Logo
HTTP/cURL PHP Python Javascript

Introduction

To use Kinow API

You must:

Overview

Response format

Responses are returned in JSON.

All returned lists contained an pagination object and a data object. This data object is a list that contains all items fetched.

When it’s a single item, object returned directly.

Post method to create new item return the new object created.

If their is no object created, or call is a delete method, the return is empty and you must check the http code. 204 is used when it’s ok and 4** when an error is triggered.

Pagination

All routes that return a list can be paginated.

curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    "https://api.kinow.com/api/customers?per_page=10&page=2"

This pagination take two parameters, page and per_page. page argument is the number of the page to get and per_page is the number of the items per page. The number per page default value is 50, you can up to 100 items per page.

{
  "pagination": {
    "total": 100,
    "current_page": 2,
    "per_page": 10,
    "last_page": 5,
    "next_page_url": "https://api.kinow.com/api/customers?per_page=10&page=3",
    "prev_page_url": "https://api.kinow.com/api/customers?per_page=10&page=1",
    "from": 10,
    "to": 20
  },
  "data": [...]
}

Parameters

Name Details
page Number of the page to get
per_page Number of items per page

Return

Name Details
total The total number of items returned by the query
current_page The page being returned
last_page The number of pages required to list all items
next_page_url The url of the next page
prev_page_url The url of the previous page
from The index of the first item returned on the current page
to The index of the last item returned on the current page

API Versionning

COMING SOON

STEP 1 - Installation

To consume this API, you can use http to fetch routes.

All methods are described here. You can test directly all methods in this page.

You can also use a SDK. For now, two languages are available, PHP and Python.

PHP

Manually

<?php
require_once __DIR__ . '/path-to-kinow-client/KaemoClient/autoload.php';
$client_id = 'YOUR_CLIENT_ID';
$client_secret = 'YOUR_CLIENT_SECRET';

$api = new \Kaemo\Client\Api\OAuthApi();
$result = $api->getToken($client_id, $client_secret);

First, download the php sdk.

Extract zip content to your choosen directory, then include the autoload file in your php file.

Show php sample

Composer

Method 1:

To install the bindings via Composer, type in your console: composer require kinow-io/kaemo-php-sdk

Method 2:

To install the bindings via Composer, add the following to composer.json:

{ 
    "repositories": [{
        "type": "git",
        "url": "https://github.com/kinow-io/kameo-php-sdk.git"
    }],
    "require": {
        "kinow-io/kameo-php-sdk": "^1.0"
    }
}

Then run composer install

Python

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package: python import kaemo_client

Javascript

NPM:

npm i kinow-javascript-sdk

npm i kinow-javascript-sdk

From Source

Sources can be fond in the sdk repository

STEP 2 - Authentication

Generate API Keys

Capture_d_écran_2017-02-10_à_12.46.04

First, you need a Client Id and a Client Secret to use the Kinow API.

You can generate them in your Kinow backoffice in Shop settings > General settings under the API tab.

Get authentication token

# With shell, you can just pass the correct header with each request
curl -X POST 
    -F "client_id=YOUR_CLIENT_ID" 
    -F "client_secret=YOUR_CLIENT_SECRET"
    "https://api.kinow.com/api/get-token"
<?php
$client_id = 'YOUR_CLIENT_ID';
$client_secret = 'YOUR_CLIENT_SECRET';

$api = new \Kaemo\Client\Api\OAuthApi();
$result = $api->getToken($client_id, $client_secret);

var_dump($result);
client_id = "2ba3025821fb65c50e28f1e4f917df04"
client_secret = "$2y$10$FYqXF3ofUtweDYClNNfftemGZPEXZ.b/lj9WMhe6wIPqTXAMYfxmG"

try:
    api_response = api_instance.get_token(client_id, client_secret)
    pprint(api_response)
except ApiException as e:
    print "Exception when calling OAuthApi->get_token: %s\n" % e
const KinowSDK = require('kinow-javascript-sdk')
const clientId = 'YOUR_CLIENT_ID'
const clientSecret = 'YOUR_CLIENT_SECRET'

// Kinow Auth
new KinowSDK.OAuthApi()
  .getToken(clientId, clientSecret)
  .then(data => {
    // Add authorization header for all requests
    KinowSDK.ApiClient.instance.defaultHeaders['Authorization'] = data.token_type + ' ' + data.access_token

    // Auth success
  })
  .catch(e => console.log(e))

Once your API key are generated, you can use them to get an authentication token. This token is valid one hour and will be sent to all http requests in the Authentication header.

To get this token, you must call https://api.kinow.com/api/get-token with your Client id and Client Secret as parameter.

Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET_ID with your API credentials.

{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...",
  "refresh_token":"P2v4B+aLW8JzpT7QsJBbfIM6kA2fXMoDqB..."
}

Http requests

curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    "https://api.kinow.com/api/customers"
<?php
// Set client authentication
$configuration = new \Kaemo\Client\Configuration();
$configuration->addDefaultHeader('Authorization', $result->getTokenType() . ' ' . $result->getAccessToken());

// Initialize api client with configuration
$apiClient = new \Kaemo\Client\ApiClient($configuration);

use \Kaemo\Client\Api\CustomersApi;
$customersApi = new CustomersApi($apiClient);
$customers = $customersApi->getCustomers();
var_dump($customers->getData());
api_client.set_default_header('Authorization', api_response.token_type + ' ' + api_response.access_token)


api_customers = kaemo_client.CustomersApi(api_client)

try:
    customers = api_customers.get_customers()
    pprint(customers)
except ApiException as e:
    print "Exception when calling CustomersApi->get_customers: %s\n" % e
var KinowSDK = require('kinow-javascript-sdk')
var apiCustomers = new KinowSDK.CustomersApi()

apiCustomers.getCustomers()
    .then(data => console.log('API called successfully. Returned data: ' + data))
    .catch(e => console.log(e))

All requests you send at api.kinow.com must have an http header Authorization containing the token type and the token access.

If token is missing or incorrect, a 403 error will be returned.

Make sure to replace YOUR_ACCESS_TOKEN with the access_token given by the previous step.

STEP 3 - Customer registration

Now we will see how to register a customer using the API.

Customer registration example

Fetch coutries

First, we fetch all the countries to create select field to pick the correct id country.

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "https://api.kinow.com/api/countries?bypass_pagination=true"
<?php
use \Kaemo\Client\Api\CountriesApi;

$countriesApi = new CountriesApi($apiClient);
$countries = $countriesApi->getCountries(
    null/* page number */,
    null /* items per page */,
    true /* bypass pagination */
);
api_country = kaemo_client.CountriesApi(api_client)
countries = api_country.get_countries()
pprint(countries)
const apiCountries = new KinowSDK.CountriesApi()

apiCountries.getCountries()
  .then(data => console.log(data))
{
  "pagination": {...},
  "data": [
    {"id": "231",
      "iso_code": "AF",
      "name": [{"lang": 0, "value": "Afghanistan"}]
    },
    ...
  ]
}

You can set bypass_pagination at true to fetch all the coutries at the same time. This parameter works only for this route.

Create customer

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
-d "{
  \"lastname\": \"Lastname\",
  \"firstname\": \"Firstname\",
  \"email\": \"customer@your-company.com\",
  \"passwd\": \"password\",
  \"id_country\": 8

}" "https://api.kinow.com/api/customers"
<?php
$body = new \Kaemo\Client\Model\Customer();
$body
    ->setEmail('customer@your-company.com')
    ->setFirstname('Firstname')
    ->setLastname('Lastname')
    ->setPassword('password')
    ->setIdCountry(8);

$customer = $customersApi->createCustomer($body);
api_response = api_instance.get_token(client_id, client_secret)
api_client.set_default_header('Authorization', api_response.token_type + ' ' + api_response.access_token)

customer = kaemo_client.Customer()
customer.email = 'customer@your-company.com'
customer.firstname = 'Firstname'
customer.lastname = 'Lastname'
customer.password = 'password'
customer.id_country = 8
api_customers = kaemo_client.CustomersApi(api_client)

new_customer = api_customers.create_customer(customer)
const apiCustomers = new KinowSDK.CustomersApi()

const customer = {
  firstname: 'firstname',
  lastname: 'lastname',
  email: 'customer@your-company.com',
  password: 'password',
  id_country: 8
}

apiCustomers.createCustomer(customer)
  .then(data => console.log(data))
  .catch(e => console.log(e))
{
  "id": 42,
  "lastname": "Lastname",
  "firstname": "Firstname",
  "email": "customer@your-company.com",
  "id_gender": "0",
  "birthday": "0000-00-00",
  "newsletter": "0",
  "optin": "0",
  "active": "1",
  "id_lang": "1",
  "date_add": "2017-05-04 13:37:42",
  "date_upd": "2017-05-04 13:37:42"
}

Once you have the country list, you can create a new customer by calling in POST method the url https://api.kinow.com/api/customers with the following parameters:

Name Description
firstname Firstname of the customer to register
lastname Lastname of the customer to register
email Email address of the customer to register
password Password of the customer to register (will be hashed on Kinow API side)
Id country Country of the customer to register

The API return you the customer that was created.

STEP 4 - Customer login

In this step, we will see how the customer we created in the last step will connect to your website using the API.

Customer registration example

Login

curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    -d "email=customer%40your-company.com&password=password" 
    "https://api.kinow.com/api/customers/check-credentials"
<?php
use \Kaemo\Client\Api\CustomersApi;
$customersApi = new CustomersApi($apiClient);
$customer = $customersApi->checkCustomerCredentials('customer@your-company.com', 'password');
api_customers = kaemo_client.CustomersApi(api_client)
customer = api_customers.check_customer_credentials('customer@your-company.com', 'password')
apiCustomers.checkCustomerCredentials('customer@your-company.com', 'password')
  .then(data => console.log(data))
  .catch(e => console.log(e))
{
  "id": 42,
  "lastname": "Lastname",
  "firstname": "Firstname",
  "email": "customer@your-company.com",
  "id_gender": "0",
  "birthday": "0000-00-00",
  "newsletter": "0",
  "optin": "0",
  "active": "1",
  "id_lang": "1",
  "date_add": "2017-05-04 13:37:42",
  "date_upd": "2017-05-04 13:37:42"
}

You can check user credential by calling https://api.kinow.com/api/customers/check-credentials in POST method with email and password parameters.

Email parameter must be a valid email address and password parameter must be over or equal the 5 characters.

If credentials are correct, API will return you the customer object, instead, an error will be returned (see table below).

Error Code Meaning
400 Bad Request – Email or password are in bad format
403 Forbidden – Email or password mismatch

STEP 5 - Retrieve products

Customer registration example

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "http://api.kinow.com/api/products"
<?php
use \Kaemo\Client\Api\ProductsApi;
$productsApi = new ProductsApi($apiClient);
$products = $productsApi->getProducts();
var_dump($products->getData());
api_products = kaemo_client.ProductsApi(api_client)
products = api_products.get_products()
pprint(products)
const apiProducts = new KinowSDK.ProductsApi()
apiProducts.getProducts()
  .then(data => console.log(data))
{
  "pagination": {
    ...
  },
  "data": [
    {
      "id": "2",
      "reference": "",
      "date_from": "2016-05-04 13:37:42",
      "date_to": "2017-05-04 13:37:42",
      "price": "3.000000",
      "active": "1",
      "available_for_order": "1",
      "date_add": "2017-05-04 13:37:42",
      "date_upd": "2017-05-04 13:37:42",
      "meta_description": [...],
      "meta_keywords": [...],
      "meta_title": [...],
      "link_rewrite": [...],
      "name": [...],
      "description": [...],
      "description_short": [...]
    }, ...
  ]
}

To get product list, you must call https://api.kinow.com/api/products, this method can have pagination parameter.

There is no filter at the moment, if you want to sort by date or something else, you have to do it on your side.

STEP 6 - Cart management

Customer registration example

To create a new cart, we need to initialize it with the customer id, the lang id and the currency id.

We will start by fetching languages and currencies enabled in your platform.

Fetch currencies

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "http://api.kinow.com/api/currencies"
<?php
use Kaemo\Client\Api\CurrenciesApi;
$currenciesApi = new CurrenciesApi($apiClient);
$currencies = $currenciesApi->getCurrencies();
var_dump($currencies->getData());
api_currencies = kaemo_client.CurrenciesApi(api_client)
currencies = api_currencies.get_currencies()
pprint(currencies)
const apiCurrencies = new KinowSDK.CurrenciesApi()
apiCurrencies.getCurrencies()
  .then(data => console.log(data))
{
  "pagination": {...},
  "data": [
    {
      "id": "1",
      "name": "Euro",
      "iso_code": "EUR",
      "iso_code_num": "978",
      "sign": "€"
    },
    ...
  ]
}

Fetch languages

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "http://api.kinow.com/api/languages"
<?php
use Kaemo\Client\Api\LanguagesApi;
$currenciesApi = new LanguagesApi($apiClient);
$currencies = $currenciesApi->getLanguages();
var_dump($currencies->getData());
api_languages = kaemo_client.LanguagesApi(api_client)
languages = api_languages.get_languages()
pprint(languages)
const apiLanguages = new KinowSDK.LanguagesApi()
apiLanguages.getLanguages()
  .then(data => console.log(data))
{
  "pagination": {...},
  "data": [
    {
      "id": "1",
       "name": "Français",
       "iso_code": "fr",
       "active": "1"
    },
    ...
  ]
}

Create new cart

Now, we have a customer, currencies list and languages list. We can now create our first cart.

curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
-d "{
  \"id_currency\": 1,
  \"id_lang\": 1,
  \"id_customer\": 0
}" "https://api.kinow.com/api/carts"
<?php
use \Kaemo\Client\Api\CartsApi;

$cartsApi = new CartsApi($apiClient);
$cartBody = new \Kaemo\Client\Model\Cart();
$cartBody->setIdCustomer(1);
$cartBody->setIdCurrency(1);
$cartBody->setIdLang(1);
$cart = $cartsApi->createCart($cartBody);
var_dump($cart);
cart_body = kaemo_client.Cart()
cart_body.id_customer = 1
cart_body.id_currency = 1
cart_body.id_lang = 1

cart_api = kaemo_client.CartsApi(api_client)
cart = cart_api.create_cart(cart_body)
pprint(cart)
const apiCarts = new KinowSDK.CartsApi()
const cart = {
  id_currency: 1,
  id_customer: 1,
  id_lang: 1
}
apiCarts.createCart({ body: cart })
  .then(data => console.log('Cart: ' + data))
  .catch(e => console.log(e))
{
  "id": 42,
  "id_currency": "1",
  "id_customer": "1",
  "id_lang": "1",
  "date_add": "2017-05-04 13:37:42",
  "date_upd": "2017-05-04 13:37:42",
  "products": []
}

Add product to cart

curl -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    -d "product_id=1" 
    "https://api.kinow.com/api/carts/42/products"
<?php
use \Kaemo\Client\Api\ProductsApi;
$productApi = new ProductsApi($apiClient);
$product = $productApi->getProduct(1);
$cart = $cartsApi->addProductToCart($cart->getId(), $product->getId());
api_product = kaemo_client.ProductsApi(api_client)
product = api_product.get_product(1)

api_cart = kaemo_client.CartsApi(api_client)
response = api_cart.add_product_to_cart(1, 1)

pprint(response)
const productId = 2
apiCarts.addProductToCart(cart.id, productId)
  .then(data => console.log(data))
  .catch(e => console.log(e))
{
  "id": 42,
  "id_currency": "1",
  "id_customer": "1",
  "id_lang": "1",
  "date_add": "2017-05-04 13:37:12",
  "date_upd": "2017-05-04 13:37:12",
  "products": [
    {
      "id_product_attribute": "0",
      "id_product": "1",
      "name": "...",
      "description_short": "...",
      ...
    }
  ]
}

Remove product from cart

curl -X DELETE -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    -d "product_id=1" 
    "https://api.kinow.com/api/carts/42/products"
<?php
$cart = $cartsApi->deleteProductFromCart($cart->getId(), $product->getId());
api_cart = kaemo_client.CartsApi(api_client)
response = api_cart.delete_product_from_cart(cart.id, product.id)
pprint(response)
apiCarts.deleteProductFromCart(cart.id, productId)
  .then(data => console.log(data))
Error Code Meaning
204 Successful operation – Successful operation
400 Bad Request – Unable to delete product from cart
404 Not found – Cart or product not found

STEP 7 - Payment process

Get payment modules

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "https://api.kinow.com/api/payment-modules"
<?php
use \Kaemo\Client\Api\PaymentModulesApi;
$paymentModulesApi = new PaymentModulesApi($apiClient);
$paymentModules = $paymentModulesApi->getPaymentModules();
var_dump($paymentModules->getData());
api_payment = kaemo_client.PaymentModulesApi(api_client)
payment_modules = api_payment.get_payment_modules()
pprint(payment_modules)
const apiPayments = new KinowSDK.PaymentModulesApi()
apiPayments.getPaymentModules()
  .then(data => console.log(data))
{
  "pagination": {...},
  "data": [
    {
      "id": "1",
      "name": "stripe",
      "displayName": "Stripe",
      "description": "Avec Stripe vous pouvez accepter les paiements par carte de crédit et Bitcoin."
    },
    ...
  ]
}

Get payment url

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
    "https://api.kinow.com/api/carts/42/payments/stripe"
<?php
$paymentModule = $paymentModulesApi->getPaymentUrl($cart->getId(), 'stripe');
var_dump($paymentModule);
api_payment = kaemo_client.PaymentModulesApi(api_client)
payment_link = api_payment.get_payment_url(cart.id, 'stripe')
apiPayments.getPaymentUrl(cart.id, 'stripe')
  .then(data => console.log(data))

STEP 8 - Get video player

Get video player

Check customer accesses

Before getting video player, we must check if customer has access to this video. To do this we will call /customers/{customer_id}/videos/{video_id}/has-access width customer_id and video_id as parameters

At this step, we just have the customer id and the product id, we must fetch the video id.

Get video id

Videos are attached to a product. To get videos, we will call /products/{product_id}/videos with product_id as parameter.

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    "https://api.kinow.com/api/products/1/videos"
<?php
use \Kaemo\Client\Api\ProductsApi;
$productApi = new ProductsApi($apiClient);
$videos = $productApi->getVideosFromProduct(1);
var_dump($videos->getData());
api_product = kaemo_client.ProductsApi(api_client)
videos = api_product.get_videos_from_product(6)
pprint(videos)
const apiProducts = new KinowSDK.ProductsApi()
apiProducts.getVideosFromProduct(product.id)
  .then(data => console.log(data))
{
  "pagination": {...},
  "data": [
    {
      "id": "1",
      "id_product": "1",
      "id_language": "1",
      "language_filter": "0",
      "id_media_source": "5",
      "name": [...],
      "description": [...],
      "duration": "90",
      "filename": "73320806",
      ...
    }
  ]
}

Check access

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    "https://api.kinow.com/api/customers/1/videos/1/has-access"
<?php
use Kaemo\Client\Api\CustomersApi;
$customerApi = new CustomersApi($apiClient);
try {
    $hasAccess = $customerApi->getCustomerHasAccessToVideo(1, 1);
} catch (Exception $e) {
    var_dump($e->getCode(), $e->getMessage());
}
api_customer = kaemo_client.CustomersApi(api_client)
has_access = api_customer.get_customer_has_access_to_video(1, 1)
pprint(has_access)
const apiCustomers = new KinowSDK.CustomersApi()
apiCustomers.getCustomerHasAccessToVideo(customer.id, video.id)
  .then(data => console.log(data))
  .catch(e => console.log(e))
Error Code Meaning
204 Success – Customer has access to this video
403 Forbidden – Customer don’t have access to this video
404 Not found – Customer or video not found

Get video url

curl -X GET -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    "https://api.kinow.com/api/customers/1/videos/1/player"
<?php
$videosApi = new VideosApi($apiClient);
$video_id = 789; // int | Video ID to fetch
$customer_id = 789; // int | Customer ID to fetch (optional)
$country_id = 789; // int | Country ID to use in video analytics (optional)
$result = $videosApi->getVideoPlayer($video_id, $customer_id, $country_id);
var_dump($result->getUrl());
api_videos = kinow_client.VideosApi(api_client)
video_id = 789 # int | Video ID to fetch
customer_id = 789 # int | Customer ID to fetch (optional)
country_id = 789 # int | Country ID to use in video analytics (optional)

result = api_videos.get_video_player(video_id, customer_id=customer_id, country_id=country_id)
pprint(result.url)
const apiVideos = new KinowSDK.VideosApi()

// Optional
var options = {
  customerId: customer.id, // Customer ID to use in video analytics (optional)
  countryId: customer.id_country // Country ID to use in video analytics (optional)
}

apiVideos.getVideoPlayer(video.id, options)
  .then(data => console.log(data))
  .catch(e => console.log(e))
const apiVideos = new KinowSDK.VideosApi()

var options = {
  customerId: customer.id,
  countryId: customer.id_country
}

apiVideos.getVideoPlayer(video.id, options)
  .then(data => console.log(data))
  .catch(e => console.log(e))
{
  "url": "http://www.dev.km/fr/?authentication_token=XXX&back=https%3A%2F%2Fwww.your-company.com%2Ffr%2Fw%2Fmy-movie%2Fvideo-player.html%3Fcontent_only%3D1&iframe_only=1"
}