API подписки по номерам отслеживания для Advanced Integrated Visibility (AIV) позволяет подписчикам Advanced Integrated Visibility с помощью конечных точек API связывать (ассоциировать) номера отслеживания с проектом webhook AIV. Функция ассоциации номеров отслеживания поддерживает два метода обработки:

• Синхронная ассоциация номеров отслеживания: возвращает результаты обработки внутри того же HTTP-ответа. Такой метод больше подходит в случаях связывания небольшого количества номеров отслеживания, требующих немедленного подтверждения. 
• Асинхронная ассоциация номеров отслеживания: в этом случае происходит отправка запроса на обработку данных в фоновом режиме, а в качестве ответа возвращается идентификатор задания, с помощью которого можно получить статус и результаты обработки позднее. Этот метод оптимален для обработки крупных пакетов номеров отслеживания. 

Мы рекомендуем выбирать метод обработки исходя из возможностей используемого решения и требований к рабочей нагрузке.

Примечание:

• У вас должен быть доступ администратора или участника к проекту Advanced Integrated Visibility.
• Дополнительные сведения о решении Advanced Integrated Visibility и его возможностях можно найти на странице документации по Advanced Integrated Visibility .

API подписки по номерам отслеживания для Advanced Integrated Visibility предоставляет следующие преимущества:

• Простота связывания и обновления номеров отслеживания, а также управления ими в рамках проектов webhook Advanced Integrated Visibility с использованием конечных точек API.
• Возможность связывать множество номеров отслеживания в единый API-запрос, вместо того чтобы обрабатывать каждый номер отслеживания отдельно.
• Наличие двух методов обработки на выбор — синхронного для быстрого получения результатов и асинхронного для пакетных операций.

Для управления проектом Advanced Integrated Visibility используйте следующие конечные точки:

• Синхронная ассоциация номеров отслеживания: позволяет связывать номера отслеживания с webhook и получать окончательный статус обработки в рамках того же HTTP-ответа.
• Асинхронная ассоциация номеров отслеживания: позволяет связывать номера отслеживания с webhook и использовать возвращенные jobId позднее, чтобы проверять статусы асинхронных заданий или загружать данные с помощью соответствующих конечных точек.    
  • Статус задачи для номеров отслеживания
  • Сведения о задаче для номеров отслеживания

Доступ к этим API можно получить на странице краткого описания проекта Advanced Integrated Visibility.

Получить доступ к этим API можно только через краткое описание проекта, как показано на снимке экрана выше.

В приведенной ниже таблице обобщены различия между синхронной и асинхронной конечными точками ассоциации номеров отслеживания.
 

Если вы хотите получать немедленные подтверждения по малым объемам номеров отслеживания, используйте синхронную конечную точку. Если необходимо обрабатывать большие объемы номеров отслеживания, не требующие немедленных подтверждений, используйте асинхронную конечную точку.

С помощью этой конечной точки вы можете связывать один или несколько номеров отслеживания с проектом webhook Advanced Integrated Visibility и получать результаты обработки внутри того же HTTP-ответа.

Данная конечная точка предназначена для тех случаев, когда требуется немедленное подтверждение, и поддерживает запросы, содержащие до 150 номеров отслеживания.

Необходимые входные данные: 

• subscriptionID
• trackingNumber

Преимущества

Синхронная конечная точка обладает следующими преимуществами:

• Мгновенные результаты обработки
• Подробные сведения об успешных и неуспешных результатах в рамках одного ответа
• Поддержка до 150 номеров отслеживания в одном запросе
• Проверка запросов и принудительное применение бизнес-правил до обработки
• Машиночитаемые коды ошибок и информативные сообщения об ошибках
• Идентификаторы транзакций для отслеживания запросов и устранения неполадок

Конечная точка с синхронной ассоциацией номеров отслеживания применяет несколько правил проверки, которые в том числе:

• требуют наличия действительного и активного идентификатора subscriptionId;
• допускают использование в рамках запроса только одного идентификатора subscriptionId;
• требуют наличия номера trackingNumber;
• проверяют, отвечают ли номера отслеживания требованиям FedEx к их форматированию (в том числе ограничению на длину в пределах от 6 до 22 цифр).

Сообщения об ошибках имеют согласованную структуру, при которой в квадратных скобках указываются код и сообщение для удобного анализа.

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

Конечная точка с синхронной ассоциацией номеров транзакций допускает получение частично успешных результатов. Даже если некоторые номера отслеживания оказываются несвязанными, Synchronous API все равно возвращает результат 200 OK и предоставляет следующие данные:

• номера failedTrackingNumber;
• описательное сообщение.

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Below tracking numbers failed to upload due to validation or system errors"

      }

    }

Дополнительную информацию и правила см. в разделах о бизнес-правилах.

Используйте эту конечную точку для отправки одного или нескольких номеров отслеживания по подписке, если для вас предпочтительна их обработка в фоновом режиме.

В этом случае запрос возвращает идентификатор задания, который можно применить к конечной точке со статусом задания номера отслеживания, чтобы отслеживать ход обработки. Идентификатор задания также можно применить к конечной точке со сведениями о задании для номеров отслеживания, чтобы загрузить результаты обработки по завершении задания.

Необходимые входные данные:

• Действие
• Сведения о номере отслеживания

В одном запросе можно связать до 1000 номеров отслеживания.

Преимущества

Асинхронная конечная точка обладает следующими преимуществами:

• Поддержка отправки крупных пакетов (до 1000 номеров отслеживания)
• Возможность обработки длительных запросов в фоновом режиме
• Отслеживание статусов заданий и загрузка отчетов об обработке
• Отсутствие проблем, связанных с истечением времени ожидания запросов при больших объемах работы

Эта конечная точка используется для получения статуса асинхронной задачи (один или несколько последовательных запросов в очереди) или статуса всех отправленных задач.

Для выполнения этого запроса требуются следующие исходные данные:

• jobID — укажите идентификатор задания, по которому вы запрашиваете статус.

Примечание. Для этой конечной точки идентификатор задания вводить не обязательно. Если он не указан, вы получите статусы всех отправленных заданий.

Успешный ответ на этот запрос вернет jobID, текущий статус задачи, а также временную метку ее создания и завершения. В ответе будет указан текущий статус задач. Кроме того, он будет включать сообщения об успехе, ошибки и предупреждения для целей устранения неполадок.

• Если статус задачи отображается как COMPLETED (Выполнено), это означает, что все номера отслеживания были успешно проверены и обработаны.
  • Статус задачи COMPLETED означает, что номера отслеживания успешно проверены и обработаны. Это не означает, что все номера отслеживания были успешно добавлены в проект Advanced Integrated Visibility.
  • У заданий с большим количеством номеров отслеживания статус может считаться выполненным (COMPLETED), даже если не все номера удалось связать с проектом. Чтобы подтвердить статус каждого номера отслеживания в исходном запросе на ассоциирование, необходимо загрузить пакетный отчет.

Примечание. Если статус задания отображается как выполненный с ошибкой (FAILED), это означает, что по ряду причин или серьезных ошибок запрос не удалось обработать и поэтому пользователю необходимо его повторить.

В приведенной ниже таблице показаны статусы заданий и их описания.

Используйте эту конечную точку для загрузки отчета в формате JSON для асинхронной задачи, находящейся в состоянии COMPLETED (Выполнено).

С этим запросом связана следующая необходимая вводная информация:

• jobID — укажите идентификатор задания, по которому вы запрашиваете статус. Для этой конечной точки указывать идентификатор задания обязательно.

Примечание:

• Одновременно можно загрузить только один отчет об асинхронном задании.
• Если вы пытаетесь загрузить отчет для задачи со статусом, отличным от COMPLETED (Выполнено), отображается сообщение об ошибке.

Успешный ответ на этот запрос предоставит отчет о задаче в формате JSON.

Типовые бизнес-правила

• Общее количество номеров отслеживания, которые можно связать с проектом Advanced Integrated Visibility, не ограничено.
• Номера отслеживания, связанные с проектом Advanced Integrated Visibility, отвязываются через 40 дней, после того как они были связаны с webhook.
• Конфиденциальная информация для отслеживания, например адрес и подпись получателя, а также прочие сведения личного характера, в API подписки по номеру отслеживания не отображается.

Бизнес-правила для синхронной конечной точки

• Не более 150 номеров отслеживания в одном запросе.
• Все номера отслеживания должны иметь один и тот же идентификатор subscriptionId.
• Указанная подписка webhook Advanced Integrated Visibility должна быть действительной и активной.
• Для запросов действует 30-секундное истечение времени ожидания.

Бизнес-правила для асинхронной конечной точки

• Не более 1000 номеров отслеживания в одном запросе.
• Статус задания и сведения о задании для асинхронного запроса хранятся в течение 90 дней после успешного связывания номеров отслеживания с webhook Advanced Integrated Visibility.