Як отримувати замовлення з лендінгу/сайта в keyCRM

Скрипти передачі даних по 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" => [
          "delivery_service_id": 1, // ID служби доставки у keyCRM
          "shipping_address_city"=> $_POST['address_city'], // місто покупця
          "shipping_receive_point"=> $_POST['address_street'], // вулиця, номер будинку чи відділення Нової Пошти
          "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"=> [
            [
                "price"=> $_POST['product_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" => "OR_1021", // зовнішній ідентифікатор поля,
        "value" => $_POST['value'] // значення поля. Для полів з типом select (список/мультисписок) передавати масив рядків
       ],
        [
        "uuid" => "OR_1022", // зовнішній ідентифікатор поля,
        "value" => $_POST['value 1', 'value2', 'value 3'] // значення поля. Для полів з типом select (список/мультисписок) передавати масив рядків
       ]
    ]
];

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

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

1. Обов'язково має передаватися масив  "buyer" та хоча б одне поле в ньому ("full_name", "email" чи "phone" покупця);
2. Дані "email" мають передаватися у вірному форматі, оскільки є валідація при створенні заявки;
3. При передачі кастомних (додаткових) полів — поля мають бути створені в системі, щоб при передачі вказувати їхню системну назву.

Крок 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, то потрібно змінити скрипт та використовувати інший метод API.

Приклад форми

• Готуємо форму та до кожного поля прописуємо зміну “name”.
  name="your-name" і далі вони ж в скрипті в полях:
  "full_name" => $_POST['your-name'].

• Створюємо файл для скрипту, наприклад, send.php, та вказуємо шлях до нього у параметрі action форми;
• Прописуємо змінні, які ми задали вище, відповідно до полів в keyCRM;

<?php
if ($_SERVER["REQUEST_METHOD"] == "POST") {
    // Отримання даних з POST
    $data = [
        "source_id" => 245, // до якого джерела в keyCRM додавати замовлення
        "promocode" =>  $_POST['your-promo'], // промокод
        "buyer_comment" =>  $_POST['your-text'], // коментар покупця
        "buyer" => [
            "full_name" => $_POST['your-name'], // ПІБ покупця
            "email" => $_POST['your-email'], // email покупця
            "phone" => $_POST['your-phone'] // номер телефону покупця
        ],
        "shipping" => [
            "shipping_receive_point" => $_POST['your-address'] // адреса доставки
        ],
        "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" => [
            [
                "price" => 42, // ціна продажу
                "quantity" => 100, // кількість проданого товару
                "name" => "Яблука Преміум", // назву товару
                "unit_type" => "кг" // одиниця виміру
            ]
        ], 
        "custom_fields" => [
            [
                "uuid" => "OR_1790", // зовнішній ідентифікатор поля
                "value" => [$_POST['custom']] // значення поля з типом список
            ]
        ]
    ];

    // Упаковуємо дані
    $data_string = json_encode($data);

    // Ваш унікальний API ключ KeyCRM
    $token = 'ТУТ_ВАШ_КЛЮЧ';

    // Відправка на сервер
    $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.