# QR «Archy v1» — для магазинів і брендів

Один QR на чеку, бирці чи в коробці — і покупець отримує в Archy готову картку речі: назва, ціна, дата, гарантія, серійний номер, характеристики, а за бажанням — фото виробу, фото клейма й документи бренду (сертифікат, гарантійний талон).

Що важливо знати магазину:

- **Працює без нашого сервера.** Дані записані в самому QR. Archy нікуди не звертається, щоб їх прочитати.
- **Файли — з вашого сайту.** Фото й документи Archy завантажує лише з вашого сайту, лише після того, як покупець зберіг річ і погодився на завантаження. Кожен файл перевіряється за відбитком SHA-256.
- **Підпис необов'язковий.** Без підпису картка заповнюється так само, але з позначкою «Не перевірено». Код із підписом і однією річчю стає **паспортом бренду** (§4): Archy 1.1+ зберігає його як є, і змінити його не може ніхто, навіть власник речі. Статус підпису — за реєстром ключів (§3).
- **Будь-яка камера.** QR — це посилання `https://quietapps.app/q#…`. Камера телефона відкриє сторінку з карткою речі, брендом і статусом підпису (§5). Сам Archy читає той самий код напряму.

---

## 1. Рядок QR

```
https://quietapps.app/q#[TS1.<yyyymmdd>.<ts-sig>/]ARCHY1.<payload>[.<sig>]
```

| Частина | Що це |
|---|---|
| `https://quietapps.app/q#` | Необов'язковий префікс для камер телефона. Частина після `#` на сервер не надсилається. Без префікса (`--raw`) Archy теж прочитає код, але камера телефона покаже просто текст. |
| `ARCHY1.` | Версія формату. |
| `payload` | `base64url` без `=` від **raw deflate** (без заголовка zlib) UTF-8 JSON. |
| `sig` | Необов'язковий. `base64url` без `=` від підпису **Ed25519** над *стиснутими байтами* payload (не над JSON). |
| `TS1.…/` | Необов'язкова **позначка часу Quiet Apps** (§3.4) перед кодом: дата друку за нашим сервером і підпис. Archy 1.0 шукає `ARCHY1.` і читає такі коди як раніше. |

Підписано саме стиснуті байти, тож перевірити можна лише рядок, яким його надрукували. Archy зберігає цей рядок без змін (§4).

## 2. JSON

Ключі короткі, щоб QR був менш щільним. Порожні поля просто не пишіть.

```json
{
  "v": 1,
  "s": {"n": "Ювелірний дім «Аурум»", "id": "aurum.example"},
  "i": [{
    "n": "Каблучка «Дерево життя»",
    "c": "jewellery",
    "p": 3850000, "cur": "UAH",
    "d": "2026-11-12",
    "st": "Аурум, Київ, Хрещатик 1",
    "w": 24,
    "sn": "KT-7781",
    "sp": {"metal": "Жовте золото", "fineness": "585", "weight": "5.74", "stone": "Діамант", "carat": "0.25", "hallmark": "585 · АУ"},
    "mt": [{"m": "gold", "c": "Жовте золото", "f": "585", "w": "1.11"},
           {"m": "silver", "f": "925", "w": "4.63"}],
    "doc": ["receipt", "certificate"],
    "u": "https://aurum.example/rings/kt-7781"
  }],
  "m": {"u": "https://aurum.example/archy/KT-7781/manifest.json", "h": "<sha256 hex>"}
}
```

