General Information
| Document version | Publication date |
|---|---|
| v 1.9 | 18.08.2026 |
General Information About the Service
The Unified API of External Courier Services is part of the Gold Apple information system and is designed to simplify and unify the exchange of messages with courier services that are Gold Apple partners. The service is a bidirectional API based on REST. The service provides methods for exchanging data between the Gold Apple information system and the courier service's information system depending on the interaction direction specified separately for each method. For ease of use and navigation, the document is divided into corresponding sections, each of which is essentially a description of a method or a set of related methods, listing the relevant parameters, request examples, response examples, and so on.
Service instances in different countries
Please note that if courier services are provided in different countries, the Gold Apple IS instances will differ accordingly, and so will the available endpoints — but only the domain zone will change. This rule works in both directions: if the courier service's IS is deployed in several countries, endpoints must be provided in the corresponding domain zones. For example, for the authorization method:
https://example_cs.ru/api/v1/auth/login
https://example_cs.kz/api/v1/auth/login
This rule applies to all of the methods listed below; however, the direction of each request must be taken into account, i.e. courier service IS endpoints are provided by courier service staff, while Gold Apple endpoints are provided directly by Gold Apple staff.
General Rules of Interaction
- The service requires authorization, which means passing an access token issued by the service;
- the only exception is the authorization method itself, see Authorization in the service
- The service uses a single UTF-8 encoding;
- Data is exchanged using the "application/json" content type unless otherwise specified;
- The format of timestamps and dates must comply with the ISO 8601 standard (UTC with zero offset)
- e.g. 2025-08-05T23:36:00Z;
- Tracking is performed using the Gold Apple order number, i.e. the orderNumber field is simultaneously the tracking number;
- Any optional parameter may be empty or null, but must still be passed;
- Any required parameter must be filled in according to the parameter's data type.
Glossary
| Abbreviation / Term | Description |
|---|---|
| OS | Gold Apple online store |
| ECS | External courier service or several such services. |
| IS | Information system. |
| PP | An order pick-up point of unspecified type, i.e. either a parcel locker or a staffed pick-up point. |
| JSON | JavaScript Object Notation, a data interchange format based on JavaScript. |
| HTTP | Hyper Text Transfer Protocol, an application-layer data transfer protocol. |
| HTTPS | Hyper Text Transfer Protocol Secure, an extension of HTTP using SSL/TLS encryption. |
| Order | An order placed by a customer in the Gold Apple online store. |
| Customer | The end customer of Gold Apple to whom the order is delivered. |
| → | ← | Direction of interaction. For example, OS → ECS means that the request is executed by the OS's IS, and the response is provided by the ECS's IS. |
Test Environment
Before connecting to the test bench, make sure you have been issued a login and password for obtaining a token. To obtain a login and password, please contact Gold Apple representatives!
Connection Requirements
To obtain a login and password, the courier service code that will be used to identify the partner, assigned orders, status ownership, etc. must be agreed in advance. The courier service code is provided as a case-sensitive string. The value may be chosen freely, but should be reasonably short.