Адреса покупателей
Адресная книга покупателя: добавить, изменить, сделать основным, удалить.
Адреса покупателей
Объекты
CustomerAddress
idintegerобязательноID адреса.
customer_idintegerобязательноID покупателя, которому принадлежит адрес.
labelstring или nullобязательноНазвание адреса, например «Дом» или «Работа»; null, если не задано.
streetstringобязательноУлица.
housestring или nullобязательноНомер дома.
apartmentstring или nullобязательноКвартира или офис.
floorstring или nullобязательноЭтаж.
entrancestring или nullобязательноПодъезд.
districtstring или nullобязательноРайон.
postal_codestring или nullобязательноПочтовый индекс.
commentstring или nullобязательноКомментарий для курьера, например как пройти; null, если не задан.
locationobject или nullобязательноТочка адреса на карте; null, если адрес перенесён из другой системы и ещё не уточнён.
Поля · 2
latnumberобязательноШирота в градусах.
lngnumberобязательноДолгота в градусах.
is_defaultbooleanобязательноОсновной адрес покупателя. Когда основной адрес удаляют, основным становится самый свежий.
created_atstring (date-time)обязательноКогда запись создана.
updated_atstring (date-time)обязательноКогда запись менялась последний раз.
Методы
Адрес из книги покупателя
get/customers/{customer}/addresses/{address}
Scope: customers:read
Параметры
Путь
customerintegerобязательноID покупателя.
addressintegerобязательноID адреса в адресной книге покупателя.
Ответы
200Успешно
Заголовки
ETagstringобязательноВерсия записи. Передайте её в If-Match, чтобы изменить запись.
- Пример:
"7"
application/json
Возвращает CustomerAddress
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Изменить адрес покупателя
patch/customers/{customer}/addresses/{address}
Scope: customers:write
Параметры
Путь
customerintegerобязательноID покупателя.
addressintegerобязательноID адреса в адресной книге покупателя.
Заголовок
Idempotency-KeystringУникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.
- Мин. длина:
- 1
- Макс. длина:
- 255
- Пример:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringобязательноETag записи из последнего чтения, например "7". Правка применится, только если запись с тех пор никто не менял, иначе 412. Без заголовка — 428.
- Пример:
"7"
Тело запроса application/json
labelstring или nullНазвание адреса, например «Дом» или «Работа»; null, если не задано.
- Макс. длина:
- 64
streetstringУлица.
- Макс. длина:
- 255
housestring или nullНомер дома.
- Макс. длина:
- 32
apartmentstring или nullКвартира или офис.
- Макс. длина:
- 32
floorstring или nullЭтаж.
- Макс. длина:
- 16
entrancestring или nullПодъезд.
- Макс. длина:
- 16
districtstring или nullРайон.
- Макс. длина:
- 64
postal_codestring или nullПочтовый индекс.
- Макс. длина:
- 16
commentstring или nullКомментарий для курьера, например как пройти; null, если не задан.
- Макс. длина:
- 500
locationobjectТочка адреса на карте; null, если адрес перенесён из другой системы и ещё не уточнён.
Поля · 2
latnumberШирота в градусах.
- Минимум:
- -90
- Максимум:
- 90
lngnumberДолгота в градусах.
- Минимум:
- -180
- Максимум:
- 180
is_defaultbooleanОсновной адрес покупателя. Когда основной адрес удаляют, основным становится самый свежий.
Ответы
200Успешно
Заголовки
Idempotent-Replayedstringtrue, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.
- Значения:
true
ETagstringобязательноВерсия записи. Передайте её в If-Match, чтобы изменить запись.
- Пример:
"7"
application/json
Возвращает CustomerAddress
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает ConflictProblem
412Запись изменилась после чтения: версия в If-Match не текущая
application/problem+json
Возвращает Problem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
428Запросу нужен If-Match с ETag записи
application/problem+json
Возвращает Problem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Отказы метода
- 409
idempotency_key_in_useЗапрос с этим ключом ещё исполняется - 412
precondition_failedЗапись изменилась - 422
idempotency_key_reusedКлюч идемпотентности уже использован - 422
invalid_idempotency_keyКлюч идемпотентности неверен - 428
precondition_requiredНужен If-Match
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl -X PATCH "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true
}{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Удалить адрес из книги покупателя
delete/customers/{customer}/addresses/{address}
Scope: customers:write
Параметры
Путь
customerintegerобязательноID покупателя.
addressintegerобязательноID адреса в адресной книге покупателя.
Заголовок
Idempotency-KeystringУникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.
- Мин. длина:
- 1
- Макс. длина:
- 255
- Пример:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringобязательноETag записи из последнего чтения, например "7". Правка применится, только если запись с тех пор никто не менял, иначе 412. Без заголовка — 428.
- Пример:
"7"
Ответы
204Успешно
Заголовки
Idempotent-Replayedstringtrue, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.
- Значения:
true
Без тела
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает ConflictProblem
412Запись изменилась после чтения: версия в If-Match не текущая
application/problem+json
Возвращает Problem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
428Запросу нужен If-Match с ETag записи
application/problem+json
Возвращает Problem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Отказы метода
- 409
idempotency_key_in_useЗапрос с этим ключом ещё исполняется - 409
in_use_conflictЗапись используется - 412
precondition_failedЗапись изменилась - 422
idempotency_key_reusedКлюч идемпотентности уже использован - 422
invalid_idempotency_keyКлюч идемпотентности неверен - 428
precondition_requiredНужен If-Match
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl -X DELETE "https://api.saleya.app/v1/customers/{customer}/addresses/{address}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Добавить адрес в книгу покупателя
post/customers/{customer}/addresses
Scope: customers:write
Параметры
Путь
customerintegerобязательноID покупателя.
Заголовок
Idempotency-KeystringУникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.
- Мин. длина:
- 1
- Макс. длина:
- 255
- Пример:
8e03978e-40d5-43e8-bc93-6894a57f9324
Тело запроса application/json
labelstring или nullНазвание адреса, например «Дом» или «Работа»; null, если не задано.
- Макс. длина:
- 64
streetstringобязательноУлица.
- Макс. длина:
- 255
housestring или nullНомер дома.
- Макс. длина:
- 32
apartmentstring или nullКвартира или офис.
- Макс. длина:
- 32
floorstring или nullЭтаж.
- Макс. длина:
- 16
entrancestring или nullПодъезд.
- Макс. длина:
- 16
districtstring или nullРайон.
- Макс. длина:
- 64
postal_codestring или nullПочтовый индекс.
- Макс. длина:
- 16
commentstring или nullКомментарий для курьера, например как пройти; null, если не задан.
- Макс. длина:
- 500
locationobjectобязательноТочка адреса на карте; null, если адрес перенесён из другой системы и ещё не уточнён.
Поля · 2
latnumberобязательноШирота в градусах.
- Минимум:
- -90
- Максимум:
- 90
lngnumberобязательноДолгота в градусах.
- Минимум:
- -180
- Максимум:
- 180
is_defaultbooleanОсновной адрес покупателя. Когда основной адрес удаляют, основным становится самый свежий.
Ответы
201Создано
Заголовки
Idempotent-Replayedstringtrue, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.
- Значения:
true
ETagstringобязательноВерсия записи. Передайте её в If-Match, чтобы изменить запись.
- Пример:
"7"
Locationstring (uri)обязательноАдрес созданной записи, а у принятого к исполнению (202) — адрес, где следить за исходом.
application/json
Возвращает CustomerAddress
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает ConflictProblem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Отказы метода
- 409
address_book_fullАдресная книга покупателя полна - 409
idempotency_key_in_useЗапрос с этим ключом ещё исполняется - 422
idempotency_key_reusedКлюч идемпотентности уже использован - 422
invalid_idempotency_keyКлюч идемпотентности неверен
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl -X POST "https://api.saleya.app/v1/customers/{customer}/addresses" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true
}{
"id": 0,
"customer_id": 0,
"label": "string",
"street": "string",
"house": "string",
"apartment": "string",
"floor": "string",
"entrance": "string",
"district": "string",
"postal_code": "string",
"comment": "string",
"location": {
"lat": 0,
"lng": 0
},
"is_default": true,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}