Общ преглед на API

REST API на qr3.app е достъпно на адрес https://qr3.app/v1/.

Версиониране

API е версионирано чрез URL пътя (/v1/). Промени, които нарушават съвместимостта (breaking changes), винаги водят до нова основна версия.

Формат на заявката

Content-Type: application/json
Автентификация: Authorization: Bearer qr3_sk_xxx
Идемпотентност: POST заявките могат да бъдат направени идемпотентни с Idempotency-Key: <uuid>

Формат на отговора

Всички успешни отговори връщат JSON:

{
  "id": "qr_abc123",
  "type": "url",
  "url": "https://example.com",
  "short_url": "https://qr3.app/r7f3Kx",
  "created_at": "2026-03-15T10:00:00.000Z"
}

Отговорите, съдържащи списъци, винаги имат структура meta.pagination:

{
  "data": [...],
  "meta": {
    "request_id": "req_xxx",
    "pagination": {
      "has_more": true,
      "next_cursor": "qr_abc",
      "total_count": 142
    }
  }
}

Формат на грешките (RFC 7807)

Всички грешки следват стандарта RFC 7807 Problem Details:

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found",
  "instance": "/v1/codes/qr_xxx"
}

Статус	Тип грешка	Описание
400	`bad-request`	Невалиден JSON или липсващи задължителни полета
401	`authentication`	Липсващ или невалиден API ключ
403	`forbidden`	Нямате права за достъп до този ресурс
404	`not-found`	Ресурсът не е намерен
409	`conflict`	Конфликт с Idempotency-Key
422	`validation-error`	Грешни входни данни (с масив `errors`)
429	`rate-limited`	Превишено ограничение на честотата (Rate Limit)
500	`internal`	Вътрешна грешка на сървъра

Пагинация

API използва пагинация, базирана на курсор (cursor-based pagination):

# Erste Seite
GET /v1/codes?limit=20

# Nächste Seite
GET /v1/codes?limit=20&cursor=qr_lastid

Ограничения на честотата (Rate Limits)

Всеки отговор съдържа:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1742040120

Интерактивна API референция

Тествайте всички крайни точки директно в браузъра:

→ Отвори API референцията (Scalar, интерактивна, с възможност за тестване)

DPP договор (Фаза 4a)

За работния процес за батерии qr3.app допълнително документира следните маршрути:

POST /v1/dpp
GET /v1/dpp
GET /v1/dpp/:id
POST /v1/dpp/validate
GET /v1/dpp/:id/qr.svg
GET /v1/dpp/:id/qr.png
GET /v1/dpp/:id/qr.pdf
GET /v1/dpp/:id/qr.eps
GET /01/...
GET /dpp/:gtin/:serial?lot=...

Страниците на таблото (dashboard), SDK-тата и тази документация използват същия договор за данни (data contract).