Доступ к учётной записи и документу
Скачайте существующее вложение из проекта переноса номеров, принадлежащего вашей учётной записи API. Используйте активированную учётную запись API и подключение по HTTPS с разрешённого IP-адреса. Проект не должен быть удалён. Поиск по идентификатору документа выполняется в пределах этого проекта; этот идентификатор не является общедоступной ссылкой для скачивания вне контекста проекта.
Определите нужный документ
Просмотрите ответ с подробными сведениями о проекте и выберите запись из списка uploads. Запись содержит числовой идентификатор id, исходное имя файла, сохранённое расширение и относительный адрес download_url. Используйте идентификатор проекта uniqueid и идентификатор выбранной загрузки, а не числовой идентификатор строки проекта или строки телефонного номера.
Преобразуйте возвращённый относительный URL в полный адрес только на основе настроенного вами доверенного хоста API. Для скачивания требуется та же аутентификация учётной записи; метаданные документа не предоставляют доступ без аутентификации.
Отправьте запрос и сохраните ответ
Задайте для PROJECT_ID и DOCUMENT_ID значения из проекта вашей учётной записи. Примените URL-кодирование к идентификатору проекта. В этом примере байты и заголовки ответа сохраняются отдельно; используется заранее заданное имя локального выходного файла, а не имя файла вложения, которому нельзя безусловно доверять.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--dump-header document-headers.txt \
--output porting-document.bin \
"https://api.multitel.net/v3/lnp/project/$PROJECT_ID/document/$DOCUMENT_ID"Используется запрос GET без тела. Он считывает одно вложение целиком; для этой конечной точки не предусмотрены разбиение на страницы, оболочка JSON или документированные условия скачивания диапазона байтов.
Двоичный ответ и заголовки
При успешном выполнении тело содержит сохранённые байты вложения после декодирования прежнего формата хранения, а не base64 и не объект ответа JSON. Метод отправляет заголовок Content-Disposition для вложения, используя сохранённое имя файла с удалёнными двойными кавычками. Нельзя гарантировать, что заголовок закодирован по стандартам или представляет безопасный путь к локальному файлу; задайте собственное имя файла для сохранения.
| Сохранённое расширение | Content-Type |
|---|---|
| application/pdf | |
| png | image/png |
| jpg, jpeg | image/jpeg |
| doc | application/msword |
| Другие значения | application/octet-stream |
Расширения сопоставляются без учёта регистра. MIME-тип выбирается по сохранённому расширению, а не по результатам проверки содержимого; этот выбор не гарантирует корректность документа.
Проверьте скачанный файл
- Проверьте как статус HTTP, так и заголовки ответа. При ошибках аутентификации или поиска вместо файла может быть возвращён ответ API в формате JSON. Не считайте любое непустое тело ответа или сохранённый выходной файл признаком успешного скачивания PDF.
- Если тело содержит ошибку в формате JSON, проверьте
status.codeиstatus.msg. Храните данные ошибки отдельно от ожидаемого документа. - Убедитесь, что полученный файл не пуст и открывается как файл ожидаемого типа. Если у вас сохранился оригинал, сравните контрольные суммы, прежде чем полагаться на копию.
- Если результат пуст, некорректен или отличается от оригинала, остановитесь и попросите службу поддержки проверить сохранённое вложение. Повторное скачивание не исправляет данные в хранилище.
Совместимость с прежним форматом хранения
Текущий механизм загрузки через API и проверенные компоненты записи загружаемых файлов портала и прежней системы сохраняют байты документа с экранированием. При этом скачивании экранирование снимается. Автономные тесты фактического обработчика подтверждают сохранение всех значений байтов и буквальных обратных косых черт для этого формата хранения.
Это не гарантирует такое поведение для каждой старой записи или записи, импортированной из внешнего источника. Обработчик всегда декодирует сохранённый двоичный объект и не определяет, была ли запись импортирована без ожидаемого экранирования. Если в записи отсутствует сохранённый двоичный объект, обработчик также не пытается получить файл по пути к нему. Такие записи могут возвращать изменённые байты или пустой результат. Проверьте результат и попросите службу поддержки исследовать проблемное вложение; не изменяйте документ клиента и не считайте его метаданные доказательством доступности файла.
Текущий портал сначала использует этот маршрут API и дополнительно располагает локальными резервными механизмами получения файла. Успешное скачивание через портал не доказывает, что каждую старую запись можно скачать напрямую через этот API.
Ошибки и последствия вызова
Если проект отсутствует, удалён или не принадлежит вашей учётной записи, возвращается код API 404 с сообщением о том, что проект не найден. Если загрузка отсутствует в проекте, принадлежащем вашей учётной записи, возвращается код API 404 с сообщением о том, что документ не найден. Читайте тела ответов об ошибках API, а также проверяйте статус HTTP. Для существующей записи, в которой нет пригодных сохранённых байтов, этот обработчик не предусматривает отдельного надёжного ответа об отсутствии документа.
Проверенная конечная точка считывает одно вложение. Она не загружает, не изменяет и не удаляет документ, не подаёт заявку на перенос номеров и не списывает средства со счёта. Вложения для переноса номеров могут содержать сведения, удостоверяющие личность, платёжные данные или сведения о предоставленных полномочиях: используйте их только в рамках разрешённых рабочих процессов учётной записи и не допускайте их попадания в общедоступные журналы, аналитические данные и снимки экрана для документации.