Retrieving the Courier Service Pickup Point Directory

If the courier service has its own pickup points that are covered by the signed agreement, the Gold Apple IS needs to have such a directory in order to provide customers with information about available pickup points. The endpoint must be published over the secure HTTPS protocol. Before the integration is fully launched into production, the Gold Apple IS executes a request to the courier service's IS to obtain the full list of all available PPs in the format required by the Gold Apple IS. This request may also be executed by the Gold Apple IS after the integration is launched, as needed to keep the pickup point directory up to date. The directory maintained in the Gold Apple IS, and its individual elements, may be changed at the courier service's request using the following methods:

Basic Information

Request method type	GET
Path / URL	/api/v1/pickpoints
Description	Method used to retrieve the list of PPs provided by the courier service
Direction	The request is executed by the Gold Apple IS. The response is provided by the courier service.

Request

Header Parameters

Parameter	Data type	Required	Description	Comment
Authorization	string	1	Access token obtained during authorization. Passed in the format `Bearer <access_token>`	The format is defined by the courier service (see Authorization in the ECS Service)
content-type	string	1	Request content type	Filled in as "application/json"

Request example

curl --location 'https://api.example-cs.com/api/v1/pickpoints' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
  -H "Content-Type: application/json"

Response

Response Codes and Messages

Code	Status	Message	Reason
200	OK	Success	Everything completed successfully. The PP directory is provided in the response payload
400	Bad Request	Missing or inappropriate required parameters	Required parameters are missing or invalid
401	Unauthorized	Token is invalid	Authentication error at the courier service
403	Forbidden	Has no permission	Insufficient permissions
500	Internal Server Error	Server unavailable	The server is unavailable

Successful Response Parameters

№	Parameter			Data type	Required	Description	Comment
1	countryISOCode			string (2)	1	Country code for the directory	Per the "ISO 3166-1, alpha-2" standard
2	deliveryServiceCode			string (100)	1	Courier service code	Agreed upon during system integration.
3	pickpointsList			array of objects	1	Array of pickup point objects
4		id		string (100)	1	Courier service PP identifier	Passed by the courier service
5		type		string (20)	1	Pick-up point type	See "Format Tables" → "Table 1"
6		address		address object	1	Object containing address data
7			Address object type	object	1	Object containing address information.	Address object (see Appendix: Address Data Types)
8		openingHours		array of objects	1	Array of PP working-hours objects
9			dayOfWeek	enum	1	Identifier of the day for which the working schedule is set	See "Format Tables" → "Table 3"
10			workingDay	bool	1	Working-day flag	If on, the PP operates on this day of the week
11			opens	string (15)	0	PP opening time	Per the "ISO 8601" standard (hh:mm:ss)
12			closes	string (15)	0	PP closing time	Per the "ISO 8601" standard (hh:mm:ss)
13		phoneNumber		string (20)	0	PP phone number	No special characters, digits only (country code and area code)
14		isAvailable		boolean	1	PP availability status	If the flag is on, the PP is active; if off, it is not
15		orderStoragePeriod		int	1	Order storage period, in calendar days	Example: 5
16		options		object	1	Object with options available at the PP
17			orderIssuing	bool	1	Order issuing available	If on, the PP can hand out orders
18			orderReturning	bool	1	Order return available	If on, the PP can accept returns
19			haveTryOn	bool	1	Fitting rooms and try-on available	If on, the PP has fitting rooms
20			havePartialBuy	bool	1	Partial purchase available	I.e. the PP can carry out a partial hand-out
21			packageMinWeight	int	1	Minimum parcel weight for this PP, in grams
22			packageMaxWeight	int	1	Maximum parcel weight for this PP, in grams
23			packageMaxLength	decimal	1	Maximum parcel length for the PP, in centimeters.	Along the X axis. Precise to two decimal places
24			packageMaxHeight	decimal	1	Maximum parcel height for the PP, in centimeters.	Along the Y axis. Precise to two decimal places
25			packageMaxWidth	decimal	1	Maximum parcel width for the PP, in centimeters.	Along the Z axis. Precise to two decimal places
26		paymentOptions		object	1	Object with payment-on-receipt options
27			haveCashPayment	bool	1	Cash payment available (register)	If on, cash payment is possible at the PP
28			haveCardPayment	bool	1	Card payment available (terminal)	If on, the PP accepts card payment
29			haveQrCodePayment	bool	1	QR-code payment available (terminal, PP software)	If on, the PP has QR-code payment

