Реализуемый метод API

POST /api/v4/leads/complex

Официальная документация метода

Описание

Метод позволяет добавлять сделки c контактом и компанией в аккаунт пакетно. Добавляемые данные могут быть проверены в контроле дублей.

Ограничения

• Метод доступен в соответствии с правами пользователя.
• Для одной сделки можно указать не более 1 связанного контакта и 1 связанной компании.
• Для добавляемых сущностей (сделка, контакт, компания), можно передать не более 40 значений дополнительных полей.
• Добавляемые данные участвуют в контроле дублей, если он включен для интеграции, которая добавляет данные.
• Метод не производит дедубликацию переданных данных, а только ищет дубли среди уже добавленных данных.
• За один запрос можно передать не более 50 сделок.
• При создании нового контакта и компании, они будут связаны между собой.

Параметры

Возвращаемые значения

HTTP 200 Успешный ответ

Возвращаемое значение соответствует документации AmoCRM для этого метода.

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

stdClass Object
(
    [0] => stdClass Object
        (
            [id] => 21674949
            [contact_id] => 33860727
            [company_id] => 
            [request_id] => Array
                (
                    [0] => 0
                )

            [merged] => 
        )

)

HTTP 40x Неудачный ответ

Официальная документация говорит о возможном коде ответа 401 Пользователь не авторизован. Библиотека WT Amocrm возвращает объект ошибки следующей структуры:

stdClass Object
(
    [error_code] => 400
    [error_message] => createLeadsComplex function: Error while trying to create lead in Amo CRM. Amo CRM API response: <b>request_id</b>: 0
<b>code</b>: FieldMissing
<b>path</b>: _embedded.metadata.form_id
<b>detail</b>: This field is missing.
<b>title</b>: Bad Request
<b>type</b>: https://httpstatus.es/400
<b>status</b>: 400
<b>detail</b>: Request validation failed
)

Пример использования в коде

Данный пример кода взят из плагина WT AmoCRM - RadicalForm. В примере PHP-кода подготавливается массив данных о лидах согласно документации AmoCRM и передаётся методом createLeadComplex:

use Joomla\CMS\Date\Date;
use Webtolk\Amocrm\Amocrm;
	
$lead_data = [
	'created_by' => 0, //ID пользователя AmoCRM, создающий сделку. При передаче значения 0, сделка будет считаться созданной роботом. Поле не является обязательным
];

// Название сделки в Amo CRM
if (isset($input["rfSubject"]) && (!empty($input["rfSubject"])))
{
	$lead_data['name'] = $input["rfSubject"];

}
else
{
	$lead_data['name'] = $params->get('rfSubject');
}

if (isset($input['pipeline_id']) && (!empty($input['pipeline_id'])))
{
	$lead_data['pipeline_id'] = $input['pipeline_id'];
}
elseif (!empty($this->params->get('pipeline_id')))
{
	$lead_data['pipeline_id'] = $this->params->get('pipeline_id');
}

if (!empty($this->params->get('status_id')))
{
	$lead_data['status_id'] = $this->params->get('status_id');
}

$lead_data['_embedded']['metadata'] = [
	'category'     => 'forms',
	'form_id'      => (isset($input['form_id']) && !empty($input['form_id'])) ? $input['form_id']: 1,
	'form_name'    => (isset($input['rfSubject']) && !empty($input['rfSubject'])) ? $input['rfSubject']: 'Call back from site',
	'form_page'    => $input['url'],
	'form_sent_at' => (new Date('now'))->toUnix(),
];


//  URL of refferer page
if (isset($input["url"]) && (!empty($input["url"])))
{
	$lead_data['_embedded']['metadata']['referer'] = $input['url'];
}
$contact = [];


if (isset($input["name"]) && (!empty($input["name"])))
{
	$contact['first_name'] = $input['name'];
}
//  Process form data
foreach ($clear as $key => $value)
{

	if ($key == "PHONE" || $key == "phone")
	{
		$phones = [
			'field_code' => 'PHONE',
			'values'     => []
		];
		/*
		 * If any phone numbers or emails are found
		 */
		if (is_array($value))
		{

			foreach ($value as $phone)
			{
				$phones['values'][] = [
					'enum_code' => 'WORK',
					'value'     => $phone
				];

			}//end FOREACH


		}
		else
		{
			/**
			 * Single email or phone number
			 */
			$phones['values'][] = [
				'enum_code' => 'WORK',
				'value'     => $value
			];
		}
		$contact['custom_fields_values'][] = $phones;
		/*
		 * Other form data. Not email or phone
		 */
	}
	elseif ($key == "EMAIL" || $key == "email")
	{
		$emails = [
			'field_code' => 'EMAIL',
			'values'     => []
		];
		/*
		 * If any phone numbers or emails are found
		 */
		if (is_array($value))
		{

			foreach ($value as $email)
			{
				$emails['values'][] = [
					'enum_code' => 'WORK',
					'value'     => $email
				];

			}//end FOREACH


		}
		else
		{
			/**
			 * Single email or phone number
			 */
			$emails['values'][] = [
				'enum_code' => 'WORK',
				'value'     => $value
			];
		}
		$contact['custom_fields_values'][] = $emails;
		/*
		 * Other form data. Not email or phone
		 */
	}
}//end foreach Process form data

if(!empty($this->params->get('radicalform_to_amocrm_lead_custom_fields'))){
	foreach ($this->params->get('radicalform_to_amocrm_lead_custom_fields') as $key => $value){
		$radical_form_field_name = $value->radical_form_field_name;

		if(array_key_exists($radical_form_field_name,$input) && !empty($input[$radical_form_field_name])){

			$lead_custom_field_array = [
				'field_id' => (int) $value->lead_custom_field_id,
				'values'     => [
					[
						'value' => $input[$radical_form_field_name]
					]
				]
			];
			$lead_data["custom_fields_values"][] = $lead_custom_field_array;
		}
	}
}

$lead_data['_embedded']['contacts'][] = $contact;


if ($this->params->get('lead_tag_id', 0) > 0)
{
	$lead_data['_embedded']['tags'][0]['id'] = (int) $this->params->get('lead_tag_id');
}

/**
 * Add UTMs into array
 */

$lead_data = $this->checkUtms($lead_data);
$leads[]   = $lead_data;

/**
 * Create a lead
 */
$amocrm = new Amocrm();
$result = $amocrm->createLeadsComplex($leads);