Общая информация
| Версия документа | Дата публикации |
|---|---|
| v 1.9 | 18.08.2026 |
Общая информация о сервисе
Сервис Единое АПИ Внешних Курьерских Служб является частью информационной системы компании Золотое Яблоко и служит для упрощения и унификации обмена сообщениями с курьерскими службами - партнёрами Золотого Яблока. Сервис представляет собой двунаправленное АПИ, построенное на основе технологии REST. Сервис предоставляет методы для подключения к информационной системе Золотого Яблока и подключается к информационной системе курьерской службы в зависимости от направления взаимодействия, указанного для каждого метода отдельно. Для удобства изучения и навигации документ разбит на соответствующие разделы, каждый из которых, по сути - есть описание метода или набора связанных методов с перечислением соответствующих параметров, примеров запросов, примеров ответов и так далее.
Экземпляры сервисов в разных странах
Обратите внимание на то, что если услуги ВКС предоставляются в разных странах, то на стороне ИС Золотого Яблока - экземпляры сервиса будут разными, соответственно и наборы эндпоинтов будут разными, но изменится при этом только доменная зона. Это правило работает в обе стороны, то есть если ИС ВКС развёрнута в нескольких странах - то требуется предоставить эндпоинты в разных доменных зонах. Например, в случае с методом авторизации:
https://example_cs.ru/api/v1/auth/login
https://example_cs.kz/api/v1/auth/login
Правило сохраняется для любых нижеперечисленных методов, однако требуется учитывать направление запроса, т.е. эндпоинты на стороне ИС ВКС - предоставляются сотрудниками ИС ВКС, а эндпоинты ИС Золотого Яблока - непосредственно сотрудниками ЗЯ.
Общие правила взаимодействия
- При работе с сервисом предусмотрена авторизация, что требует передачу access-токена, выданного сервисом;
- исключение составляет только метод авторизации в сервисе, см. Авторизация в сервисе
- При работе с сервисом предусмотрена единая кодировка UTF-8;
- Обмен данными ведётся с типом содержимого "application/json", если не указано иное;
- Формат временных штампов и дат должен соответствовать стандарту ISO 8601 (UTC с нулевым смещением)
- например 2025-08-05T23:36:00Z;
- Отслеживание ведётся по номеру заказа Золотого Яблока, то есть поле orderNumber одновременно и трек-номер;
- Любой необязательный параметр может быть пустым или нулевым, но должен быть передан;
- Любой обязательный параметр должен быть заполнен в соответствии с типом данных параметра.
Глоссарий
| Сокращение-термин | Описание |
|---|---|
| ИМ | Интернет - магазин Золотое Яблоко |
| ВКС | Внешняя курьерская служба или несколько служб. |
| ИС | Информационная система. |
| ПВЗ | Пункт выдачи заказа неуточнённого типа, то есть и постамат и непосредственно ПВЗ |
| JSON | JavaScript Object Notation, формат обмена данными, основанный на JavaScript. |
| HTTP | Hyper Text Transfer Protocol, протокол прикладного уровня передачи данных. |
| HTTPS | Hyper Text Transfer Protocol Secure, расширение протокола HTTP, с использованием шифрования SSL/TLS |
| Заказ | Заказ интернет-магазина Золотое Яблоко, осуществлённый клиентом. |
| Клиент | Конечный клиент компании Золотое Яблоко, которому осуществляется доставка заказа |
| → | ← | Направление взаимодействия. Например ИМ → ВКС - означает, что запрос выполняет ИС ИМ, а ответ предоставляет ИС ВКС |
Тестовое окружение
Перед подключением к тестовому стенду необходимо убедиться, что вам выдан логин и пароль для получения токена. Для получения логина и пароля, пожалуйста, свяжитесь с представителями Золотого Яблока!
Требования к подключению
Для получения логина и пароля необходимо заранее оговорить код курьерской службы, который будет использоваться для идентификации партнёра, назначенных заказов, принадлежности статусов, e.t.c. Код курьерской службы передаётся строкой с произвольным, регистрозависимым значением, лучше всего если он не будет слишком длинным.