Работа с короткими ссылками

Короткие ссылки

API для сокращения ссылок, которые отправляются контактам. Когда человек перейдет по ссылке в контакт добавиться примечание, о переходе на сайт. Так же, человеку прикрепится пиксель, по которому в дальнейшем может произойти автоматическое объединение чатов.

Для каждого контакта генерируется отдельная ссылка. То есть, если одну и ту же ссылку нужно отправить нескольким контактам, для каждого контакта нужно сгенерировать отдельную ссылку.

При этом, если вы хотите показать менеджеру, что ссылка была отправлена клиенту, например, создать об этом примечание, то менеджер должен видеть только исходную ссылку, не должен видеть или переходить по короткой, которая была отправлена клиенту.

Генерация ссылок

Метод позволяет генерировать короткие ссылки по одной или пакетно (не более 500 за один запрос) Обязательно с каждым запросом передавать GET параметры USER_LOGIN и USER_HASH с логином и api ключем соответственно

URL метода

POST /api/v2/url_shortener/

Параметры

Параметр	Тип	Описание
url require	string	Ссылка для сокращения
properties	array	Свойства по которым формируется ссылка
properties/type require	integer	Тип свойства, на данный момент значение может быть только 1 - по id контакту
properties/contact_id require	integer	Id контакта, которому будет отправлена ссылка.

Приведём пример запроса на сокращение ссылок.

Пример запроса

[
{
"url" : "https:\/ \/www.yandex.ru" ,
"properties" : [
{
"type" : 1 ,
"contact_id" : 123
}
]
} ,
{
"url" : "http:\/ \/www.google.ru" ,
"properties" : [
{
"type" : 1 ,
"contact_id" : 456
}
]
}
]

Параметры ответа

Параметр	Описание
_links	Массив, содержащий информацию о запросе
_links/self	Массив, содержащий информацию о текущем запросе
_links/self/href	Относительный URL текущего запроса
_embedded	Массив, содержащий информацию прилегающую к запросу
_embedded/items	Массив, содержащий информацию по каждому отдельному элементу
_embedded/items/base_url	Базовая ссылка, которая не связана с контактом, может использоваться просто для редиректа
_embedded/properties_url/url	Ссылка, связанная с контактом, при переходе по которой, добавится примечание в карточку контакта
_embedded/properties_url/contact_id	id контакта, к которому привязана ссылка
_embedded/properties_url/account_id	id аккаунта

Response Headeres содержит следующие заголовки:

Content-Type:application/hal+json

Пример ответа

{
"_links" : {
"self" : {
"href" : "/api/v2/url_shortener"
}
} ,
"_embedded" : {
"items" : [
{
"base_url" : "https://amo.sh/1" ,
"properties_url" : [
{
"account_id" : 111 ,
"contact_id" : 123 ,
"url" : "https://amo.sh/1/2"
}
]
} ,
{
"base_url" : "https://amo.sh/2" ,
"properties_url" : [
{
"account_id" : 111 ,
"contact_id" : 456 ,
"url" : "https://amo.sh/2/3"
}
]
}
]
}
}

Пример интеграции

Для сокращения ссылки необходимо описать массив, содержащий информацию о id контакта и ссылки которую наждо сократить.

$links = array (
array (
'url' => 'https://www.yandex.ru' ,
'properties' => array (
array (
'type' => 1 ,
'contact_id' => 123 ,
) ,
) ,
) ,
) ;
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test' ; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/url_shortener/?USER_LOGIN=test@test.ru&USER_HASH=111' ;
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, true ) ;
curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
curl_setopt ( $curl ,CURLOPT_CUSTOMREQUEST, 'POST' ) ;
curl_setopt ( $curl ,CURLOPT_POSTFIELDS, json_encode ( $links ) ) ;
curl_setopt ( $curl ,CURLOPT_HTTPHEADER, array ( 'Content-Type: application/json' ) ) ;
curl_setopt ( $curl ,CURLOPT_HEADER, false ) ;
curl_setopt ( $curl ,CURLOPT_COOKIEFILE, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt ( $curl ,CURLOPT_COOKIEJAR, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
$out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo ( $curl ,CURLINFO_HTTP_CODE) ;
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int) $code ;
$errors = array (
301 => 'Moved permanently' ,
400 => 'Bad request' ,
401 => 'Unauthorized' ,
403 => 'Forbidden' ,
404 => 'Not found' ,
500 => 'Internal server error' ,
502 => 'Bad gateway' ,
503 => 'Service unavailable'
) ;
try
{
if ( $code > 299 ) {
throw new Exception( isset ( $errors [ $code ] ) ? $errors [ $code ] : 'Undescribed error' , $code ) ;
}
}
catch(Exception $E )
{
die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
*/
$Response = json_decode ( $out , true ) ;
$Response = $Response [_embedded']['items'];
$output=' Ссылки : '.PHP_EOL;
foreach($Response as $v)
if(is_array($v))
$output.=$v['id'].PHP_EOL;
return $output;