Автентифікація та ліміти
API-ключі, scopes, rate limit за планом, заголовки X-RateLimit, формат помилок problem+json і таблиця кодів.
API-ключі
Усі ендпоінти /v1/* і /mcp потребують ключа в заголовку:
Authorization: Bearer rv_live_...- Ключ створює власник компанії в Desk: Налаштування → API-ключі. Покроково: швидкий старт.
- Ключ прив'язаний до вашої компанії (тенанта) і діє лише в її межах. Дані інших компаній через нього недоступні.
- Ключ показується один раз. У базі зберігається лише
sha256ключа та префікс. У логах API видно тільки префіксrv_live_XXXX, самого ключа немає ніколи. - Ключ можна обмежити строком дії й відкликати в будь-який момент: доступ припиняється негайно.
- Не вбудовуйте ключ у код браузера публічного сайту й не комітьте його в репозиторій. Тримайте його в змінних середовища сервера.
Scopes (права)
Ключ має набір прав. Ендпоінт без потрібного права відповідає 403 insufficient_scope.
| Scope | Що дозволяє |
|---|---|
read:pricing | POST /v1/landed-cost, GET /v1/market-price, GET /v1/rules/{country}, GET /v1/fx; MCP: calculate_landed_cost, estimate_market_price, get_customs_rules |
read:listings | GET /v1/vin/{vin}, GET /v1/listings/search; MCP: decode_vin, search_listings |
mcp | доступ до POST /mcp. Додатково потрібне право самого інструмента |
write:deals | зарезервовано під майбутні ендпоінти створення й оновлення угод і контактів У розробці |
Для MCP-клієнта створюйте ключ з правами mcp, read:pricing, read:listings: інструменти, на які в ключа немає права, у списку tools/list просто не показуються.
Ліміти запитів
Ліміт рахується на ключ за хвилину і залежить від плану вашої компанії:
| План | Запитів за хвилину |
|---|---|
| trial | 30 |
| starter | 60 |
| pro | 300 |
| business | 1200 |
Кожна відповідь містить заголовки:
| Заголовок | Значення |
|---|---|
X-RateLimit-Limit | запитів у вікні для плану вашого ключа |
X-RateLimit-Remaining | скільки лишилось |
X-RateLimit-Reset | час у unix-секундах, коли вікно звільниться |
X-Request-Id | ідентифікатор запиту, він же request_id у тілі помилки. Називайте його, коли пишете в підтримку |
Коли ліміт вичерпано, API відповідає 429 rate_limited із заголовком Retry-After (секунди). Зачекайте цей час і повторіть запит. SDK уміє робити це сам.
Порядок перевірок: 401, потім 429, потім 403. Якщо Redis, на якому тримається лічильник, недоступний, API відповідає 503 (fail-closed), а не пропускає запити без обліку.
Місячні квоти
Окремі місячні квоти планів API (Free 100 / Dev 10 000 / Business 100 000 викликів) поки лише рахуються, але не застосовуються. Щоб перевірити їх узгодженість із тарифами білінгу, потрібне рішення власника Чекає на власника. Доступ до API за тарифами ImportOS: див. таблицю в розділі Для брокерів.
Формат помилок: problem+json
Усі помилки мають тип application/problem+json (RFC 9457):
{
"type": "https://importos.app/problems/insufficient_scope",
"title": "Forbidden",
"status": 403,
"detail": "The API key does not have the required scope: read:pricing",
"instance": "/v1/landed-cost",
"code": "insufficient_scope",
"request_id": "..."
}Поле type — це адреса <API_PROBLEM_BASE_URL>/<code>; на сервері рекомендовано виставити API_PROBLEM_BASE_URL=https://docs.<домен>/problems, тоді така адреса веде на цю таблицю кодів.
Орієнтуйтесь на code: він стабільний, на відміну від detail. Для помилок валідації додається errors[] із path і message для кожного поля, для 429 ще й retry_after.
code | HTTP | Коли |
|---|---|---|
validation_error | 400 | Некоректні параметри чи тіло запиту (errors[] показує які саме) |
unauthorized | 401 | Ключа немає, він невалідний, відкликаний або прострочений |
insufficient_scope | 403 | У ключа немає потрібного scope |
origin_not_allowed | 403 | Браузерний Origin поза списком дозволених (захист /mcp) |
not_found | 404 | Немає такого ресурсу |
unsupported_country | 404 | Для цієї країни немає правил |
method_not_allowed | 405 | Метод не підтримується (GET і DELETE на /mcp) |
unprocessable_input | 422 | Запит коректний, але порахувати неможливо (наприклад немає правил на цю дату) |
rate_limited | 429 | Перевищено ліміт, див. Retry-After |
internal_error | 500 | Внутрішня помилка |
upstream_unavailable | 502 | Зовнішній провайдер (курси, декодер VIN) недоступний |
auth_unavailable | 503 | Не вдалося перевірити ключ |
rate_limiter_unavailable | 503 | Лічильник лімітів недоступний |
Код 5xx і 429 варто повторювати з експоненційною затримкою. Помилки 4xx (крім 429) повторювати без змін сенсу немає.
CORS і браузер
CORS дозволено лише для адрес зі списку API_CORS_ORIGINS (порожній список вимикає CORS). Для /mcp браузерний Origin поза списком отримує 403: це захист від DNS rebinding. Звертайтесь до API з вашого сервера, а не з браузера користувача: так ключ не потрапить до клієнта.
Швидкий старт: API-ключ, REST і MCP
Від API-ключа до першого запиту GET /v1/landed-cost і виклику calculate_landed_cost із Claude Desktop.
MCP: Claude Desktop, ChatGPT, Cursor
Віддалений MCP-сервер ImportOS Data: інструменти, підключення до Claude Desktop, Cursor, Claude Code і ChatGPT, перевірка curl.