Snapcode API — документация

01Авторизация

Каждый запрос к /api/* требует API-ключ в заголовке. Ключи выдаются вручную — если его ещё нет, спроси у администратора сервиса.

X-API-Key: <ваш ключ>

Запрос без ключа или с неверным ключом возвращает 401. Эндпоинт GET /f/:id (отдача файла по временной ссылке) ключа не требует — сама ссылка уже неугадываема и живёт ограниченное время.

02Как это устроено

Три входных эндпоинта — по одному на каждый формат входных данных. У каждого есть параметр ?output=, определяющий формат ответа.

Вход \ выход	base64	binary	url
`POST /api/from-url`	✓	✓	✓
`POST /api/from-base64`	—	✓	✓
`POST /api/from-binary`	✓	—	✓

Формат по умолчанию (без ?output=) — base64. Тип файла сервис определяет сам по сигнатуре байт (PNG/JPEG/GIF/WebP/BMP/AVIF), не доверяя заголовкам или расширению — так надёжнее.

POST/api/from-url

Отдаёшь ссылку на файл — сервис скачивает его сам (без CORS-ограничений, в отличие от браузера) и возвращает в выбранном формате.

Тело запроса

{ "url": "https://example.com/image.png" }

Запрос

curl -X POST \
  'https://snapcode.api.fullbiz-dev.ru/api/from-url?output=base64' \
  -H 'X-API-Key: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/image.png"}'

Ответ 200

{
  "base64": "iVBORw0KGgo...",
  "dataUri": "data:image/png;base64,...",
  "mime": "image/png",
  "size": 8214
}

POST/api/from-base64

Отдаёшь base64 (голую строку или полный data:-URI) — получаешь бинарник или временную ссылку.

Тело запроса

{ "base64": "iVBORw0KGgo..." }
// или с data-URI префиксом:
{ "base64": "data:image/png;base64,iVBORw0KGgo..." }

Запрос — получить ссылку

curl -X POST \
  'https://snapcode.api.fullbiz-dev.ru/api/from-base64?output=url' \
  -H 'X-API-Key: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"base64":"iVBORw0KGgo..."}'

Ответ 200

{
  "url": "https://snapcode.api.fullbiz-dev.ru/f/4kikbkv6...",
  "mime": "image/png",
  "size": 8214,
  "expiresAt": "2026-09-05T23:47:29.953Z"
}

output=binary отдаёт сырые байты напрямую телом ответа с заголовком Content-Type, выставленным по определённому mime-типу.

POST/api/from-binary

Отдаёшь сырые байты файла прямо телом запроса (без JSON-обёртки) — получаешь base64 или временную ссылку.

Запрос

curl -X POST \
  'https://snapcode.api.fullbiz-dev.ru/api/from-binary?output=base64' \
  -H 'X-API-Key: ВАШ_КЛЮЧ' \
  -H 'Content-Type: image/png' \
  --data-binary @photo.png

Ответ 200

{
  "base64": "iVBORw0KGgo...",
  "dataUri": "data:image/png;base64,...",
  "mime": "image/png",
  "size": 8214
}

GET/f/:id

Отдаёт файл, ранее сохранённый через ?output=url. Ключ не нужен — идентификатор неугадываемый (128-битный случайный), а срок жизни короткий.

curl https://snapcode.api.fullbiz-dev.ru/f/4kikbkv6pyzWSrDDa92TlA -o file.png

После истечения срока или для несуществующего id — 404.

03Лимиты

Максимальный размер файла	`20 МБ`
Срок жизни ссылки (`output=url`)	`3 часа` с момента создания, затем файл удаляется
Таймаут скачивания по `from-url`	`10 секунд`

Ссылка одноразовая по смыслу, но не по факту — доступна повторно, пока не истекли 3 часа. Рассчитана на сценарий «получили ссылку → тут же передали в другой сервис»: если конечное приложение вызывается сразу, ссылка гарантированно ещё жива.

04Ошибки

Все ошибки — JSON вида { "error": "текст" } с соответствующим HTTP-статусом.

Статус	Причина
400	Некорректный запрос: не передан `url`/`base64`/тело, невалидный base64, не-http(s) схема в url
401	Не передан или неверный `X-API-Key`
404	Файл по ссылке не найден или срок его жизни истёк
413	Файл больше 20 МБ
502	Не удалось скачать файл по переданному url (недоступен, не 2xx-ответ)
500	Внутренняя ошибка сервиса

Отдельно: запросы на приватные/внутренние адреса (127.0.0.1, 10.0.0.0/8, 192.168.0.0/16 и т.п.) в /api/from-url блокируются намеренно — это защита от SSRF, не баг.

{ "error": "refusing to fetch a private/internal address" }