| Ключ | Тип | Значення |
|---|---|---|
| `v` | число | Завжди `1`. |
| `s.n` | рядок | Назва магазину чи бренду, як її побачить покупець. |
| `s.id` | рядок | Ваш домен (`aurum.example`). За ним Archy шукає ключ у реєстрі. |
| `i` | масив | Одна чи кілька речей. Якщо речей кілька (комплект), покупець вибирає, яку додати. **Паспорт бренду — лише для коду з однією річчю** (§4). |
| `i.n` | рядок | **Обов'язково.** Назва речі. |
| `i.c` | рядок | Категорія, див. §7. Якщо не вказати, покупець вибере сам. |
| `i.p` | ціле | Ціна **в копійках/центах**: 38 500 грн → `3850000`. |
| `i.cur` | рядок | Валюта ISO 4217 (`UAH`, `EUR`, `USD`…). Типово `UAH`. |
| `i.d` | рядок | Дата покупки, `YYYY-MM-DD`. **Обов'язкова для паспорта бренду**: за нею перевіряється строк дії ключа (§3). Ставте справжню дату продажу. |
| `i.st` | рядок | Магазин для картки (місто, адреса). Якщо не вказати, береться `s.n`. |
| `i.w` | ціле | Гарантія в місяцях, 1–1200. |
| `i.sn` | рядок | Серійний номер, артикул чи номер виробу. За ним Archy попереджає про дубль. |
| `i.sp` | об'єкт | Поля шаблону категорії, див. §7. Числа пишіть із крапкою (`3.4`), дати як `YYYY-MM-DD`, суми цілими гривнями без пробілів (`45000`). |
| `i.mt` | масив | Метали виробу, якщо їх кілька (§2.1). |
| `i.doc` | масив | Які документи мають бути в пакеті речі (§8). Archy покаже, яких бракує. |
| `i.u` | рядок | Сторінка товару, лише `https://`. У картці буде посилання «Сторінка товару». |
| `m.u`, `m.h` | рядки | Маніфест файлів (§6): адреса `https://` і SHA-256 (hex) його байтів. |

Обмеження (дані з QR — завжди лише дані, нічого не виконується):

- текст коду — до 8 192 символів, розпакований JSON — до 64 КБ, інакше код не читається;
- до 20 речей, до 40 полів `sp` на річ (ключ до 40 символів), до 6 металів у `mt`, рядки обрізаються до 300 символів;
- `cur` — три латинські літери (ISO 4217), інакше `UAH`; `doc` — лише відомі типи (§8), без повторів;
- невідомі ключі ігноруються; посилання не через `https://` відкидаються;
- сторінка товару відкривається лише після натискання, а в картці поруч видно її домен.

### 2.1. Кілька металів (`mt`)

Комбінований виріб (золото + срібло) описується масивом `mt`, по запису на метал:

| Ключ | Значення |
|---|---|
| `m` | Метал: `gold`, `silver`, `platinum`, `palladium`, `steel`, `titanium`, `other`. Обов'язково. |
| `c` | Як назвати метал у картці (колір, сплав): «Жовте золото», «Біле золото». Якщо не вказати, Archy назве метал за `m`. |
| `f` | Проба (`585`, `925`). |
| `w` | Вага цього металу в грамах, з крапкою (`1.11`). |

Вага — в окремих полях:

- `sp.weight` — **загальна вага виробу** в грамах (з каменями й вставками);
- `mt[].w` — вага кожного металу.

Сумісність зі старими версіями Archy (до 1.1 `mt` не знають і пропускають): **перший метал** продублюйте в `sp.metal` (назва, як у `c`) і `sp.fineness`, а в `sp.weight` пишіть загальну вагу. Тоді Archy 1.0 і PDF для страхової покажуть правильну загальну вагу. Archy 1.1+ при наявності `mt` показує метали з `mt`, а `sp.metal` і `sp.fineness` не показує окремо. Генератор заповнює ці поля сам.

Виріб з одного металу можна описати як раніше, лише `sp.metal` / `sp.fineness` / `sp.weight`, без `mt`.

## 3. Підпис і реєстр ключів

### 3.1. Ключ бренду

1. Створіть ключ:
   `python tools/archy_qr.py --new-key aurum.key`
   Скрипт збереже приватний ключ (32 байти) у `aurum.key` і надрукує публічний.
2. Надішліть **публічний** ключ і домен (`s.id`) на support@quietapps.app з адреси на цьому домені.
3. Підписуйте коди: `--key aurum.key`.

Приватний ключ тримайте в магазині й не кладіть у репозиторій чи на сайт. Якщо ключ втрачено чи скомпрометовано, напишіть нам (§3.5).

### 3.2. Реєстр

Реєстр — статичний файл `https://quietapps.app/archy/registry.json` і поруч його підпис `registry.json.sig`. Підписує реєстр ключ Quiet Apps. Його публічна частина (основна й запасна) вшита в Archy і в сторінку quietapps.app/q, тож підмінений реєстр не пройде перевірку.

