Отправка целевого события/достижение цели

Цель — это действие пользователя в боте, например продажа. Graspil имеет несколько уже созданных "целей", вы можете увидеть их в своем личном кабинете в разделе конверсии. Там же вы можете создавать свои цели.

Каждая цель имеет свой триггер — некую логику при наступлении которой будет создано целевое событие (достижение цели), его вы и уведите в статистике.

"Цели" можно активировать через API. Ниже представлен метод, который описывает как передать целевое событие.

Отправка данных

За одну отправку запроса вы можете передать от 1 до 100 событий. Данные отправляются в json формате. Предпочтительней отправлять события в момент их появления.

Не забудьте добавить заголовок для авторизации запроса. Подробней в этом разделе

HTTPS Request

POST https://api.graspil.com/v1/send-target

Передаваемые параметры

Параметр	Type	Обязательный	Описание
target_id	integer	да	ID цели, вы можете найти ID в настройках
user_id	integer	да	Telegram ID пользователя, кому принадлежит событие. Перед сохранением данных будет проверенно соответствует ли id пользователю вашего бота.
date	RFC 3339 (ISO 860)	нет	Дата и время когда произошло событие, если оставить пустым будет установленно текущее время. Формат времени должен содержать миллисекунды и часовой пояс. Пример: 2024-08-03T20:00:00.123+02:00
value	float	нет	Общая цена (число с плавающей запятой).
unit	string(3)	да, если есть value	Код валюты, максимальная длинна строки 3. Аналогично валютам в TG Api.

Передавать можно как один объект:

{
    "target_id": 1,
    "user_id": 5842703839,
    "date": "2023-12-31T20:00:00+01:00",
    "value": 10,
    "unit": "usd"
}

Так и массив объектов:

[
    {
        "target_id": 1,
        "user_id": 5842703839,
        "date": "2023-12-31T20:00:00+01:00",
        "value": 10,
        "unit": "usd"
    },
    {
        "target_id": 1,
        "user_id": 5842703839,
        "date": "2023-12-31T20:00:00+01:00",
        "value": 10,
        "unit": "usd"
    }
]

Примеры кода

PHP

$url = "https://api.graspil.com/v1/send-target";
$api_key = ""; // your API key
$data = json_encode([
    "target_id": 1,
    "user_id": 5842703839,
    "date": "2023-12-31T20:00:00+01:00",
    "value": 10,
    "unit": "usd"
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Api-Key: ' . $api_key,
    'Content-Type: application/json;'
)];
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

Python

import requests
import json

url = "https://api.graspil.com/v1/send-target"
api_key = ""  # your API key

payload = json.dumps({
  "target_id": 1,
  "user_id": 5842703839,
  "date": "2023-12-31T20:00:00+01:00",
  "value": 10,
  "unit": "usd"
})

headers = {
    "Api-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Ответ

Пример успешного ответа:

{
  "ok": true
}

Ошибки

При полученнии данных API проверяет только базовые параметры, остальные проверки происходят позже при обработке данных. Все возникшие ошибки вы можете найти в разделе “ошибки бота”

В случае возникновения ошибок при валидировании данных, ответ будет содержать информацию об ошибке

{
  "ok": false,
  "error": {
      "target_id": [
          "Unknown target_id"
      ],
      "user_id": [
          "The user with this id was not found"
      ]
  }
}