API для разработчиков

Запросы

Адрес API — https://my.primeplanner.app/api/v1. Ключ передаётся в заголовке Authorization: Bearer pp_… и действует с правами роли, выбранной при его создании.

curl https://my.primeplanner.app/api/v1/activities \
  -H "Authorization: Bearer pp_…"

• Списки отдаются страницами: параметр limit — до 200 записей (по умолчанию 50), параметр cursor — значение next_cursor предыдущей страницы. Если next_cursor равен null, страница последняя.
• Время передаётся в формате ISO 8601 в UTC, суммы — целым числом копеек.
• Запросы, которые меняют данные, принимают заголовок Idempotency-Key со случайным UUID: повтор с тем же ключом и тем же телом в течение 48 часов возвращает сохранённый ответ и не повторяет изменение.
• Один ключ выполняет до 600 запросов в минуту. Сверх лимита API отвечает 429 с заголовком Retry-After.
• Ошибки приходят с кодом HTTP и телом { "statusCode": 404, "data": { "message": "…", "code": "not_found" } }. Код plan_required означает, что тариф организации не включает API.

Участники добавляются пачкой до 500 человек. Профиль ищется по external_id — ID человека в вашей системе, затем по телефону, адресу почты и совпадающему ФИО. Если профиль не найден, PrimePlanner создаёт его.

curl -X POST https://my.primeplanner.app/api/v1/activities/<id>/participants \
  -H "Authorization: Bearer pp_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-9d1b-4c47-9a44-2f8e3c1d5b7a" \
  -d '{"participants":[{"external_id":"crm-1042","lastname":"Иванова","firstname":"Анна","email":"anna@example.com"}]}'

Вебхуки

PrimePlanner отправляет событие POST-запросом с телом JSON { "id", "type", "created", "data" }. Заголовок X-PrimePlanner-Event содержит тип события, X-PrimePlanner-Delivery — ID доставки, X-PrimePlanner-Signature — подпись вида t=<время>,v1=<подпись>. Подпись — HMAC-SHA256 секрета адреса от строки <время>.<тело> в шестнадцатеричном виде.

Ответьте кодом 2xx в течение 10 секунд. Если адрес не ответил или вернул ошибку, PrimePlanner повторяет отправку через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч. После 10 неудачных доставок подряд адрес выключается. Одно событие может прийти дважды: сверяйте поле id.

Проверка подписи

import crypto from "node:crypto";

// header — значение X-PrimePlanner-Signature, body — тело запроса как строка, без разбора JSON
export function verify(secret, header, body) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex"), "hex");
  const given = Buffer.from(v1, "hex");
  return expected.length === given.length && crypto.timingSafeEqual(expected, given);
}

function verify(string $secret, string $header, string $body): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (!isset($parts['t'], $parts['v1']) || abs(time() - (int) $parts['t']) > 300) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $body, $secret);
    return hash_equals($expected, $parts['v1']);
}

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(",") if "=" in item)
    if "t" not in parts or "v1" not in parts or abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])