- **Archy 1.1+** періодично завантажує реєстр, перевіряє підпис і зберігає копію: перевірка працює й без мережі. Новий ключ бренду діє одразу після появи в реєстрі, без оновлення застосунку. Вшитий у застосунок список лишається запасним.
- **Archy 1.0** знає лише ключі, вшиті в збірку (`archyQrIssuers`).

```json
{
  "v": 1,
  "issued": "2026-11-20",
  "brands": [{
    "id": "aurum.example",
    "name": "Ювелірний дім «Аурум»",
    "logo": {"u": "https://quietapps.app/archy/brands/aurum.example.png", "h": "<sha256 hex>"},
    "keys": [{"k": "<публічний ключ, base64url>", "validUntil": "2027-11-30", "compromisedFrom": null}],
    "pack": ["widget", "pdf"],
    "quota": {"n": 500, "from": "2026-12-01"},
    "tsFrom": "2027-01-01"
  }],
  "ts": ["<публічний ключ позначок часу, base64url>"]
}
```

`registry.json.sig` — `base64url` без `=` від підпису Ed25519 над **байтами** `registry.json` як вони є.

| Ключ | Значення |
|---|---|
| `id` | Домен бренду, той самий, що `s.id` у QR. |
| `name`, `logo` | Як показувати бренд на quietapps.app/q, у віджеті й у брендованому PDF. Логотип — PNG до 256 КБ (прозорий фон, ~600 × 150 px) на quietapps.app, з SHA-256. Застосунок завантажує логотипи всіх брендів із пакетом `pdf` наперед (запит не видає, чий паспорт у людини) і в PDF бере лише з диска. |
| `keys` | Ключі бренду. Кілька — коли ключ змінювали: старі паспорти перевіряються старим ключем. |
| `keys.validUntil` | До якої дати (включно) ключ підписує **нові** паспорти: дата `i.d` має бути не пізніше неї. Це оплачений період бренду. |
| `keys.compromisedFrom` | Дата, з якої ключ вважається скомпрометованим; `null` — ні. |
| `pack` | Платні можливості бренду: `widget` (віджет перевірки), `pdf` (логотип у PDF-паспорті). |
| `quota` | Пакет паспортів: не більше `n` нових позначок часу від дати `from` (початок оплаченого періоду). Рахує сервер позначок (§3.4); застосунок і сторінка перевірки поле не читають. Немає — без ліміту. Пакет має сенс разом із `tsFrom`: коди без позначки сервер не бачить. |
| `tsFrom` | З цієї дати покупки коди бренду мають мати позначку часу (§3.4); без неї — «Без позначки часу». Немає — позначка необов'язкова. |
| `demo` | `true` — демо-бренд Quiet Apps (`demo.quietapps.app`, назва «Archy Demo»). Паспорти перевіряються як звичайні, але Archy (картка, PDF з водяним знаком «ДЕМО»), quietapps.app/q і віджет показують їх із позначкою «Демо» й поясненням «не справжня покупка». Без `validUntil` і `quota`; пакети `widget`, `pdf`. Позначки часу демо-кодів Quiet Apps ставить на своєму ПК (`archy_registry.py demo`). Демо-коди й файли — на demo.quietapps.app. Для інших брендів поля немає. |
| `ts` | Публічні ключі позначок часу Quiet Apps (верхній рівень реєстру). |

Записи з реєстру не видаляються: щоб ключ перестав підписувати нові паспорти, досить не продовжити `validUntil`.

### 3.3. Статуси

Archy і quietapps.app/q показують однакові статуси. Перевірка йде по черзі, перший збіг — статус:

| № | Статус | Коли | Що бачить покупець |
|---|---|---|---|
| 1 | Не перевірено | Підпису немає або домену `s.id` немає в реєстрі. | «Не перевірено — звір дані з чеком». |
| 2 | Підпис не збігається | Підпис є, але не збігся з жодним ключем домену: дані змінено. | «Підпис не збігається — дані могли змінити». |
| 3 | Підпис не збігається | Позначка часу є, але не збігається з ключами позначок Quiet Apps. | «Підпис не збігається — дані могли змінити». |
| 4 | Без позначки часу | Позначки немає, а `i.d` ≥ `tsFrom` бренду (або `i.d` немає). | «Без позначки часу — дату паспорта не підтверджено». |
| 5 | Не перевірено | Немає ні позначки, ні дати `i.d`. | «Не перевірено — звір дані з чеком». |
| 6 | Ключ скомпрометовано | Дата паспорта ≥ `compromisedFrom` ключа, що підійшов. | «Ключ «…» скомпрометовано з ДД.ММ.РРРР». |
| 7 | Ключ не продовжено | Дата паспорта пізніше `validUntil` цього ключа. | «Ключ бренду не продовжено». |
| 8 | Перевірено | Усе інше. | «Підписано «…» · дані не змінені». |

