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 и цвет. |
Что происходит
- Номер клиента приводим к виду
+7XXXXXXXXXX. Есть такой пользователь — визитка добавится к нему; нет — заводим кабинет на этот номер. - Передан
external_idи визитка с ним уже есть у вас — обновляем её (ответ 200), ключ и QR-код прежние. Иначе создаём новую (ответ 201). - Клиент уже сам правил эту визитку — API её не меняет: 409
edited_by_clientс адресом визитки. Клиент главнее. - У клиента не больше 10 визиток: одиннадцатая — 422
client_card_limit. - Визитка создана — клиенту уходит СМС «Для вас создана 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-67 | tel:+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-код. Сохраните их у себя рядом с заказом. |
svg | QR-код строкой SVG — см. ниже. |
qr | Версия кода, число модулей по стороне (без поля), уровень коррекции (M — восстанавливает до 15 % повреждений) и поле вокруг в модулях. |
client.new | true — номер у нас впервые, кабинет создан сейчас. |
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 — или сразу попросить нужный цвет:
| Параметр | По умолчанию | Что делает |
|---|---|---|
margin | 4 | Светлое поле вокруг кода в модулях, 0–8. Стандарт — 4; если поле даёт сам макет, ставьте 0. |
color | #000000 | Цвет модулей, HEX: #1d4f91 или #000 (в строке запроса — %23 вместо # или без решётки). |
background | transparent | Фон под кодом: HEX или transparent — без фона, код ляжет на ваш макет. |
format | json | svg — ответ самим файлом 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."]}
}
| HTTP | error | Когда |
|---|---|---|
| 400 | invalid_json | Тело — не JSON-объект. |
| 401 | invalid_key | Нет заголовка, ключ неверный или неизвестный. |
| 401 | revoked_key | Ключ отозван в кабинете. |
| 403 | partner_blocked | Партнёр заблокирован. |
| 403 | partner_pending | Анкета партнёра на проверке. |
| 404 | not_found | Нет такой визитки среди ваших или такого адреса API. |
| 409 | edited_by_client | Клиент уже правил визитку сам — API её не меняет; в ответе key и url. |
| 413 | payload_too_large | Тело больше 7 МБ. |
| 422 | validation | Ошибки в полях; errors — по полям: phone, name, links.2.value, external_id… |
| 422 | client_card_limit | У клиента уже 10 визиток. |
| 429 | rate_limited | Больше 60 запросов в минуту или исчерпана суточная квота. |
| 500 | server_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.