Введение
Это страница документации API KWIGA. С помощью данного API вы имеете возможностью производить некоторые действия в от своего имени в определённых кабинетах.
Для того чтобы включить API, в личном кабинете в разделе settings нужно нажать на соответсвующий чекбокс. После этого будет сгенерирован токен для API и получен хеш кабинета, которые нужны для последующих обращений к API.
При компрометации токена его можно перевыпустить, что сделает прошлый токен неактивным и сгенерирует новый.
API доступен только для тех пользователей у кого в кабинете включено API.
API имеет ограничение на количество обращений в секунду. Сейчас доступно 1 обращение в секунду.
Базовая работа с API
<?php
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$id = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts/' . $id);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/contacts/1
Все запросы должны отправляться на домен:
https://api.kwiga.com
Для авторизации передаём API-токен в заголовках как Token:
Token: {token}
Для идентификации кабинета, в котором происходят действия, обязательно передаём хеш-кабинета в заголовках:
Cabinet-Hash: {cabinet_hash}
Ошибки
Код ошибки | Значение |
---|---|
400 | Bad Request - Ваш запрос неверен. |
401 | Unauthorized - Ошибка авторизации. Ваш API-ключ неверен. |
403 | Forbidden - Запрошенный ресурс спрятан и доступен только администраторам. |
404 | Not Found - Не найдено. Указанная страница не найдена. |
405 | Method Not Allowed - Метод не разрешен. Серверу известен метод запроса, но целевой ресурс не поддерживает этот метод. |
406 | Not Acceptable - Не принято. Вы запросили формат, отличный от json. |
410 | Gone - Запрошенный ресурс удален с нашего сервера. |
422 | Unprocessable entity - Сущность невозможно обработать. |
429 | Too Many Requests - Очень много запросов. Вы отправляете слишком много запросов, остановитесь! |
500 | Internal Server Error - Внутренняя ошибка сервера. Проблема с нашим сервером. Повторите попытку позже. |
503 | Service Unavailable - Сервис недоступен. Мы временно отключены от сети в связи с техническим обслуживанием. Повторите попытку позже. |
CRM. Контакты
Список контактов
Пример запроса:
<?php
// Запрос без параметров
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
<?php
// Запрос с пагинацией
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts?page=1&per_page=500');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
<?php
// Запрос с пагинацией и фильтрацией
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts?page=1&per_page=500&filters[date_from]=2022-04-27&filters[search]=Ivanov');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/contacts
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/contacts?page=1&per_page=500
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/contacts?page=1&per_page=500&filters[date_from]=2022-04-27&filters[search]=Ivanov
Пример ответа:
{
"data": [
{
"id": 1,
"created_at": "2022-02-04T12:17:32.000000Z",
"email": "test@example.com",
"first_name": "James",
"last_name": "Bond",
"phone": "+380931234567"
},
{
"id": 2,
"created_at": "2022-02-04T12:17:32.000000Z",
"email": "test2@example.com",
"first_name": "Petr",
"last_name": "Ivanov",
"phone": "+380983234512"
}
],
"links": {
"first": "https://api.kwiga.com/contacts?page=1",
"last": "https://api.kwiga.com/contacts?page=2",
"prev": null,
"next": "https://api.kwiga.com/contacts?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 2,
"links": [
{
"url": null,
"label": "« Предыдущая",
"active": false
},
{
"url": "https://api.kwiga.com/contacts?page=1",
"label": "1",
"active": true
},
{
"url": "https://api.kwiga.com/contacts?page=2",
"label": "2",
"active": false
},
{
"url": "https://api.kwiga.com/contacts?page=2",
"label": "Следующая »",
"active": false
}
],
"path": "https://api.kwiga.com/contacts",
"per_page": 2,
"to": 2,
"total": 3
}
}
HTTP Request
GET https://api.kwiga.com/contacts
URL Parameters
Parameter | Description |
---|---|
page (integer) |
Номер страницы |
per_page (integer) |
Кол-во элементов выборки |
filters[is_active] (integer) |
Фильтр по активных контактам |
filters[date_from] (2022-04-27) |
Фильтр по дате создания. Параметр 'от' |
filters[date_to] (2022-04-29) |
Фильтр по дате создания. Параметр 'до' |
filters[search] (string) |
Фильтр по email, телефону, ФИО |
Получение контакта
Пример запроса:
<?php
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$id = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts/' . $id);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/contacts/1
Пример ответа:
{
"data": [
{
"id": 1,
"created_at": "2022-02-04T12:17:32.000000Z",
"email": "test@example.com",
"first_name": "James",
"last_name": "Bond",
"phone": "+380931234567",
"tags": [
{
"id": 2,
"name": "tag1",
"created_at": "2022-02-14T08:58:38.000000Z"
}
]
}
]
}
HTTP Request
GET https://api.kwiga.com/contacts/{id}
Создание контакта
Пример запроса:
$headers = [
'Accept: application/json',
'Content-Type: application/x-www-form-urlencoded',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$data = [
'first_name' => 'James',
'last_name' => 'Bond',
'email' => 'test@example.com',
'phone' => '+380931234567',
'tags' => ['tag1'],
'send_activation_email' => true,
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts/');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response);
curl -X POST -H 'Accept: application/json' -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -H 'Content-Type: application/json' -d '{"first_name" : "James", "last_name" : "Bond", "email" : "test@example.com", "send_activation_email" : true, "phone":"+380931234567"}' https://api.kwiga.com/contacts
Пример ответа:
{
"data": [
{
"id": 4,
"created_at": "2022-02-04T12:17:32.000000Z",
"email": "test@example.com",
"first_name": "James",
"last_name": "Bond",
"phone": "+380931234567",
"tags": [
{
"id": 2,
"name": "tag1",
"created_at": "2022-02-14T08:58:38.000000Z"
}
]
}
]
}
HTTP Request
POST https://api.kwiga.com/contacts
Request (application/x-www-form-urlencoded)
Parameter | Description |
---|---|
email (string) (required) |
Email - должен быть уникальным в рамках кабинета |
phone (string) |
Номер телефона - формат: +{код страны}{телефон} Пример: +380930123456 |
first_name (string) |
Имя |
last_name (string) |
Фамилия |
tags (string[]) |
Теги |
send_activation_email (boolean) |
Отправить приветственное письмо |
locale (string) |
Язык контакта в формате iso_2 Допустимые варианты: ru (по умолчанию), uk , en |
Добавить покупку
Этот метод создаёт или находит контакт и добавляет ему покупку предложения
Пример запроса:
$headers = [
'Accept: application/json',
'Content-Type: application/x-www-form-urlencoded',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$data = [
'first_name' => 'James',
'last_name' => 'Bond',
'email' => 'test@example.com',
'phone' => '+380931234567',
'send_activation_email' => true,
'locale' => 'uk',
'offer' => 'er1DXGGlkwFo',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/contacts/purchases');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response);
curl -X POST -H 'Accept: application/json' -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -H 'Content-Type: application/json' -d '{"first_name" : "James", "last_name" : "Bond", "email" : "test@example.com", "send_activation_email" : true, "phone":"+380931234567", "locale": "uk", "offer":"er1DXGGlkwFo"}' https://api.kwiga.com/contacts/purchases
Пример ответа:
{
"data": [
{
"id": 4,
"created_at": "2022-02-04T12:17:32.000000Z",
"email": "test@example.com",
"first_name": "James",
"last_name": "Bond",
"phone": "+380931234567",
}
]
}
HTTP Request
POST https://api.kwiga.com/contacts/purchases
Request (application/x-www-form-urlencoded)
Parameter | Description |
---|---|
email (string) (required) |
Email - должен быть уникальным в рамках кабинета |
phone (string) |
Номер телефона - формат: +{код страны}{телефон} Пример: +380930123456 |
first_name (string) |
Имя |
last_name (string) |
Фамилия |
tags (string[]) |
Теги |
send_activation_email (boolean) |
Отправить приветственное письмо |
locale (string) |
Язык контакта в формате iso_2 Допустимые варианты: ru (по умолчанию), uk , en |
offer (string) |
Идентификатор предложения (можно получить в конце ссылки предложения) Пример: er1DXGGlkwFo |
Маркетинг. Рассылка
Список групп контактов
Пример запроса:
<?php
// Запрос без параметров
$ch = curl_init();
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/mailing/contact-lists');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
<?php
// Запрос с пагинацией
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/mailing/contact-lists?page=1&limit=50');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/mailing/contact-lists
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/mailing/contact-lists?page=1&limit=50
Пример ответа:
{
"data": [
{
"id": 2,
"title": "Пример 2",
"description": "Описание",
"is_default": false,
"created_at": "2022-04-28T13:22:44.000000Z",
"updated_at": "2022-04-28T13:22:44.000000Z"
},
{
"id": 1,
"title": "Мой первый список",
"description": "Данный список создаётся автоматически с вашим контактом внутри. Вы можете его отредактировать под свои потребности.",
"is_default": true,
"created_at": "2022-04-28T12:47:08.000000Z",
"updated_at": "2022-04-28T12:47:08.000000Z"
}
],
"links": {
"first": "https://api.kwiga.com/mailing/contact-lists?page=1",
"last": "https://api.kwiga.com/mailing/contact-lists?page=2",
"prev": null,
"next": "https://api.kwiga.com/mailing/contact-lists?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 2,
"links": [
{
"url": null,
"label": "« Предыдущая",
"active": false
},
{
"url": "https://api.kwiga.com/mailing/contact-lists?page=1",
"label": "1",
"active": true
},
{
"url": "https://api.kwiga.com/mailing/contact-lists?page=2",
"label": "2",
"active": false
},
{
"url": "https://api.kwiga.com/mailing/contact-lists?page=2",
"label": "Следующая »",
"active": false
}
],
"path": "https://api.kwiga.com/mailing/contact-lists",
"per_page": 2,
"to": 2,
"total": 3
}
}
HTTP Request
GET https://api.kwiga.com/mailing/contact-lists
URL Parameters
Parameter | Description |
---|---|
page (integer) |
Номер страницы |
limit (integer) |
Кол-во элементов выборки |
Получение группы контактов
Пример запроса:
<?php
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$id = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/mailing/contact-lists/' . $id);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/mailing/contact-lists/1
Пример ответа:
{
"data": {
"id": 1,
"title": "Мой первый список",
"description": "Данный список создаётся автоматически с вашим контактом внутри. Вы можете его отредактировать под свои потребности.",
"is_default": true,
"created_at": "2022-04-28T12:47:08.000000Z",
"updated_at": "2022-04-28T12:47:08.000000Z",
"contacts": [
{
"id": 1,
"first_name": "Alex",
"middle_name": null,
"last_name": "Иванович Burt",
"name": "Иванович Burt Alex",
"sex": null,
"age": null,
"email": "admin@grandstep.com.ua",
"phone_country": "UA",
"phone_number": "983721222",
"city": null,
"phone": "+380983721222",
"created_at": "2022-04-28T12:47:07.000000Z",
"updated_at": "2022-04-28T12:47:08.000000Z"
}
],
"statistic": {
"contact_list_id": 1,
"count_contacts": 1
}
}
}
HTTP Request
GET https://api.kwiga.com/mailing/contact-lists/{id}
Создание группы контактов
Пример запроса:
$headers = [
'Accept: application/json',
'Content-Type: application/x-www-form-urlencoded',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$data = [
'title' => 'Название группы',
'description' => 'описание'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/mailing/contact-lists/');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response);
curl -X POST -H 'Accept: application/json' -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -H 'Content-Type: application/json' -d '{"title" : "Название группы", "description" : "описание"}' https://api.kwiga.com/mailing/contact-lists
Пример ответа:
{
"data": {
"id": 3,
"title": "fsdaf asfsf dsafsda fsda",
"description": "1dsad sadsa ds dsa",
"is_default": false,
"created_at": "2022-05-04T09:57:37.000000Z",
"updated_at": "2022-05-04T09:57:37.000000Z"
}
}
HTTP Request
POST https://api.kwiga.com/mailing/contact-lists
Request (application/x-www-form-urlencoded)
Parameter | Description |
---|---|
title (string) (required) |
Название |
description (string) |
Описание |
Добавление контактов в группу
Пример запроса:
$headers = [
'Accept: application/json',
'Content-Type: application/x-www-form-urlencoded',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$data = [
'contacts' => [
1,
2
],
'contact_lists' => [
1
]
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/mailing/contact-lists/bulk-contacts/');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response);
curl -X POST -H 'Accept: application/json' -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -H 'Content-Type: application/json' -d '{"contacts" : [1, 2], "contact_lists" : [2]}' https://api.kwiga.com/mailing/contact-lists/bulk-contacts
Пример ответа:
{
"success": true
}
HTTP Request
POST https://api.kwiga.com/mailing/contact-lists/bulk-contacts
URL Parameters
Parameter | Description |
---|---|
contacts (array) (required) |
Контакты (ID) |
contact_lists (array) (required) |
Группы контактов (ID) |
Продажи. Купоны
Список купонов
Пример запроса:
<?php
// Запрос без параметров
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/coupons');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
<?php
// Запрос с фильтрацией
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/coupons?filters[date_from]=2022-04-15&filters[date_to]=2022-04-27');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/coupons
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/coupons?filters[date_from]=2022-04-15&filters[date_to]=2022-04-27
Пример ответа:
{
"data": [
{
"id": 3,
"code": "KwigaSMVT-MD",
"reward": 30,
"is_fixed": true,
"is_disposable": false,
"used_amount": 0,
"total_uses": 10,
"total_uses_per_user": 1,
"user": {
"id": 3,
"avatar_url": "https://someurl.com",
"hash": "EL9p2ycy4Ypga715",
"name": "Test User",
"email": "test@example.com",
"tag_name": "TestUser"
},
"created_at": "2022-04-28T09:46:11.000000Z",
"updated_at": "2022-04-28T09:46:11.000000Z",
"deleted_at": null
}
]
}
GET https://api.kwiga.com/coupons
URL Parameters
Parameter | Description |
---|---|
filters[date_from] (2022-04-15) |
Фильтр по дате создания. Параметр 'от' |
filters[date_to] (2022-04-27) |
Фильтр по дате создания. Параметр 'до' |
Получение купона
Пример запроса:
<?php
$headers = [
'Accept: application/json',
'Token: <Token>',
'Cabinet-Hash: <Cabinet-Hash>',
];
$id = 1;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.kwiga.com/coupons/' . $id);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
?>
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H 'Token: <Token>' -H 'Cabinet-Hash: <Cabinet-Hash>' -X GET https://api.kwiga.com/coupons/1
Пример ответа:
{
"data": {
"id": 1,
"code": "KwigaSMVT-MD",
"reward": 30,
"is_fixed": true,
"is_disposable": false,
"used_amount": 0,
"total_uses": 10,
"total_uses_per_user": 1,
"created_at": "2022-04-28T09:46:11.000000Z",
"updated_at": "2022-04-28T09:46:11.000000Z",
"deleted_at": null
}
}
HTTP Request
GET https://api.kwiga.com/coupons/{id}