**Дата паспорта** — з позначки часу (§3.4), якщо вона є й перевірена; інакше `i.d`.

У паспорті (§4) Archy ще звіряє збережений маніфест із відбитком `m.h`: не збігся — «Підпис не збігається».

Паспорт із датою покупки до `validUntil` лишається дійсним назавжди, навіть якщо ключ згодом не продовжено.

Лише в Archy: річ, збережена з QR до версії 1.1 (сирого рядка немає), позначається «Паспорт без оригіналу».

### 3.4. Позначка часу Quiet Apps

Дату `i.d` ставить сам бренд. Щоб її не можна було підробити (друкувати після оплаченого строку зі старою датою), генератор у момент друку отримує позначку часу від сервера Quiet Apps:

1. Генератор надсилає на `https://api.quietapps.app/ts` домен бренду, SHA-256 стиснутих байтів payload і підпис цього запиту ключем бренду. **Дані речі до нас не потрапляють** — лише відбиток.
2. Сервер перевіряє бренд за реєстром, підпис запиту, оплачений строк (`validUntil`) і пакет (`quota`; повторний запит того самого коду в пакет не рахується), записує в журнал «бренд · відбиток · дата» і повертає `TS1.<yyyymmdd>.<підпис>`: Ed25519 ключем позначок Quiet Apps над UTF-8 `ARCHY-TS1|<yyyymmdd>|` + SHA-256 payload.
3. Генератор ставить позначку перед кодом: `…#TS1.20261120.<sig>/ARCHY1.…`.

Archy і quietapps.app/q перевіряють позначку без мережі (ключі позначок — у підписаному реєстрі, `ts`). Дата паспорта береться з позначки, тож строк ключа (`validUntil`) порівнюється з датою друку за сервером. Без мережі генератор друкує код без позначки й попереджає; після `tsFrom` такий код показується «Без позначки часу».

Сервер — Cloudflare Worker + D1 (журнал видачі = облік паспортів для рахунків).

### 3.5. Втрачений або скомпрометований ключ

Напишіть нам. Ми проставимо `compromisedFrom` (дата, з якої ключу не можна довіряти) і внесемо ваш новий ключ. Паспорти з датою покупки раніше цієї дати лишаються «перевірено».

## 4. Паспорт бренду в Archy

Підписаний код з однією річчю Archy 1.1+ зберігає як **паспорт бренду** (крім коду, підпис якого вже при скануванні не збігся з ключем бренду). Статус перевіряється за реєстром при кожному відкритті картки: якщо ваш ключ з'явиться в реєстрі пізніше, паспорти, збережені раніше, стануть «перевірено» самі.

- зберігається сирий рядок QR, домен бренду, дата сканування й маніфест файлів (§6), окремо від даних власника;
- у картці речі два шари: **«Паспорт від …»** (назва, артикул, метали, клеймо, камені, сертифікат, ціна, дата, гарантія, файли бренду), який не редагується, і **«Моє»**: фото й документи власника, події, нагадування, нотатки, своя назва речі;
- статус підпису перевіряється з того самого збереженого рядка при кожному відкритті картки, без мережі;
- якщо власник бачить розбіжність (наприклад, «вага не збігається»), він додає «Зауваження до паспорта», але сам паспорт не змінюється;
- файли з маніфесту позначені «від бренду», окремо їх не видалити, лише разом із річчю;
- при передачі речі новому власникові й у резервній копії паспорт іде як є, і в нового власника підпис перевіряється заново;
- у PDF — окремий розділ «Підписано брендом»: поля паспорта, статус, список файлів бренду з SHA-256 і QR для перевірки на quietapps.app/q; нотатки власника — окремим розділом.

