API

API нужен, чтобы передавать данные с сервера сайта и забирать отчёты в свои системы. Он работает только сервер-сервер: ключ API хранится на вашем сервере и в браузер не попадает.

Здесь — общие правила, методы и примеры. Полное описание методов, полей и схем — машинное: OpenAPI по адресу GET /api/v1/openapi.json, без авторизации. Его понимают генераторы клиентов и просмотрщики API, и оно всегда совпадает с тем, что сервис принимает на самом деле.

Ключ API#

1. Откройте настройки сайта, раздел «Ключи API», и создайте ключ.
2. Полный ключ показывается один раз — сохраните его в секретах сервера. В списке ключей потом видны только имя, префикс, дата создания и дата последнего использования.
3. Потерянный или раскрытый ключ отзовите и создайте новый.

Ключ — ak_ и 40 латинских букв и цифр. В примерах вместо него заглушка ak_XXXXXXXX…. Ключ определяет сайт: все запросы с ним относятся к этому сайту. Кнопка «Выйти на всех устройствах» в кабинете ключи API не отзывает.

Ключ API — не то же самое, что ключ сайта as_… в коде тега: ключ сайта публичный и для API не подходит.

Общие правила#

• Отозванный ключ — ответ 401. Заблокированный или удалённый сайт, заблокированный владелец — 403.
• X-Request-ID пишите в свои логи: по нему можно найти запрос при разборе.
• Коды ошибок и лимиты запросов — в разделе Ошибки и лимиты.

Идентификаторы#

На сервере visitor_id удобно брать из cookie _dara_a запроса, в котором посетитель оформил заказ или заявку, — только если значение похоже на UUID. Сохраните его вместе с заказом: отправка в аналитику обычно идёт позже, из очереди.

Чтобы связать посетителя с пользователем сайта, после входа вызовите на странице:

dara('user', { user_id: 'u-501' });

Методы#

Конверсии#

POST /conversions записывает достижение цели, которое подтвердилось на сервере: оплату, звонок из колл-центра, сделку в CRM.

export DARA_ANALYTICS_KEY='ak_XXXXXXXX…'

curl -X POST https://analytics.daratech.ru/api/v1/conversions \
  -H "Authorization: Bearer $DARA_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      {"id": "deal-7731", "goal": "crm_deal_won", "user_id": "u-501", "occurred_at": "2026-09-14T15:20:00Z", "value": 12000},
      {"id": "deal-7732", "goal": "crm_deal_won", "visitor_id": "0b7e6f8a-3c2d-4e5f-9a1b-2c3d4e5f6a7b"}
    ]
  }'

Ответ 202 Accepted:

{"accepted": 1, "duplicates": 0, "rejected": [{"index": 1, "code": "unknown_visitor"}]}

• В одном запросе — до 1000 конверсий.
• id — ваш id конверсии, до 64 символов ASCII, уникален в пределах сайта. Повторно присланная конверсия не учитывается и попадает в duplicates, поэтому пачку можно безопасно отправить ещё раз.
• goal — код цели типа «JS-цель».
• visitor_id или user_id — кто достиг цели, occurred_at — когда, value — ценность достижения: она важнее фиксированной суммы из настроек цели. Без occurred_at берётся время приёма запроса; время из будущего заменяется временем приёма.
• Конверсия записывается в последний визит посетителя до occurred_at, не старше 90 дней. Если посетитель известен только по user_id, берётся последний визит связанного с ним посетителя.
• Коды отказа: unknown_goal — у сайта нет включённой цели типа «JS-цель» с таким кодом, unknown_visitor — посетитель не найден, too_old — подходящий визит старше 90 дней.

Заказы#

POST /orders передаёт заказы и возвраты. Правила учёта — в разделе Электронная коммерция.

curl -X POST https://analytics.daratech.ru/api/v1/orders \
  -H "Authorization: Bearer $DARA_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [{
      "transaction_id": "T-20931",
      "visitor_id": "0b7e6f8a-3c2d-4e5f-9a1b-2c3d4e5f6a7b",
      "occurred_at": "2026-09-14T12:30:00Z",
      "status": "purchased",
      "currency": "RUB",
      "revenue": 5480,
      "products": [
        {"id": "SKU-1017", "name": "Платье миди", "category": "Одежда/Женская/Платья", "brand": "Пример", "variant": "синее", "price": 2490, "qty": 2},
        {"id": "SKU-2044", "name": "Ремень", "category": "Одежда/Аксессуары", "price": 500, "qty": 1}
      ]
    }]
  }'

Ответ 202 Accepted:

{"accepted": 1, "duplicates": 0, "rejected": []}

• В одном запросе — до 500 заказов.
• status — purchased (по умолчанию) или refunded. Заказ со статусом refunded — возврат: он уменьшает выручку и заказы того периода, в который пришёл, а прошлые отчёты задним числом не меняет. Правила учёта — в разделе Электронная коммерция.
• Заказ узнаётся по transaction_id: покупка из тега и из API учитывается один раз.
• Заказ приписывается визиту по тем же правилам, что конверсия.
• Коды отказа: unknown_visitor, too_old, invalid_products.

Отчёты#

POST /reports строит отчёт тем же движком, что конструктор в кабинете. Права и пределы — как у пользователя с ролью «наблюдатель».

curl -X POST https://analytics.daratech.ru/api/v1/reports \
  -H "Authorization: Bearer $DARA_ANALYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["source_type", "source_name"],
    "metrics": ["visits", "visitors", "pageviews"],
    "date_from": "2026-09-01",
    "date_to": "2026-09-14",
    "filters": [{"dimension": "device_type", "op": "eq", "values": ["phone"]}],
    "attribution": "last_significant",
    "robots": "exclude",
    "sort": [{"field": "visits", "dir": "desc"}],
    "limit": 100
  }'

