Як налаштувати скрипт передачі замовлень у keyCRM через API

Скрипти передачі даних по 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 (список/мультисписок) передавати масив рядків
       ]
    ]
];

Ви можете прибрати поля, які вам не потрібні, та додати ті, яких не вистачає, з методу API.

При передачі замовлень потрібно враховувати особливості:

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.