Код із кількома речами (комплект) заповнює картку як звичайно, але паспортом не стає. Для паспорта друкуйте окремий код на кожну річ.

## 5. Перевірка будь-ким: quietapps.app/q

Камера телефона відкриває `https://quietapps.app/q#ARCHY1.…`. Сторінка без нашого сервера:

- розпаковує код у браузері (частина після `#` на сервер не йде);
- завантажує реєстр із quietapps.app і перевіряє підпис через WebCrypto Ed25519;
- показує бренд, річ і статус (§3.3). Якщо браузер не вміє Ed25519, сторінка пише «Перевірте в Archy».

**Файли бренду** — лише за кнопкою «Показати файли бренду»: тоді браузер звертається до вашого сайту (не до нас) за маніфестом і файлами.

- Якщо ваш сайт віддає заголовок `Access-Control-Allow-Origin: https://quietapps.app` для маніфесту й файлів, сторінка звірить маніфест із відбитком у коді, кожен файл — із SHA-256 у маніфесті, і покаже фото та документи. Файл, що не завантажився чи не збігся, позначено «не завантажився або змінений»; змінений маніфест — «файли змінили після видачі».
- Без цього заголовка браузер не дасть прочитати маніфест: сторінка покаже дані з коду й напише, що файли покупець побачить в Archy. Archy перевіряє файли й без CORS.

### 5.1. Віджет перевірки на сайті бренду (пакет `widget`)

Покупець перевіряє паспорт прямо на сайті бренду: камерою, фото QR або вставкою коду. Перевірка та сама, що в Archy й на quietapps.app/q; код нікуди не надсилається. Працює для брендів, у яких у реєстрі `pack` містить `widget`; інакше віджет пише, що перевірку не підключено.

```html
<div data-archy-verify="aurum.example" data-accent="a3762a" data-lang="uk"></div>
<script src="https://quietapps.app/q/embed.js" async></script>
```

- `data-archy-verify` — домен бренду, як `id` у реєстрі; `data-accent` — колір кнопок (hex без `#`); `data-lang` — `uk`, `en` чи `lv` (типово — мова браузера); `data-theme` — `light` чи `dark` (типово — як у системі).
- Скрипт вставляє iframe `https://quietapps.app/q/embed/?b=<домен>` з `allow="camera"` і сам підганяє висоту. Можна вставити iframe і напряму — тоді висоту задайте самі (~480 px).
- У віджеті — логотип і назва бренду з реєстру. Код іншого бренду віджет не перевіряє, а відсилає на quietapps.app/q. Виняток — демо-бренд (`demo: true`): його коди віджет будь-якого бренду показує з позначкою «Демо», тож бренд може перевірити свій віджет кодами з demo.quietapps.app. «Детальніше й файли бренду» відкриває quietapps.app/q з цим кодом.
- Камера: `BarcodeDetector` браузера, де він є, інакше бібліотека jsQR (Apache-2.0) з quietapps.app. Камера вмикається лише кнопкою й вимикається, щойно QR знайдено.

## 6. Фото й документи бренду (маніфест)

QR містить лише посилання на маніфест і його відбиток. Маніфест — JSON на **вашому** сайті:

```json
{"v": 1, "files": [
  {"t": "photo", "u": "https://aurum.example/archy/KT-7781/1.jpg", "h": "<sha256>"},
  {"t": "hallmark_photo", "u": "https://aurum.example/archy/KT-7781/hallmark.jpg", "h": "<sha256>"},
  {"t": "certificate", "u": "https://aurum.example/archy/KT-7781/igi.pdf", "h": "<sha256>",
   "n": "Сертифікат IGI", "num": "602318745", "d": "2026-11-12", "until": "2028-11-12"}
]}
```

| Ключ | Значення |
|---|---|
| `t` | `photo` — фото виробу; `hallmark_photo` — фото клейма; або тип документа (§8). |
| `u` | `https://` на **тому самому хості**, що й маніфест. Файли з інших сайтів Archy відкидає. |
| `h` | SHA-256 файла (hex, 64 символи). |
| `n`, `num`, `d`, `until` | Назва (для `other`), номер, дата, «дійсний до». Archy покаже їх у картці документа й у PDF. |

