Адреса покупателей

Адресная книга покупателя: добавить, изменить, сделать основным, удалить.

Загружаем поисковый индекс…

Адреса покупателей

Объекты

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"
Пример ответа · 200
{
  "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-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же 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

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
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
Тело запроса — 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
}
Пример ответа · 200
{
  "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-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же 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

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
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-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же 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

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
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
Тело запроса — 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
}
Пример ответа · 201
{
  "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"
}