Рекомендации по интеграции API FedEx

Данное краткое руководство призвано помочь пользователям API разобраться в том, как улучшить интеграцию с FedEx и обеспечить высокое качество интеграции с точки зрения настроек, скорости и конфиденциальности.

Чтобы добиться эффективной интеграции с API FedEx, разработчикам необходимо следовать приведенным ниже рекомендациям по интеграции.

Идентификаторы URI API

• Для тестирования и рабочих решений используются разные идентификаторы URI API. 
• Разработчикам следует использовать для разработки и интеграции тестовые URI, а для рабочих решений — рабочие URI.

Ниже перечислены идентификаторы URI API.

Для тестирования: https://apis-sandbox.fedex.com/

Для работы: https://apis.fedex.com/

Управление учетными данными

• Ключ API и секретный ключ

• Ключ API и секретный ключ используются для идентификации приложения: они необходимы при получении запроса маркера OAuth.

1. Вы обязаны обеспечивать максимальную безопасность при хранении и использовании ключа API и секретного ключа. Не передавайте ключ API или секретный ключ по электронной почте или посредством кода в распределенной среде, включающего клиентские элементы JavaScript.
2. Приложение может оказаться под угрозой рассекречивания, если злоумышленникам станет известен ваш ключ API или секретный ключ. В случае возникновения подозрений в отношении того, что учетные данные были украдены или стали известны третьим лицам, незамедлительно измените секретный ключ.
3. Избегайте внесения в журнал конфиденциальной информации, такой как секретный ключ.

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

• Маркер OAuth

• Маркер доступа должен храниться только на сервере веб-приложений и не должен отображаться в браузере.
• Не задавайте маркер жестко в своих приложениях.
• Защищайте маркеры доступа во избежание их рассекречивания.
• Не выполняйте многократные запросы маркера OAuth API для новых маркеров доступа. Рекомендуется кэшировать маркер доступа на случай возникновения ошибки HTTP 401. В этом случае заново сгенерируйте маркер OAuth.
• Не раскрывайте маркер конечному пользователю или приложению.
• Для любых действий с API используйте протокол HTTPS.

Рекомендации по работе с кодом

• Для обеспечения соответствия новейшим и самым безопасным протоколам передачи зашифрованных данных рекомендуется использовать Протокол защиты транспортного уровня Transport Layer Security (TLS) версии не ниже 1.2.
• Обязательно назначайте корректные заголовки API, необходимые для каждого запроса API. Информация о заголовках находится внизу каждой страницы документации по API. 
• При использовании HTTP-метода POST в поле «Тип содержимого» должно быть указано «application/json».
• Ознакомьтесь с примером кода, прежде чем начать работать с каждым API. Для каждой конечной точки API приведены образцы, которые помогут вам понять, какие требуются элементы и формат, а также прочие подробности.
• Использование пользователями или разработчиками большого количества десятичных знаков при передаче значений может привести к возникновению нечетных ошибок. При указании веса или стоимости/количества допустимо указывать не более двух знаков после запятой. При указании размеров, таких как длина, ширина и высота, допустимо использовать только целые числа.

Пример. Вес: 45,26; объявленная стоимость/сумма: 100,52; длина: 10; ширина: 25; высота: 15.

• Не отправляйте элементы без указания значений.

Например, "Строки с названием улицы":""

• Отправляйте только данные, необходимые для обработки запроса.

Например, при доставке по территории США не следует отправлять коммерческие счета-фактуры и данные о товаре, которые требуются только для международных отправлений.

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

Например, отправка посылки возможна в том случае, если отсутствует функция определения тарифа. Протестируйте ответ транзакции на отсутствие элементов, прежде чем пользоваться данными.

• В целом, по возможности избегайте жесткой зависимости от интеграции с API FedEx.
• Для сокращения времени ожидания и получения точных результатов следуйте рекомендациям.
  
  • Фильтрация: установите фильтр для сужения критериев поиска, указав необходимые параметры.
  • Сортировка: задайте сортировку, чтобы распределить результаты по определенному параметру от большего к меньшему или наоборот.
• Перед отправкой транзакции подтвердите обязательные поля, такие как почтовый индекс получателя и вес посылки. Эти поля не должны быть пустыми. Убедитесь, что данные введены в правильные поля. Это предотвратит возникновение ошибок во время транзакции.
  

Например, при указании почтового индекса США убедитесь, что все введенные символы являются числами и введены в формате 5 цифр от 1 до 9 или в формате почтового индекса ZIP+4.

• Во избежание отрицательного влияния на работу и надежность системы FedEx, следуйте приведенным ниже рекомендациям.
  
  • Не проводите тестирование производительности в тестовой и рабочей среде.
  • Используйте логику кодирования во избежание постоянных ошибок для одной и той же транзакции.