Фото клейма (`hallmark_photo`, лише jpg/png/webp) Archy 1.1+ показує в паспорті поруч із полем «Клеймо» з позначкою «від бренду, підписано» і в PDF поруч із даними клейма. Archy 1.0 цей тип пропускає.

Правила:

- Формати: фото `jpg`/`png`/`webp`, документи — також `pdf`. Archy перевіряє тип за вмістом, а не за розширенням.
- До 12 файлів. Маніфест не більший за 64 КБ, кожен файл — до 25 МБ. Фото понад ліміт картки не додаються.
- **Файли й маніфест не можна змінювати** після друку QR. Змінився хоч байт — відбиток не збігся, і файл не завантажиться. Новий файл — нова адреса й новий QR.
- Тримайте файли доступними щонайменше рік. Archy завантажує їх один раз, одразу після збереження речі, і далі зберігає в себе зашифровано разом із маніфестом.
- Достатньо звичайного `GET` з відповіддю `200`. Авторизація не потрібна. CORS потрібен лише для перевірки файлів на quietapps.app/q (§5). Адреси краще робити незручними для вгадування (`/archy/<випадковий-id>/`).

Генератор робить маніфест сам:

```
files.json (поруч із файлами):
{"base": "https://aurum.example/archy/KT-7781/",
 "files": [{"t": "photo", "path": "1.jpg"},
           {"t": "hallmark_photo", "path": "hallmark.jpg"},
           {"t": "certificate", "path": "igi.pdf", "n": "Сертифікат IGI", "num": "602318745", "d": "2026-11-12"}]}

python tools/archy_qr.py item.json --key aurum.key --manifest files.json -o kt-7781.png
```

Генератор перевіряє файли, рахує SHA-256 і пише `manifest.json` поруч із `files.json`. Потім додає в QR `m.u` = `<base>manifest.json` і відбиток. Викладіть `manifest.json` і файли на `base` як є.

## 7. Категорії й поля шаблону (`c`, `sp`)

| `c` | Поля `sp` |
|---|---|
| `jewellery` | metal, fineness, weight (г, загальна), stone, carat (кт), cut, stoneColour, clarity, stonesOther, size, hallmark, article, certLab, certNumber, appraisal, appraisalDate; кілька металів — `mt` (§2.1) |
| `watch` | brand, model, reference, serial, case, movement, boxPapers, certNumber, appraisal, appraisalDate |
| `phone` | imei, imei2, brand, model, storage, colour, serial |
| `tablet` | imei, brand, model, storage, colour, serial |
| `laptop` | brand, model, cpu, gpu, ram, storage, screen, serial |
| `computer` | brand, model, cpu, gpu, ram, storage, motherboard, psu, serial |
| `components` | componentType, brand, model, serial |
| `tv` | brand, model, diagonal, resolution, serial |
| `camera` | brand, model, lens, shutterCount, serial |
| `audio`, `appliances`, `electronics`, `tools` | brand, model, serial |
| `gaming` | brand, model, storage, serial |
| `energy` | energyType, brand, model, serial, capacity, power, batteryType |
| `art` | author, year, technique, size, provenance, certLab, certNumber, appraisal, appraisalDate |
| `antiques` | objectType, manufacturer, stamp, formModel, decor, paintTech, grade, pieces, author, period, material, hallmark |
| `collectibles` | year, material, condition, catalogNo, certNumber, appraisal, appraisalDate |
| `bullion` | metal, fineness, weight, barNumber, issuer, coinName, certNumber |
| `instruments` | brand, model, year, serial, condition |
| `bike` | brand, model, frameNumber, frameSize, colour, capacity, power |
| `vehicle` | brand, model, year, vin, plate, colour, engine, regCert, osagoUntil, kaskoUntil, inspectionUntil |
| `realEstate` | propertyType, address, area, cadastral, regNumber, share, appraisal, appraisalDate |
| `fashion` | brand, article, size, colour, serial, boxPapers |
| `luxury` | brand, model, dateCode, colour, material, size, authCard, authCheck, boxPapers |
| `furniture` | brand, model, material, size, colour |
| `sport` | brand, model, size, serial |
| `other` | — |

Поля поза шаблоном категорії зберігаються, але в картці не показуються.

## 8. Типи документів (`doc`, `t`)

