Base URL
https://api.kodlog.ru/v1
Авторизация
Bearer Token / API Key
Аутентификация
POST
/auth/login
Получение JWT-токена для работы с API. Токен действует 24 часа.
Request
{
"email": "user@example.com",
"password": "your_password"
}
Response 200
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"expires_at": "2026-01-31T23:59:59Z",
"user": {
"id": 1,
"email": "user@example.com",
"role": "admin"
}
}
}
POST
/auth/api-key
Аутентификация через API-ключ (для серверных интеграций). Передайте ключ в заголовке X-API-Key.
Headers
// Для всех последующих запросов:
Authorization: Bearer {token}
// или
X-API-Key: {api_key}
Получатели
GET
/recipients
Список получателей с пагинацией и фильтрацией
Query Parameters
| Параметр | Тип | | Описание |
|---|
page | integer | опц. | Номер страницы (по умолч. 1) |
limit | integer | опц. | Записей на странице (по умолч. 20, макс. 100) |
status | string | опц. | pending | in_progress | confirmed | cancelled |
search | string | опц. | Поиск по ФИО или СНИЛС |
region_id | integer | опц. | Фильтр по региону |
Response 200
{
"success": true,
"data": {
"items": [{
"id": 1,
"full_name": "Иванов Иван Иванович",
"snils": "123-456-789 00",
"phone": "+7 (999) 123-45-67",
"address": "г. Москва, ул. Ленина, д. 1",
"status": "pending",
"codes_count": 0,
"created_at": "2026-01-20T10:00:00Z"
}],
"pagination": { "page": 1, "total_pages": 10, "total": 200 }
}
}
POST
/recipients
Создание нового получателя
Request Body
| Поле | Тип | | Описание |
|---|
full_name | string | обяз. | ФИО получателя |
snils | string | обяз. | СНИЛС (формат: XXX-XXX-XXX XX) |
phone | string | опц. | Телефон |
address | string | обяз. | Адрес доставки |
region_id | integer | обяз. | ID региона |
Request
{
"full_name": "Петров Пётр Петрович",
"snils": "987-654-321 00",
"phone": "+7 (999) 987-65-43",
"address": "г. Москва, ул. Пушкина, д. 10",
"region_id": 77
}
PUT
/recipients/{id}
Обновление данных получателя. Передайте только изменяемые поля.
DELETE
/recipients/{id}
Удаление получателя. Невозможно, если есть привязанные коды маркировки.
Коды маркировки
GET
/codes
Список отсканированных кодов маркировки с фильтрацией
Query Parameters
| Параметр | Тип | | Описание |
|---|
recipient_id | integer | опц. | Фильтр по получателю |
verified | boolean | опц. | Только верифицированные / невериф. |
date_from | string | опц. | Дата начала (ISO 8601) |
date_to | string | опц. | Дата окончания (ISO 8601) |
Response 200
{
"success": true,
"data": {
"items": [{
"id": 1,
"recipient_id": 1,
"gtin": "04630037580018",
"serial": "ABC1234567",
"verified": true,
"verification_status": "valid",
"photo_url": "https://storage.kodlog.ru/photos/...",
"latitude": 55.7558,
"longitude": 37.6173,
"courier_id": 5,
"scanned_at": "2026-01-20T14:30:00Z"
}]
}
}
POST
/codes
Добавление нового кода маркировки (используется мобильным приложением)
Request Body
| Поле | Тип | | Описание |
|---|
recipient_id | integer | обяз. | ID получателя |
code | string | обяз. | Полный DataMatrix-код |
photo | string | опц. | Base64-фото подтверждения |
latitude | float | опц. | Широта |
longitude | float | опц. | Долгота |
Request
{
"recipient_id": 1,
"code": "010463003758001821ABC1234567...",
"photo": "data:image/jpeg;base64,/9j/4AAQ...",
"latitude": 55.7558,
"longitude": 37.6173
}
Синхронизация
POST
/sync
Пакетная синхронизация данных с мобильного устройства. Принимает массив операций (создание/обновление кодов и получателей).
Request
{
"device_id": "uuid-device-123",
"last_sync": "2026-01-20T10:00:00Z",
"operations": [
{ "type": "code_create", "data": { ... } },
{ "type": "recipient_update", "data": { ... } }
]
}
Response 200
{
"success": true,
"data": {
"synced": 2,
"conflicts": 0,
"server_updates": [ /* новые данные с сервера */ ]
}
}
Верификация (Честный Знак)
POST
/verify
Верификация кода маркировки через API CRPT (Честный Знак). Поддерживается одиночная и пакетная проверка.
Request
{
"codes": [
{ "gtin": "04630037580018", "serial": "ABC1234567" }
]
}
Response 200
{
"success": true,
"data": [{
"gtin": "04630037580018",
"serial": "ABC1234567",
"status": "valid",
"product_name": "Лекарственный препарат",
"owner": "ООО Фармацевтика"
}]
}
Ограничения и коды ответов
Rate Limits
| Старт | 100 запросов/мин |
| Бизнес | 500 запросов/мин |
| Enterprise | Без ограничений |
// Заголовки ответа:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706745600
HTTP Status Codes
200 | Успешный запрос |
201 | Ресурс создан |
400 | Неверные параметры |
401 | Не авторизован |
403 | Доступ запрещён |
404 | Не найдено |
429 | Превышен лимит запросов |
500 | Ошибка сервера |
Формат ошибки
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Поле snils обязательно для заполнения",
"details": [{ "field": "snils", "rule": "required" }]
}
}