• Установленное ограничение составляет 1400 транзакций за 10 секунд. Если лимит превышен в течение первых нескольких секунд, возникнет ошибка HTTP с кодом 429 Too many requests (Слишком много запросов) и возможность совершать транзакции будет приостановлена на 10 секунд. После этого выполнение транзакций возобновится.
  

Например, если мы получим 1400 запросов в первые четыре секунды, возникнет ошибка HTTP с кодом 429 Too many requests и появится сообщение: «Мы получили слишком много запросов за короткий промежуток времени. Подождите и повторите попытку через некоторое время». Транзакции будут недоступны в течении следующих шести секунд, затем возможность их совершать возобновится.

• Не следует жестко задавать в коде деловой регламент (виды услуг, типы посылок, ограничения по весу и т. д.), поскольку он может измениться.

Обработка ошибок

В каждом ответе API содержится код состояния HTTP и полезная нагрузка ответа. При необходимости в некоторых ответах будет содержаться информация об ошибке, предупреждение или примечание. Предупреждения и примечания не означают критическую ошибку, однако стоит зафиксировать и проанализировать сообщение об ошибке или предупреждение. Правильная обработка ошибок обеспечит плавную и удобную интеграцию с FedEx и поможет избежать сбоев.

Коды состояния HTTP

Тариф

• Существует два способа получить предложение по тарифу.
  
  • Тариф на определенный тип услуги serviceType. Результаты будут отфильтрованы по указанному значению serviceType. Это позволит сформулировать более краткий ответ и сократить время ответа на транзакцию.
    

    Например: STANDARD_OVERNIGHT

  • Поиск тарифа. Если не указано значение serviceType, будут отображены все доступные услуги с соответствующими тарифами.
• Воспользуйтесь API доступности услуг, чтобы узнать, какие услуги, варианты упаковки и особые услуги доступны для указанной пары пунктов отправки и назначения, и передайте значение serviceType и вариант упаковки в запросе тарифа.
  

  Например, услуга STANDARD_OVERNIGHT (в том числе) доступна не для всех почтовых индексов.

• Чтобы особая услуга применялась к конкретному отправлению, необходимо указать вид услуги и подробные сведения. 
  
  • Примечание. У некоторых особых услуг подробные сведения отсутствуют.
• Ознакомьтесь с Документацией по API тарифов.

Отправить

• Воспользуйтесь API доступных услуг, чтобы узнать, какие услуги доступны для отправления из указанного места в указанном направлении, и передайте значение serviceType и вариант упаковки в запросе на отправку.
• Чтобы особая услуга применялась к конкретному отправлению, необходимо указать вид услуги и подробные сведения.
  
  • Примечание. У некоторых особых услуг подробные сведения отсутствуют.
• Выполните закрытие FedEx Ground в конце рабочего дня до забора посылки.
  
• Ознакомьтесь с Документацией по API отправлений..
  

Отслеживание

• Включайте в один запрос на отслеживание не более 30 номеров отслеживания. Это позволит сформулировать более краткий ответ и сократить время ответа на транзакцию.
• Рекомендуется ограничить количество отслеживаний посылки значением, которое необходимо для работы.
• При пакетном отслеживании удалите из пакета все посылки, статус которых изменился на «доставлено».
• Ознакомьтесь с Документацией по API отслеживания.

Проверка адреса

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

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

• Ознакомьтесь с Документацией по API проверки адреса.
  

Поиск офисов FedEx

• Уточните условия поиска, указав определенные атрибуты (такие как тип офиса, предлагаемые услуги и т. д.). Это поможет подобрать подходящий офис и сократить время ожидания ответа.
• Ознакомьтесь с Документацией по API поиска офисов FedEx.
  

Запрос на забор посылки

• При планировании забора посылки не указывайте прошедшие даты или слишком далекие даты в будущем.
• Анонимный забор посылок запрещен.
  
• Ознакомьтесь с Документацией по API запросов на забор посылки..
  

Доступность услуг

• Чтобы получить ответы от нескольких операторов, например FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) и FedEx Ground® Economy, не используйте элемент carrierCodes или отправляйте отдельные запросы о доступности услуг, поскольку указать несколько кодов перевозчика невозможно.
• Убедитесь в наличии предварительного разрешения на использование индивидуальных поддонов на 68,5 кг (151 фунт) или более и поддонов весом более 998 кг (2200 фунтов).
  
• Указание SATURDAY_DELIVERY (ДОСТАВКА В СУББОТУ) в качестве переменной опции обеспечит одновременно и опцию доставки в субботу, и опцию обычной доставки для всех услуг с опцией доставки в субботу. Не указывайте SATURDAY_DELIVERY для особых услуг, при этом будут возвращены только применимые опции доставки в субботу.
• Ознакомьтесь с Документацией по API доступности услуг.

Центр поддержки клиентов

Мы ответим на все вопросы и предоставим необходимую поддержку! Перейдите на страницу Поддержка, где вы найдете контактную информацию и необходимые ресурсы.