¶ Как устроено API SalesRender
API SalesRender работает полностью на GraphQL. Это язык запросов данных и язык манипулирования данными с открытым исходным кодом для построения веб ориентированных программных интерфейсов. Благодаря работе с GraphQL всегда доступна полная и точная документация прямо внутри API.
Все запросы в GraphQL делятся на 2 типа:
- Query - это запрос информации о сущностях. Аналог GET в REST. С помощью query вы сможете запросить данные о заказах, товарах, статусах, пользователях и т.д..
На скриншоте показан простой пример запроса данных о компании и ответ, возвращаемый от сервера
- Mutation - тип запросов, выполняющие какие-либо действия с сущностями. Это аналог POST, PUT и DELETE в REST. Все добавления новых сущностей или изменение данных сущности выполняются с помощью запросов Mutation. Например, добавление заказов, редактирование товара (название, фото, цену), редактирование пользователей и т.д..
На скриншоте показан пример редактирование пользователя id 5
Узнать больше о GraphQL и работе с ним вы можете с помощью официальной документации - https://graphql.org/learn/
Также на youtube есть видео, где в первые 20 минут хорошо рассказывают про GraphQL
¶ Документация API
Документация не открывается по отдельной ссылке, она находится внутри GraphQL. Удобней всего работать через GraphQL клиент, так как в нем есть возможность по специальной кнопке открыть документацию к ознакомлению, а также отправлять запросы. Можем посоветовать использовать удобное расширение Google Chrome - Altair. В нем легко просматривать документацию API и отправлять запросы прямо из браузера - https://chrome.google.com/webstore/detail/altair-graphql-client/flnheeellpciglgpaodhkhmapeljopja.
Полную документацию для каждой сущности вы можете найти в схеме API. Для этого достаточно указать URL с id компании, без использования токена. Например, для клиента Altair указывается url и нажимается кнопка Docs
¶ URL для получения документации и отправки запросов
В SalesRender есть 2 вида API: одно основное для работы с заказами или интеграциями с разными сервисами (мы называем его CRM), а другое для вебмастеров и CPA-сеток, чтобы они могли лить заказы (мы называем его CPA).
1. CRM - основной модуль для компании, который позволяет работать с сущностями внутри компании. С его помощью вы сможете запрашивать данные по заказам, пользователям, статусам, товарам и т.д., а также добавлять или изменять эти сущности. Модуль подойдет для интеграций с сайтами/лендингами или сторонним сервисом.
URL для доступа к документации: https://de.backend.salesrender.com/companies/{Company ID}/CRM
По этой же ссылке вы будете отправлять post запросы для получения данных из компании или добавление/изменений сущностей.
2. CPA - модуль для вебмастеров и CPA-сеток, который позволяет отправлять заказы, а также запрашивать информацию об отправленных заказах, балансе и выплатах. Он нужен для интеграций с сайтами/лендингами вебмастеров или CPA-сеток.
Чтобы настроить этот вид API, сначала нужно:
- добавить вебмастера в компанию и дать ему логин, пароль и ссылку для входа в компанию. Инструкция к личному кабинету вебмастера с описанием функционала и описанием параметров для вебхука находится здесь https://wiki.salesrender.com/ru/home/cpa/webmaster_account
- убедиться, что ему доступны офферы. Если у ваших офферов открытая доступность, то вебмастера будут видеть офферы сразу, без необходимости дополнительного открытия доступа.
- в личном кабинете вебмастер увидит свой токен и сможет продолжить настройку. Без токена совершить настройку невозможно.
URL для доступа к документации: https://de.backend.salesrender.com/companies/{Company ID}/CPA
И по этой же ссылке вебмастер будет отправлять запросы для создания заказов или получения данных о них.
Обратите внимание, что в каждом URL есть параметр {Company ID}, который нужно изменить на id вашей компании (или компании, с которой вы будете работать в качестве интегратора). Узнать ID компании можно внутри личного кабинета (или запросите у владельца компании)
Что такое API токен
Для доступа к API нужен токен - это пароль (код), позволяющий использовать методы API для создания интеграций со сторонними сервисами или сайтами.
Для модуля CRM токен создается внутри компании в режиме “Управление”, пункт “API токены”. Для создания нового токена нажмите на + в правом нижнем углу страницы и заполните форму:
Из интересного и важного:
- Комментарий можно указывать любую информацию, например для чего используется токен, чтобы не забывать в дальнейшем.
- Роль указывается для определения доступа по API. Это тот же функционал ролей, как и для обычных пользователей, но он также работает и для API токенов. Например, вы как директор компании не хотите, чтобы по API была возможность редактирования каких-то конкретных настроек, для этого вы создаете роль с нужными запретами и даете токену эту роль.
- Срок годности - это дата активности токена. Любые интеграции будут работать до тех пор, пока токен будет активен или его срок годности не закончится. Как только срок истечет, то все настроенные интеграции перестают работать. Если срок не указать, токен будет работать бессрочно.
- Токен генерируется автоматически в момент нажатия на кнопку “Добавить” и появляется в отдельном окне. Увидеть и скопировать токен для использования можно только при его создании, так что рекомендуем вам сразу скопировать (можно навести на токен и нажать для сохранения) и сохранить/использовать токен для работы. Если по какой-то причине при создании вы не успели скопировать токен, нужно архивировать текущий и создавать новый.
Для модуля CPA токен генерируется в личном кабинете вебмастера. Поэтому сначала вы должны создать кабинет вебмастеру (вход по ссылке https://cpa.salesrender.com/auth) и вебмастер сможет скопировать токен из пункта “Вебхук”.
SalesRender поддерживает 2 типа авторизации:
- Отправка токена в заголовке "Authorization". Для клиента Altair:
- Отправка токена в URL в параметре "token". Пример использования - https://de.backend.salesrender.com/companies/{Company_ID}/CRM?token=your_token_here
¶ Примеры кода на создание заказа (для API CRM)
- Запрос для клиента GraphQL (для API CRM):
mutation {
orderMutation {
addOrder(
input: {
projectId: 1
statusId: 1
orderData: {
humanNameFields: {
field: "name",
value: {
lastName: "Test"
}
}
phoneFields: {
field: "phone",
value: "79999999999"
}
}
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
}
}
) {
id
}
}
}
- Запроса в curl (для API CRM):
curl --location --globoff 'https://de.backend.salesrender.com/companies/{Company_ID}/CRM' \
--header 'Authorization: mytoken' \
--header 'Content-Type: application/json' \
--data '{
"query": "mutation {
orderMutation {
addOrder(
input: {
projectId: 1,
statusId: 1,
orderData: {
humanNameFields: {
field: \"name\",
value: {
lastName: \"Петр\"
}
},
phoneFields: {
field: \"phone\",
value: \"79999999999\"
}
},
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
}
}
) {
id
}
}
}"
}'
- Запрос на php через curl (для API CRM):
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://de.backend.salesrender.com/companies/{Company_ID}/CRM',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode(array(
"query" => "mutation {
orderMutation {
addOrder(input: {
projectId: 1,
statusId: 1,
orderData: {
humanNameFields: {
field: \"name\",
value: {
lastName: \"Петр\"
}
},
phoneFields: {
field: \"phone\",
value: \"79999999999\"
}
},
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
}
}) {
id
}
}
}"
)),
CURLOPT_HTTPHEADER => array(
'Authorization: mytoken',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Во всех примерах в ответе вернется id заказа, но вы можете добавить другие переменные в код, чтобы возвращались и другие данные с заказа.
¶ Примеры кода на создание заказа (для API CPA)
- Запрос для клиента GraphQL (для API CPA):
mutation {
leadMutation {
addLead(
input: {
offerId: 1,
externalTag: "test_tag",
externalId: "test_id",
data: {
phone_1: "79999999999",
humanName_1: {
firstName: "name",
lastName: "test"
}
},
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
},
source: {
uri: "https://google.com/",
utm_source: "source"
}
}
) {
id
}
}
}
- Запроса в curl (для API CPA):
curl --location --globoff 'https://de.backend.salesrender.com/companies/{Company_ID}/CPA' \
--header 'Authorization: mytoken' \
--header 'Content-Type: application/json' \
--data '{
"query": "mutation {
leadMutation {
addLead(
input: {
offerId: 1,
externalId: \"test_id\",
externalTag: \"test_tag\",
data: {
phone_1: \"79999999999\",
humanName_1: {
firstName: \"name\",
lastName: \"test\"
}
},
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
},
source: {
uri: \"https://google.com/\",
utm_source: \"source\"
}
}
) {
id
}
}
}"
}'
- Запрос на php через curl (для API CPA):
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://backend.salesrender.com/companies/{Company_ID}/CPA',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode(array(
"query" => "mutation {
leadMutation {
addLead(input: {
offerId: 1,
externalId: \"test_id\",
externalTag: \"test_tag\",
data: {
phone_1: \"79999999999\",
humanName_1: {
firstName: \"name\",
lastName: \"test\"
}
},
cart: {
items: [
{
itemId: 1,
variation: 1,
quantity: 1
}
]
},
source: {
uri: \"https://google.com/\",
utm_source: \"source\"
}
}) {
id
}
}
}"
)),
CURLOPT_HTTPHEADER => array(
'Authorization: mytoken',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
- Запрос REST API (для API CPA):
curl -X POST --location "https://de.backend.salesrender.com/companies/{Company_ID}/CPA/lead/add" \
-H "Authorization: token" \
-H "Content-Type: application/json" \
-d '{
"offerId": "1",
"externalId": "test_id",
"externalTag": "test_tag",
"data": {
"humanName_1": {
"firstName": "name",
"lastName": "test"
},
"phone_1": "79999999999"
},
"cart": {
"items": [
{
"itemId": "1",
"variation": "1",
"quantity": "1"
}
]
},
"source": {
"uri": "https://google.com/",
"utm_source": "source"
}
}'
Вы можете обратиться в нашу поддержку или написать своему менеджеру, если у вас возникнут вопросы или нужны тестовые данные для изучения и проверки API. Если вам нужна автоматическая выгрузка данных по API, вы можете настроить отправку вебхука через триггеры.