Скрипты передачи данных по API позволяют создавать заказы из кастомных сервисов, сайтов и интеграций.

Подготовка к передаче данных

1. Добавьте отдельный источник, который будет указываться в скрипте и передаваться заказ именно с указанным источником. Нужно для разделения заказов и понимания, что именно этот заказ пришел из кастомного сервиса;
2. Создайте или скопируйте API ключ, необходимый для настройки скрипта;
3. Добавьте товары в каталог с артикулами, которые вы будете передавать, чтобы в заказах товар автоматически связался с товаром в каталоге, была доступна аналитика, склад и прочее.

Настройка скрипта передачи данных

Шаг 1: Прописываем передачу информации в нужные поля

Рассмотрим php скрипт передачи данных из html формы: когда продаем 1 товар, указывается имя, e-mail, телефон покупателя, информация об доставку, оплате и данные с дополнительных полей. 

Нам нужно указать какие параметры передавать — слева поле в CRM, куда мы передаем значение, а справа переменная из поля формы откуда это значение подставляем в скрипт:

$data = [
      "source_id" => 22, // в какой источник в KeyCRM добавлять заказы
      "buyer" => [
            "full_name"=> $_POST['name'], // ФИО покупателя
            "email"=> $_POST['email'], // email покупателя
            "phone"=> $_POST['phone'] // номер телефона покупателя
      ],
      "shipping" => [
          "shipping_address_city"=> $_POST['address_city'], // город покупателя
          "shipping_address_country"=> $_POST['address_country'], // страна
          "shipping_address_region"=> $_POST['address_region'], // область/штат/регион
          "shipping_address_zip"=> $_POST['address_zip'] // индекс
          "shipping_secondary_line" => $_POST['secondary_line'], // дополнительный адрес
          "shipping_receive_point" => $_POST['receive_poin'], // точка выдачи заказа
          "recipient_full_name" => $_POST['recipient_full_name'], // имя получателя (если отличается от покупателя)
          "recipient_phone" => $_POST['receive_phone'], // номер телефона получателя (если отличается от покупателя). Рекомендуем передавать в международном формате с плюсом
           "warehouse_ref" => $_POST['warehouse_ref'], // UUID состава Новой Почты (обязательно с параметром delivery_service_id – ID службы доставки ЧП в СРМ)
           "shipping_date" => $_POST['date'], // дата доставки/отправки
 ],
      "marketing" => [
           "utm_source" => $_POST['utm_source'], // источник компании
           "utm_medium" => $_POST['utm_medium'], // тип трафика
           "utm_campaign" => $_POST['utm_campaign'], // название компании
           "utm_term" => $_POST['utm_term'], // ключевое слово
           "utm_content" => $_POST['utm_content'], // идентификатор объявления
      ],
      "products"=> [
            [
                "sku" => $_POST['product_sku'], // артикул товара
                "price"=> $_POST['product_price'], // цена продажи
                "purchased_price" => $_POST['purchased_price'], // цена закупки  за единицю товара
                "quantity"=> 1, // количество проданного товара
                "name"=> $_POST['product_name'], // название товара
                "picture"=> $_POST['product_url'], // картинка товара
                "properties"=>[
                [
                    "name"=> "Color",
                    "value"=> "Space Gray"
                ]
              ]
          ]
      ],
     "payments" => [
          [
              "payment_method_id" => $_POST['payment_method_id'], // идентификатор метода оплаты,
              "payment_method" => $_POST['product_url'], // название метода оплаты,
              "amount" => $_POST['amount'], // сумма платежа,
              "description" => $_POST['description'], // комментарий к платежу,
              "payment_date" => $_POST['payment_date'], // дата и время платежа. Если не передается, будет использовано текущее время,
              "status" => $_POST['description'], // статус платежа Допустимые значения: paid , not_paid , canceled , refund
        ]
     ],
      "custom_fields" => [
               [
               "uuid" => "LD_1021", // внешний идентификатор поля,
               "value" => $_POST['value'] // значение поля. Для полей с типом select (список/мультисписок) передавать массив строк
              ],
              [
             "uuid" => "LD_1022", // внешний идентификатор поля,
             "value" => $_POST['value 1', 'value2', 'value 3'] // значение поля. Для полей с типом select (список/мультисписок) передавать массив строк
              ]
        ]
];

При передаче заказов нужно учитывать особенности:

1. Поле «source_id» (идентификатор источника) должно передаваться обязательно.
2. Обязательно должен передаваться массив «buyer» и хотя бы одно поле в нем («full_name», «email» или «phone» покупателя);
3. Данные «email» должны передавать в верном формате, поскольку есть валидация при создании заявки;
4. При передаче кастомных (дополнительных) полей - поля должны быть созданы в системе, чтобы при передаче указывать их системное название.
5. Если вам в запросе нужно передать существующий товар из каталога, то можно передавать только артикул, цену продажи и цену закупки.
   Все остальные данные будут подтянуты в заказ по артикулу из каталога, а именно название, картинки, свойства, валюта и т.д.

Шаг 2: Готовим данные для отправки

Нужно ваш ранее созданный API ключ скопировать и вставить в изменение $token.

//  "упаковываем данные"
$data_string = json_encode($data);

// Ваш уникальный API ключ KeyCRM
$token = 'Ваш API ключ';

// отправляем на сервер
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://openapi.keycrm.app/v1/order");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        "Content-type: application/json",
        "Accept: application/json",
        "Cache-Control: no-cache",
        "Pragma: no-cache",
        'Authorization:  Bearer ' . $token)
);
$result = curl_exec($ch);
curl_close($ch);

Результат работы

Заходим на сайт, заполняем тестовый заказ и смотрим, что происходит  в KeyCRM - пришел новый заказ, данные с полей без проблем подтянулись:

Теперь вы можете передавать ваши заказы из различных кастомных сервисов и работать с ними в заказах KeyCRM.