Таблицы

Преобразуйте ссылки в Google-таблице или загруженной книге с bearer-токеном вашего аккаунта. Результат всегда имеет формат .xlsx, даже для CSV. Ссылки заменяются на месте с привязкой к вашему аккаунту и необязательными campaign и label, описанными на странице Ссылки.

Исходная Google-таблицаКопировать ссылку на раздел

Отправьте URL Google Sheets, который NinjaBuy может прочитать. Преобразование читает все вкладки, а не только предпросмотр, и фиксирует снимок для этого задания.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

Исходный XLSX или CSVКопировать ссылку на раздел

Сначала зарезервируйте загрузку. filename должно заканчиваться на .xlsx или .csv и содержать от 1 до 255 символов после удаления пробелов по краям. bytes — точный размер файла в байтах от 1 до 20 971 520.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

Ответ 201 содержит upload_id, подписанный PUT-адрес url, expires_at (миллисекунды с начала эпохи Unix), max_bytes и request_id. Резервирование истекает через 15 минут. Отправьте исходный файл методом PUT на полученный URL, затем передайте идентификатор загрузки:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

Прямой PUT использует формат ответа сервиса хранения. NinjaBuy проверяет загруженные байты при отправке задания на преобразование. Неизвестные идентификаторы и загрузки других аккаунтов возвращают 404. Сохранённый объект должен соответствовать заявленному числу байтов; объект больше заявленного размера или максимума возвращает 413 upload-too-large, а меньший (обрезанный) объект возвращает 422 invalid-workbook с объяснением несоответствия числа байтов. Эти проверки выполняются до скачивания и также применяются, если байты изменились после проверки метаданных. Отклонённые исходные загрузки удаляются, а принятые исходные загрузки удаляются после сохранения их проверенного снимка.

Укажите ровно один источник: url или upload_id. Оба варианта принимают необязательные campaign и label; async не требуется. Оба POST-маршрута поддерживают Idempotency-Key и расходуют по одному вызову из общего лимита 30 вызовов в минуту. Дочерние преобразования ссылок дополнительных вызовов не расходуют.

Задание и скачиваниеКопировать ссылку на раздел

Отправка таблицы возвращает 202 с Location: /api/v1/jobs/JOB_ID, Retry-After: 5 и телом:

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

Опрашивайте Задания с токеном того же аккаунта до done или failed, соблюдая poll_after_seconds. Завершённый job.result содержит kind: "sheet_conversion", counts и подписанный download_url, действительный 15 минут. Повторный запрос выдаст новую подпись для скачивания. Неудачное задание содержит error и не предоставляет частичный файл.

Для Google Таблицы job.result может также содержать copy_url: ссылку только для просмотра на точную копию в Google Таблицах, где ссылки заменены вашими; любой, у кого есть ссылка, может сохранить собственную копию через Файл → Создать копию. copy_notes перечисляет то, что нужно знать читателю этой копии, например что изображениям, вставленным через =IMAGE(), в его копии нужен один клик по Разрешить доступ. download_url по-прежнему возвращает XLSX. copy_counts содержит те же счётчики для копии; если XLSX создать не удаётся, в результате остаётся copy_url, нет download_url, а copy_notes объясняет причину. download_notes перечисляет построчно то, что XLSX не может хранить из таблицы, например диаграммы или вторую ссылку в ячейке.

Снимки и файлы результатов хранятся семь дней после завершения задания или его сбоя. После очистки задание остаётся доступным для чтения со своим статусом и счётчиками, а поле job.result.download_url отсутствует. Общие снимки сохраняются, пока они нужны другому заданию. Неиспользованные исходные загрузки удаляются через час после истечения резервирования загрузки; проверенная загрузка, для которой так и не запустили задание, теряет снимок через семь дней после истечения резервирования. Очистка выполняется каждый час.

Покрытие соответствует равенству links_found = converted + sum(left_by_host) + unresolved. Социальные ссылки, ссылки Google Sheets, навигация внутри книги и существующие ссылки NinjaBuy остаются без изменений. Каждый кандидат должен получить ответ до записи результата; отсутствие ответов приводит к сбою задания.

Сохранение содержимого книгиКопировать ссылку на раздел

Результат сохраняет стили, объединения, размеры строк и столбцов и изображения в том виде, в котором они представлены в прочитанной сетке. Форматированные текстовые фрагменты сохраняются в ячейках без гиперссылки ячейки; ячейки со ссылкой используют одну текстовую подпись и гиперссылку. Книга сериализуется заново: диаграммы, макросы и другие функции вне сетки не сохраняются.

XLSX поддерживает одну гиперссылку на ячейку. Преобразование заменяет ссылки на месте, не добавляя вторую ссылку рядом. Ячейка с двумя или более разными целями ссылок, не относящихся к изображениям, сохраняет первую как гиперссылку, а остальные перечисляет в примечании к ячейке, так что ни одна цель не теряется.

ОграниченияКопировать ссылку на раздел

Превышение ограничения чтения или записи приводит к явному сбою. См. Ошибки: invalid-workbook, upload-expired и upload-too-large.