Идемпотентность

Передайте заголовок Idempotency-Key со случайным UUID для одного логического документа. Сохраните его в своей базе до первого запроса. Тот же ключ и то же тело запроса возвращают первоначальный PDF без нового списания в течение 24 часов после готовности.

curl https://pdfapi.ru/api/v1/convert \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 9a9384e0-1ea7-4fd5-9363-90990f524e65' \
  -d '{"source":"html","html":"<h1>Счёт</h1>"}' -o invoice.pdf

Ключ действует в пределах аккаунта, включая его другие действующие API-ключи. Допустимы 1–128 латинских букв, цифр и символов . _ ~ -; рекомендуем случайный UUID. Не помещайте в ключ персональные данные. Порядок полей options несущественен; изменение текста, опций или имени Office-файла с тем же ключом возвращает 409 idempotency_conflict. Для URL повтор возвращает первоначальный результат, даже если страница уже изменилась.

Одновременный повтор получает 409 idempotency_in_progress и Retry-After: 2. Таймаут или закрытие соединения не отменяют выполняющийся запрос. Если PDF сохранён, страницы списаны один раз; если процесс прервался раньше, списания нет. Ошибка завершённого рендера сохраняется вместе с ключом: новый рендер требует нового ключа.

После 24 часов тот же ключ возвращает 410 result_expired и никогда сам не запускает платную конвертацию. Короткая запись о ключе и списании остаётся для защиты от повторной оплаты. Удаление зашифрованных данных из базы выполняется фоном; выдача после срока запрещена независимо от фоновой очистки. Системные журналы восстановления БД могут сохранять удалённые блоки до своего обслуживания.

Без переданного ключа сервер создаёт новый и возвращает его в Idempotency-Key. Если ответ полностью потерян, восстановить такой ключ нельзя. Для надёжного восстановления задавайте ключ сами. Повторная выдача проходит обычную авторизацию и лимит частоты, возвращает Idempotency-Replayed: true и X-Result-Expires-At. X-Quota-* отражают расход на момент первоначального сохранения; текущий остаток доступен через /v1/me.

Один PDF ограничен 20 МиБ, сохранённые PDF аккаунта — 128 МиБ, общее хранилище — 1 ГиБ по умолчанию. При переполнении результат не тарифицируется: 503 result_storage_full. Ограничения задаются оператором; отдельная плата за временное хранение не взимается.

Библиотеки#

Новые локальные версии TypeScript и Python SDK создают один ключ на вызов и сохраняют его при внутренних повторах. Для повтора после исключения передавайте собственный ключ:

await client.html(html, { idempotencyKey: operationId });

client.html(html, idempotency_key=operation_id)

Ключ доступен также в error.idempotencyKey (TypeScript) и error.idempotency_key (Python). Автоматический повтор таймаутов остаётся выключенным: отмену приложения и бесконечный рендер библиотека не скрывает. В PHP, Go и .NET передавайте заголовок через свой HTTP-транспорт; встроенные параметры этих версий пока не расширены. Поддержка требует обновлённого сервера; старый сервер игнорирует заголовок и такой гарантии не предоставляет.