Ответ:

{"data": [
   {"dimensions": ["search", "Яндекс"], "metrics": [1840, 1522, 5210]},
   {"dimensions": ["search", "Google"], "metrics": [620, 541, 1733]}
 ],
 "totals": [3920, 3311, 11042],
 "sampled": false,
 "timezone": "Europe/Moscow"}

• Измерения и метрики — те же, что в разделе Отчёты и метрики. Полный список их идентификаторов — в описании OpenAPI.
• Измерения аудитории — gender, age_group, interest, has_children, children_age, company_type, industry, company_region, purchase_category, price_segment, geo_person_country, geo_person_region, geo_person_city, visitor_param:ключ, value_source:атрибут — и метрики people, people_share, undefined_share, network_share, affinity_index считаются по правилам раздела Сеть ДАРА. Значения — коды, как в POST /visitors/attributes; у интересов, категорий и мест — id справочника, а название — в подписи строки.
• totals — итоги по метрикам в том же порядке, что metrics.
• sampled: true — отчёт посчитан по выборке, например потому что запрос не уложился в 30 секунд.
• Одновременно — до 2 запросов отчётов на ключ и до 60 в минуту. Третий одновременный запрос и запрос сверх 60 в минуту сразу получают 429 с кодом rate_limited и заголовком Retry-After.
• Неизвестное измерение или метрику, неверные даты и фильтры отчёт отклоняет ответом 422 с кодом validation_failed — подробности в details, коды — в разделе Ошибки и лимиты.

Примеры на PHP#

<?php
function dara_analytics(string $method, string $path, ?array $body = null): array
{
    $ch = curl_init('https://analytics.daratech.ru/api/v1' . $path);
    $options = [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('DARA_ANALYTICS_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 30,
    ];
    if ($body !== null) {
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    }
    curl_setopt_array($ch, $options);
    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($response === false || $status >= 400) {
        throw new RuntimeException('ДАРА АНАЛИТИКА: HTTP ' . $status . ' ' . ($response ?: curl_error($ch)));
    }
    return json_decode($response, true, 512, JSON_THROW_ON_ERROR);
}

$result = dara_analytics('POST', '/conversions', ['conversions' => [
    ['id' => 'deal-7731', 'goal' => 'crm_deal_won', 'user_id' => 'u-501', 'value' => 12000],
]]);
echo 'Принято: ', $result['accepted'], "\n";

// При оформлении заказа, в запросе посетителя: id посетителя сохраняется вместе с заказом
$cookie = $_COOKIE['_dara_a'] ?? '';
$visitorId = is_string($cookie)
    && preg_match('/\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i', $cookie)
    ? strtolower($cookie)
    : null;

// Позже, в фоновой задаче или обработчике очереди, — отправка заказа
$order = [
    'transaction_id' => 'T-20931',
    'user_id' => 'u-501',
    'currency' => 'RUB',
    'revenue' => 5480,
    'products' => [
        ['id' => 'SKU-1017', 'name' => 'Платье миди', 'price' => 2490, 'qty' => 2],
        ['id' => 'SKU-2044', 'name' => 'Ремень', 'price' => 500, 'qty' => 1],
    ],
];
if ($visitorId !== null) {
    $order['visitor_id'] = $visitorId;
}
dara_analytics('POST', '/orders', ['orders' => [$order]]);

$report = dara_analytics('POST', '/reports', [
    'dimensions' => ['source_type'],
    'metrics' => ['visits'],
    'date_from' => '2026-09-01',
    'date_to' => '2026-09-14',
]);
foreach ($report['data'] as $row) {
    echo $row['dimensions'][0], ': ', $row['metrics'][0], "\n";
}

Примеры на Python#

import os

import httpx

api = httpx.Client(
    base_url="https://analytics.daratech.ru/api/v1",
    headers={"Authorization": f"Bearer {os.environ['DARA_ANALYTICS_KEY']}"},
    timeout=30,
)

result = api.post("/conversions", json={"conversions": [
    {"id": "deal-7731", "goal": "crm_deal_won", "user_id": "u-501", "value": 12000},
]})
result.raise_for_status()
print("Принято:", result.json()["accepted"])

api.post("/orders", json={"orders": [{
    "transaction_id": "T-20931",
    "visitor_id": "0b7e6f8a-3c2d-4e5f-9a1b-2c3d4e5f6a7b",
    "currency": "RUB",
    "revenue": 5480,
    "products": [
        {"id": "SKU-1017", "name": "Платье миди", "price": 2490, "qty": 2},
        {"id": "SKU-2044", "name": "Ремень", "price": 500, "qty": 1},
    ],
}]}).raise_for_status()

report = api.post("/reports", json={
    "dimensions": ["source_type"],
    "metrics": ["visits"],
    "date_from": "2026-09-01",
    "date_to": "2026-09-14",
})
report.raise_for_status()
for row in report.json()["data"]:
    print(row["dimensions"][0], row["metrics"][0])

Как встроить#

• Очередь на сервере. Копите конверсии и заказы в очереди и отправляйте пачками. При сетевой ошибке, 429 или 5xx повторяйте ту же пачку с паузой: дубли по id конверсии и transaction_id заказа не учитываются.
• Таймауты. Не держите ответ посетителю в ожидании API: отправка в аналитику не должна задерживать оформление заказа.
• Ключ. Храните ключ в секретах сервера и не пишите в логи целиком — достаточно префикса.