Швидкий старт: API-ключ, REST і MCP

Створіть API-ключCopy Anchor Link

1. Увійдіть у Desk і відкрийте Налаштування → API-ключі.
2. Назва: quickstart. Права: read:pricing і mcp (для пошуку оголошень і VIN додайте read:listings).
3. Натисніть «Створити ключ» і скопіюйте його одразу: ключ виглядає як rv_live_… і показується один раз.

Збережіть ключ у змінній середовища, а не в коді:

export IMPORTOS_API_KEY="rv_live_..."
export IMPORTOS_API="https://api.importos.app"   # локально: http://127.0.0.1:4114

$env:IMPORTOS_API_KEY = "rv_live_..."
$env:IMPORTOS_API = "https://api.importos.app"

Перший запит: POST /v1/landed-costCopy Anchor Link

Порахуємо Toyota Camry 2018 (2.5 л, бензин) з Copart, майданчик Trenton (NJ), ставка $8000, доставка в Київ, наша комісія $700:

curl -s "$IMPORTOS_API/v1/landed-cost" \
  -H "Authorization: Bearer $IMPORTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lot_price": 8000,
    "auction": "copart",
    "vehicle": { "vin": "4T1B11HK5JU000001", "year": 2018, "fuel": "petrol", "engine_cc": 2487, "damage": "FRONT END" },
    "from": { "auction_yard": "NJ - TRENTON" },
    "to": { "country": "UA", "city": "Київ" },
    "fee_model": { "model": "fixed", "amount": 700, "currency": "USD" },
    "date": "2026-10-17"
  }'

Відповідь містить items[] (кожна стаття має kind, amount, currency, explanation, formula, source, verified), total, total_range, warnings[], assumptions[], rulesVersion, fx[] і confidence. Не забудьте показувати warnings користувачам: ставки з verified: false орієнтовні.

Звертайте увагу на заголовки відповіді X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset і X-Request-Id. Усі поля запиту: POST /v1/landed-cost.

Якщо ви отримали помилку, подивіться поле code у відповіді application/problem+json: unauthorized (немає або неправильний ключ), insufficient_scope (ключу бракує read:pricing), validation_error (тіло запиту), rate_limited (зачекайте Retry-After секунд). Таблиця кодів: Автентифікація та ліміти.

Підключіть MCP до Claude DesktopCopy Anchor Link

1. У Claude Desktop відкрийте Settings → Developer → Edit Config. Файл: %APPDATA%\Claude\claude_desktop_config.json (Windows) або ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
2. Додайте сервер (підставте свій ключ):

{
  "mcpServers": {
    "importos": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.importos.app/mcp",
        "--header",
        "Authorization:${IMPORTOS_AUTH}"
      ],
      "env": { "IMPORTOS_AUTH": "Bearer rv_live_YOUR_KEY" }
    }
  }
}

Форма Authorization:${...} (без пробілу після двокрапки, значення в env) обходить відому помилку лапок Windows з пробілами в args.

3. Повністю закрийте Claude Desktop (через трей, а не лише вікно) і запустіть знову.
4. Запитайте: «Скільки коштуватиме в Україні Toyota Camry 2018 2.5 з Copart NJ, ставка $8000?» Claude викличе інструмент calculate_landed_cost і поверне розбивку.

Інструмент приймає інші назви полів, ніж REST: lot_price_usd, destination_country, our_fee_usd, us_state. Приклад входу:

{
  "lot_price_usd": 8000,
  "auction": "copart",
  "vehicle": {
    "year": 2018,
    "fuel": "petrol",
    "engine_cc": 2487,
    "vin": "4T1B11HK5JU000001",
    "damage": "FRONT END"
  },
  "us_state": "NJ",
  "destination_country": "UA",
  "destination_city": "Kyiv",
  "our_fee_usd": 700,
  "target_currency": "USD"
}

Усі інструменти, інші клієнти (Cursor, Claude Code, ChatGPT) та перевірка через curl: MCP.