Successful response example

{
  "countryISOCode": "RU",
  "deliveryServiceCode": "EXAMPLE_CS",
  "pickpointsList": [
    {
      "id": "PP-SPB-001",
      "type": "PICKPOINT",
      "address": {
        "addressType": "gar",
        "fullAddress": "190000, Saint Petersburg, Nevsky Ave., 28",
        "regionFias": "c2deb16a-0330-4f05-821f-1d12d16a218a",
        "cityFias": "f1a154e5-7982-4d4b-a70d-5e9a01350320",
        "houseFias": "a1b2c3d4-5678-90ef-1234-567890abcdef",
        "flat": "",
        "latitude": 58.0167,
        "longitude": 56.235,
        "addressComment": "2nd floor, near the escalator"
      },
      "openingHours": [
        {
          "dayOfWeek": 1,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 2,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 3,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 4,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 5,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 6,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "20:00:00"
        },
        {
          "dayOfWeek": 7,
          "workingDay": false,
          "opens": null,
          "closes": null
        }
      ],
      "phoneNumber": "78121234567",
      "isAvailable": true,
      "orderStoragePeriod": 5,
      "options": {
        "orderIssuing": true,
        "orderReturning": true,
        "haveTryOn": true,
        "havePartialBuy": true,
        "packageMinWeight": 150,
        "packageMaxWeight": 10000,
        "packageMaxLength": 100,
        "packageMaxHeight": 100,
        "packageMaxWidth": 100
      },
      "paymentOptions": {
        "haveCashPayment": true,
        "haveCardPayment": true,
        "haveQrCodePayment": true
      }
    },
    {
      "id": "PP-MOS-005",
      "type": "POSTOMAT",
      "address": {
        "addressType": "coord",
        "fullAddress": "125009, Moscow, Tverskaya St., 7",
        "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
        "latitude": 55.755816,
        "longitude": 37.617633,
        "flat": "",
        "addressComment": "Parcel locker 'Meridian', 1st floor, near the main entrance"
      },
      "openingHours": [
        {
          "dayOfWeek": 1,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 2,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 3,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 4,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 5,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 6,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 7,
          "workingDay": true,
          "opens": "11:00:00",
          "closes": "21:00:00"
        }
      ],
      "phoneNumber": null,
      "isAvailable": false,
      "orderStoragePeriod": 7,
      "options": {
        "orderIssuing": true,
        "orderReturning": false,
        "haveTryOn": false,
        "havePartialBuy": false,
        "packageMinWeight": 50,
        "packageMaxWeight": 3000,
        "packageMaxLength": 45,
        "packageMaxHeight": 27.9,
        "packageMaxWidth": 30
      },
      "paymentOptions": {
        "haveCashPayment": false,
        "haveCardPayment": true,
        "haveQrCodePayment": true
      }
    }
  ]
}

Unsuccessful Response Parameters

Parameter	Data type	Required	Description	Comment
error	string	1	Human-readable description of the error	see the "Response Codes and Messages" section

Unsuccessful response example

{
  "error": "Token is invalid"
}

Format Tables

Table 1: Valid Pick-up Point Types

Type	Code	Description
PP	PICKPOINT	An order pickup point with an on-site operator, register, fitting rooms, etc.
Parcel locker	POSTOMAT	An order pickup terminal at a retail location or shopping mall — a parcel locker

Table 2: Address Information Types

Type	Code	Description
Russian Federation State Address Register	gar	An address object using GAR and FIAS identifiers
Coordinate system (latitude, longitude, address)	coord	An address object using coordinates and a free-form address
Free-form address	custom	An address object using a free-form address and clarifying fields

Table 3: Days of the Week

Day of the week	Identifier
Monday	1
Tuesday	2
Wednesday	3
Thursday	4
Friday	5
Saturday	6
Sunday	7

Basic Information​

Request​

Header Parameters​

Request example​

Response​

Response Codes and Messages​

Successful Response Parameters​

Successful response example​

Unsuccessful Response Parameters​

Unsuccessful response example​

Format Tables​

Table 1: Valid Pick-up Point Types​

Table 2: Address Information Types​

Table 3: Days of the Week​