Приложения
Приложение — доступ одной системы к одному магазину: его scopes, точки, с которыми оно работает, и, если заданы, адреса, с которых оно может обращаться. Приложения создаются в «Настройки → API и вебхуки» тем, у кого есть право управлять API, — по умолчанию владельцем, — и никто не может дать приложению больше, чем есть у него самого.
Приложение действует в магазине как отдельный участник. Заказы, которые оно создаёт, и остатки, которые меняет, подписаны его именем, и магазин видит в истории, что сделала интеграция.
API входит в тариф. Если магазин перейдёт на тариф без него, запросы получают 403 integration_api_not_in_plan, пока магазин не вернётся; приложения и токены остаются как были.
Scopes
Scope открывает ресурс на чтение или на запись: catalog:read, orders:write. Scope записи включает scope чтения своего ресурса. Таблица scopes показывает, какие методы открывает каждый.
Два scope добавляют поля в ответы другого ресурса: costs:read — себестоимость в варианты каталога и позиции заказов, customers:read — контакты, адрес и комментарий покупателя в заказы и получателя в фискальные документы. Без scope этих полей в ответе нет вовсе, а не пусто.
Запрос без scope своего метода получает 403 insufficient_scope. Ответ называет недостающий scope, и магазин добавляет его приложению:
curl "https://api.saleya.app/v1/orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:read"
{
"type": "insufficient_scope",
"title": "Scope is missing",
"status": 403,
"detail": "This request needs the orders:read scope. The store owner grants it in the app access settings.",
"required_scope": "orders:read",
"accepted_scopes": [
"orders:read"
]
}Токены
- Токен начинается с
saleya_at_. Его последние шесть символов — контрольная сумма: токен с опечаткой отклоняется до поиска, а сканеры секретов узнают утёкший. - Магазин хранит только хеш токена и его первые символы, поэтому токен показывается один раз — при выпуске.
- Срок действия — по желанию. Владелец магазина получает письмо до того, как токен истечёт.
- У приложения не больше 2 текущих токенов: один в работе и один на замену.
Чтобы сменить токен, выпустите новый на замену старому и выберите, сколько старый ещё проработает. Разверните новый в этот срок. Отзыв действует со следующего запроса; удаление приложения отзывает все его токены.
type у 401 | Что значит |
|---|---|
api_token_missing | Нет заголовка Authorization: Bearer. |
api_token_invalid | Неверный формат или контрольная сумма, или такого токена нет. |
api_token_expired | Срок действия истёк. |
api_token_revoked | Токен отозван, приложение удалено или магазин закрыт. |
Безопасность токенов
- Храните токен на своём сервере. Токен в браузере, мобильном приложении или репозитории — утёкший токен.
- Ограничьте приложение адресами своих серверов: запрос с любого другого адреса получит 403
ip_not_allowed. - Владелец магазина получает письмо, когда токен выпущен или отозван и когда меняется доступ приложения.
- Журнал запросов приложения в панели хранит каждый запрос 30 дней: метод, путь, статус и
typeотказа, без тел. - Если токен утёк, отзовите его сразу: отзыв не ждёт замены.