API QR-визитки для партнёров

Версия 1. Один запрос создаёт визитку клиента и возвращает QR-код в SVG. Машиночитаемое описание — OpenAPI 3.1 (YAML).

Коротко

  • Адрес API — https://qr.deltalab.ru/api/v1, только HTTPS, данные — JSON в UTF-8.
  • Ключ — в заголовке Authorization: Bearer qrk_live_…. Ключи создаются в кабинете партнёра после короткой анкеты.
  • Передаёте номер телефона клиента, имя и контакты — получаете адрес визитки и QR-код в SVG. Клиент потом сам входит на qr.deltalab.ru по своему номеру и меняет контакты; QR-код не меняется.
  • Вызывайте API только со своего сервера: ключ нельзя показывать в браузере или в приложении у клиента. Запросы со страниц чужих сайтов (CORS) мы не принимаем.

Ключ и авторизация

Ключ — qrk_live_ или qrk_test_ и 40 латинских букв и цифр. Мы показываем его один раз при создании и храним только отпечаток: потеряли — отзовите и создайте новый. Действующих ключей у партнёра — до 5.

Authorization: Bearer qrk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCd

Нет ключа или он неверный — 401 invalid_key, ключ отозван — 401 revoked_key, партнёр заблокирован — 403 partner_blocked, анкета ещё на проверке — 403 partner_pending.

Создать или обновить визитку — POST /api/v1/cards

curl -X POST https://qr.deltalab.ru/api/v1/cards \
  -H "Authorization: Bearer $QR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79991234567",
    "name": "Иван Петров",
    "subtitle": "Менеджер по продажам, ООО «Ромашка»",
    "links": [
      {"type": "phone", "value": "+7 999 123-45-67", "label": "Рабочий"},
      {"type": "telegram", "value": "@ivan_petrov"},
      {"type": "whatsapp", "value": "+79991234567"},
      {"type": "max", "value": "https://max.ru/u/f9LHodD0cOJt34p_UbhR97c03cMEAAwBUXCeUwGhqCU6Y4eHmDs5q2j5bc0"},
      {"type": "email", "value": "ivan@romashka.ru"},
      {"type": "link", "value": "romashka.ru/katalog", "label": "Каталог"}
    ],
    "external_id": "order-2026-1234"
  }'
ПолеТипЧто это
phoneстрока, обязательноНомер телефона клиента — владельца визитки, российский: +79991234567, 8 (999) 123-45-67 и т. п. По нему клиент входит в кабинет и управляет визиткой. Это не обязательно номер на визитке.
nameстрока, обязательноИмя или название — крупно вверху визитки, до 80 символов.
subtitleстрокаПодпись под именем: должность, компания — до 120 символов.
photoстрокаФото или логотип вместо кружка с инициалами — картинка в base64, см. Фото или логотип. При обновлении: поля нет — фото прежнее, null — убрать.
photo_shapeстрокаcircle — круг, для портрета (по умолчанию); square — квадрат с чуть скруглёнными углами, для логотипа.
linksмассив, обязательноКнопки связи в порядке показа, от 1 до 20: {"type", "value", "label"}. Один тип можно повторять — два телефона, два Telegram.
links[].typeстрокаtelegram, max, whatsapp, phone, email или link — форматы ниже.
links[].valueстрокаНик, номер, ссылка или адрес почты — в любом привычном виде, мы приведём к одному.
links[].labelстрокаПодпись кнопки: «Рабочий», «Для заказов» — до 30 символов, необязательно. У ссылки (link) подпись становится надписью на кнопке: «Наш сайт», «Каталог»; без подписи — «Сайт».
external_idстрокаНомер заказа или клиента в вашей системе: до 64 символов, латиница, цифры и . _ : -. Повтор запроса с тем же external_id обновляет ту же визитку, а не создаёт новую.
margin, color, background, formatПараметры QR-кода — в теле или в строке запроса, см. SVG и цвет.

Что происходит

  1. Номер клиента приводим к виду +7XXXXXXXXXX. Есть такой пользователь — визитка добавится к нему; нет — заводим кабинет на этот номер.
  2. Передан external_id и визитка с ним уже есть у вас — обновляем её (ответ 200), ключ и QR-код прежние. Иначе создаём новую (ответ 201).
  3. Клиент уже сам правил эту визитку — API её не меняет: 409 edited_by_client с адресом визитки. Клиент главнее.
  4. У клиента не больше 10 визиток: одиннадцатая — 422 client_card_limit.
  5. Визитка создана — клиенту уходит СМС «Для вас создана QR-визитка. Изменить контакты: qr.deltalab.ru — вход по номеру телефона». Не чаще раза в сутки на номер; при обновлении визитки и с тестовым ключом СМС нет.