`receipt` чек · `payment_proof` підтвердження оплати · `warranty` гарантійний талон · `certificate` сертифікат · `service_act` акт сервісу · `manual` інструкція · `registration` реєстрація · `insurance` страховка · `contract` договір · `extract` витяг · `inspection` техогляд · `appraisal` оцінка · `export_permit` дозвіл на вивезення · `other` інше (назва в `n`).

Лише в маніфесті (`t`), не в `doc`: `photo` фото виробу · `hallmark_photo` фото клейма.

## 9. Генератор

**У браузері:** [quietapps.app/archy/shops/generator/](https://quietapps.app/archy/shops/generator/) — те саме, що скрипт нижче, без встановлення. Можна завантажити теку генератора й відкривати `index.html` з диска: він працює без мережі (мережа потрібна лише для позначки часу).

- Ключ бренду: створити (файл `<домен>.key`, 32 байти — той самий формат, що в скрипта) або відкрити наявний. Ключ лишається в браузері.
- Одна річ — формою з полями шаблону категорії, металами й файлами (генератор рахує SHA-256 і готує `manifest.json`); партія — з CSV (колонки нижче) або з теки, де CSV, `files.json` і файли.
- Позначка часу Quiet Apps — галочкою; на `api.quietapps.app/ts` ідуть лише відбитки кодів, підписані ключем бренду.
- Результат: PNG кожного коду, `codes.csv`, маніфести з підказкою, куди їх покласти, — одним zip; аркуш A4 для друку. Кожен код генератор одразу розбирає й перевіряє підпис і позначку часу (самоперевірка) і попереджає, якщо код не стане паспортом (комплект, немає дати) чи надто щільний для вибраного розміру.

**Скрипт:** `tools/archy_qr.py` (Python 3.10+, `pip install qrcode[pil] cryptography`):

```
python tools/archy_qr.py --new-key aurum.key                      # ключ магазину
python tools/archy_qr.py item.json -o ring.png                    # без підпису
python tools/archy_qr.py item.json --key aurum.key -o ring.png    # з підписом
python tools/archy_qr.py item.json --key aurum.key --manifest files.json -o ring.png
python tools/archy_qr.py items.csv --key aurum.key -o out/        # партія: один PNG на рядок
```

CSV має колонки `seller_name`, `seller_id`, `n`, `c`, `p`, `cur`, `d`, `st`, `w`, `sn`, `doc` (через `|`), `u`, `sp.<поле>` (наприклад, `sp.metal`), `mt` (метали через `|`, поля через `;`: `gold;Жовте золото;585;1.11|silver;;925;4.63`) і `manifest` — шлях до `files.json` цієї речі.

Друк. Код із підписом і маніфестом займає близько 650 символів (QR версії ~20). Друкуйте його не менше 4–4,5 см, чорним на білому, з полем навколо (модуль коду — від 0,4 мм; веб-генератор підкаже мінімум для кожного коду). Без маніфесту й характеристик код помітно менший.

## 10. Фіскальний чек

Archy також читає QR фіскального чека ДПС (`https://cabinet.tax.gov.ua/cashregs/check?...`). З нього підставляються дата й сума, а номер чека потрапляє в документ «Чек». Якщо фото чека немає, посилання на чек у кабінеті ДПС зберігається в нотатках. Нічого додатково робити не треба: це звичайний QR вашого РРО/ПРРО.

## 11. Перевірка перед друком

1. Відскануйте код в Archy: «Додати річ» → значок QR. Картка має заповнитися, а статус — відповідати очікуваному (§3.3).
2. Збережіть річ. Фото й документи мають з'явитися в картці. Якщо щось не завантажилось, Archy напише, скільки файлів не пройшло.
3. Відскануйте код звичайною камерою. Має відкритися quietapps.app/q з брендом, карткою речі й статусом підпису.

## 12. Сумісність версій

| | Archy 1.0 | Archy 1.1+ |
|---|---|---|
| Ключі брендів | лише вшиті в збірку | реєстр з quietapps.app + вшиті як запасні |
| `mt` | пропускає; показує `sp.metal`, `sp.fineness`, `sp.weight` | список металів |
| `hallmark_photo` | пропускає | фото клейма в паспорті |
| Паспорт бренду | лише позначка «Дані з QR магазину» | паспорт, який не редагується, зі статусом |

Питання й реєстрація ключа: support@quietapps.app.