Правила те же, что в редакторе визитки на сайте, и тексты ошибок те же.

typeЧто принимаемКнопка ведёт
telegramНик: @ivan_petrov, ivan_petrov, t.me/ivan_petrov (5–32 символа, латиница, цифры и «_», первый — буква). Или номер: +7 999 123-45-67. Ссылки-приглашения t.me/+AbCd… не принимаем.https://t.me/ivan_petrov; по номеру — https://t.me/+79991234567 (откроется, только если в Telegram разрешён поиск по номеру)
maxТолько ссылка: профиль https://max.ru/u/<токен> или канал https://max.ru/<имя>. Текст приглашения из приложения со ссылкой внутри тоже подойдёт — оставим ссылку. Номер телефона Max не открывает — такой ввод вернёт ошибку.Эту ссылку
whatsappНомер в любом виде, ссылка wa.me/79991234567 или api.whatsapp.com/send?phone=…https://wa.me/79991234567
phone+7 999 123-45-67, 8 (999) 123-45-67, 9991234567; другие страны — с кодом: +375 29 123-45-67tel:+79991234567
emailАдрес почты до 254 символов, домены на кириллице — тожеmailto:ivan@romashka.ru
linkСайт или промо-страница: romashka.ru, https://romashka.ru/promo?id=15, домены на кириллице — тоже. Только http и https, без схемы допишем https://, до 2048 символовЭту ссылку с меткой utm_source=qr&utm_campaign=<ключ визитки> — в аналитике сайта видно, что пришли с визитки. Свои utm_source и utm_campaign в ссылке остаются. В API и в «Сохранить в контакты» ссылка без метки

Фото или логотип

Поле photo — картинка JPEG, PNG или WebP в base64, до 5 МБ и 40 мегапикселей. Можно с префиксом data:image/jpeg;base64,. На визитке фото стоит вместо кружка с инициалами, попадает в «Сохранить в контакты» и в превью ссылки в мессенджерах.

  • photo_shape: "circle" — фото обрезается до квадрата: широкое — по центру, высокое — ближе к верху, где обычно лицо. Всё, что вне круга, не видно.
  • photo_shape: "square" — логотип целиком, свободное место — белое. Прозрачный фон тоже станет белым.
  • Нужен точный кадр — пришлите уже квадратную картинку: её не обрежем. Храним квадрат 512 × 512 без метаданных (EXIF с геометкой не сохраняется).
  • Не картинка или файл больше 5 МБ — 422 с текстом в errors.photo. Тестовый ключ проверяет фото так же, но не сохраняет.
{
  "phone": "+79991234567",
  "name": "ООО «Ромашка»",
  "links": [{"type": "link", "value": "romashka.ru"}],
  "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
  "photo_shape": "square"
}

Ответ

201 — визитка создана, 200 — обновлена по external_id. Тело — JSON:

{
  "key": "k7gx2pqa",
  "url": "https://qr.deltalab.ru/k7gx2pqa",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 37 37\" width=\"370\" height=\"370\" shape-rendering=\"crispEdges\"><path d=\"M4 4h7v1h-7z…\" fill=\"#000000\"/></svg>",
  "qr": {"version": 3, "modules": 29, "ecc": "M", "margin": 4},
  "client": {"phone": "+79991234567", "new": true},
  "photo": "https://qr.deltalab.ru/storage/photos/3f9c…e1.webp",
  "manage": "https://qr.deltalab.ru/login",
  "mode": "live"
}
key, urlПостоянный ключ визитки и её адрес — он и зашит в QR-код. Сохраните их у себя рядом с заказом.
svgQR-код строкой SVG — см. ниже.
qrВерсия кода, число модулей по стороне (без поля), уровень коррекции (M — восстанавливает до 15 % повреждений) и поле вокруг в модулях.
client.newtrue — номер у нас впервые, кабинет создан сейчас.
photoАдрес фото шапки (WebP 512 × 512) или null.
manageГде клиент входит по номеру телефона, чтобы менять визитку. Расскажите ему об этом.

Нужен сразу файл, а не JSON, — добавьте ?format=svg или заголовок Accept: image/svg+xml: ответ — сам SVG (Content-Type: image/svg+xml), адрес и ключ визитки — в заголовках X-Card-Url и X-Card-Key.

SVG и цвет

Код — один элемент <path> из тёмных модулей с атрибутом fill; viewBox — в модулях, shape-rendering="crispEdges". Чтобы перекрасить, достаточно поменять один fill — или сразу попросить нужный цвет:

ПараметрПо умолчаниюЧто делает
margin4Светлое поле вокруг кода в модулях, 0–8. Стандарт — 4; если поле даёт сам макет, ставьте 0.
color#000000Цвет модулей, HEX: #1d4f91 или #000 (в строке запроса — %23 вместо # или без решётки).
backgroundtransparentФон под кодом: HEX или transparent — без фона, код ляжет на ваш макет.
formatjsonsvg — ответ самим файлом SVG.

Печать. Код — тёмный на светлом: светлые модули на тёмном фоне многие камеры не читают. На визитке — не меньше 2 × 2 см вместе с полем; перед тиражом проверьте пробный оттиск камерой телефона. Код совпадает модуль в модуль с тем, что клиент скачает в своём кабинете.

Получить визитку — GET /api/v1/cards/{key}

Данные визитки, которую создали вы: имя, подпись, фото (photo — адрес или null, photo_shape), кнопки, external_id, active (открывается ли страница), client_edited_at (когда клиент правил сам), даты. Чужие визитки — 404. QR-код этой визитки файлом — GET /api/v1/cards/{key}.svg с теми же параметрами margin, color, background в строке запроса.

curl https://qr.deltalab.ru/api/v1/cards/k7gx2pqa.svg?color=%231d4f91&margin=2 \
  -H "Authorization: Bearer $QR_API_KEY" -o qr-k7gx2pqa.svg

Проверка ключа — GET /api/v1/ping

{"ok": true, "partner": "ООО «Ромашка»", "mode": "live"}

Тестовый режим

Ключ qrk_test_… проверяет запрос целиком — те же поля, форматы и ошибки — и отвечает так же, но ничего не создаёт: key всегда test, QR-код ведёт на qr.deltalab.ru/test — страницу «Это тестовый QR-код партнёрского API DELTALAB». Ответ всегда 201, client.new всегда true: тестовый ключ не узнаёт, есть ли такой клиент. GET /api/v1/cards/test и /test.svg отвечают образцом.

Лимиты

  • 60 запросов в минуту на ключ.
  • 500 новых визиток в сутки на партнёра (обновления не считаются; сутки — по Москве). Нужно больше — напишите на info@deltalab.ru.
  • До 10 визиток на одного клиента и до 20 кнопок в визитке.
  • Тело запроса — до 7 МБ (вместе с фото в base64; фото — до 5 МБ).

Превысили — 429 rate_limited с полем retry_after (секунды) и заголовком Retry-After.

Ошибки

Ошибка — всегда JSON с кодом и текстом по-русски, который можно показать менеджеру:

{
  "error": "validation",
  "message": "Проверьте поля запроса.",
  "errors": {"links.2.value": ["Номер не распознан. Пример: +7 999 123-45-67 или с кодом страны: +375 29 123-45-67."]}
}
HTTPerrorКогда
400invalid_jsonТело — не JSON-объект.
401invalid_keyНет заголовка, ключ неверный или неизвестный.
401revoked_keyКлюч отозван в кабинете.
403partner_blockedПартнёр заблокирован.
403partner_pendingАнкета партнёра на проверке.
404not_foundНет такой визитки среди ваших или такого адреса API.
409edited_by_clientКлиент уже правил визитку сам — API её не меняет; в ответе key и url.
413payload_too_largeТело больше 7 МБ.
422validationОшибки в полях; errors — по полям: phone, name, links.2.value, external_id…
422client_card_limitУ клиента уже 10 визиток.
429rate_limitedБольше 60 запросов в минуту или исчерпана суточная квота.
500server_errorСбой у нас — повторите позже.

Пример на PHP

// Визитка клиента из заказа: ответ — адрес и QR-код SVG для макета.
$payload = [
    'phone' => '+79991234567',
    'name' => 'Иван Петров',
    'subtitle' => 'Менеджер по продажам, ООО «Ромашка»',
    'links' => [
        ['type' => 'phone', 'value' => '+7 999 123-45-67', 'label' => 'Рабочий'],
        ['type' => 'telegram', 'value' => '@ivan_petrov'],
    ],
    'external_id' => 'order-' . $orderId,
    'color' => '#1d4f91',
];

$ch = curl_init('https://qr.deltalab.ru/api/v1/cards');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('QR_API_KEY'),
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status === 200 || $status === 201) {
    file_put_contents("qr-{$body['key']}.svg", $body['svg']); // в макет
    saveCardUrl($orderId, $body['url']);                     // адрес — рядом с заказом
} elseif ($status === 409) {
    // Клиент уже сам правит визитку: QR-код тот же, менять нечего.
} else {
    throw new RuntimeException($body['message'] ?? "QR API: HTTP {$status}");
}

Условия

Пользуясь API, вы принимаете условия API для партнёров: передаёте данные клиента с его согласия и сообщаете ему, что визитка создана на qr.deltalab.ru и управляется по номеру телефона. Вопросы и предложения — info@deltalab.ru.

Проекты DELTALAB