M
    Mapiok
    ВойтиРегистрация
    Документация API

    Туториал по Tools API

    Узнайте, как использовать единый Tools API для парсинга данных, генерации изображений с помощью AI и извлечения информации.

    Справочник OpenAPI (Scalar)
    Amazon Scraper
    Извлекайте данные о товарах, цены и отзывы с Amazon
    AI Generator
    Генерируйте изображения из текста с помощью AI-моделей Flux и Stable Diffusion
    Все инструменты
    Просматривайте полный каталог доступных инструментов и интеграций

    Начало работы

    1

    Получите API ключ

    Войдите в аккаунт и создайте API ключ на странице API ключей. Храните ключ в безопасности и никогда не раскрывайте его в клиентском коде.

    Совет по безопасности: Всегда храните API ключ в переменных окружения. Никогда не добавляйте его в систему контроля версий.

    2

    Выберите инструмент

    Откройте Каталог инструментов чтобы найти подходящий инструмент. У каждого инструмента есть уникальный slug используемый в API эндпоинте.

    amazon-scraper
    instagram-scraper
    ai-generator
    wildberries-scraper
    + ещё
    3

    Выполняйте API запросы

    Все инструменты работают по одной схеме: отправьте задание, затем опрашивайте статус или получите результат через webhook. Выберите язык ниже, чтобы увидеть примеры.

    Схема работы API

    1. Отправить задание
    POST /tools/{slug}/execute
    2. Получить Job ID
    Возвращается немедленно
    3. Опросить статус
    GET /tools/jobs/{jobId}
    4. Получить результат
    Когда status = success

    Бесплатный тариф

    Начните разработку бесплатно — без банковской карты.

    50 приветственных кредитов

    Новые аккаунты получают 50 кредитов при регистрации для знакомства со всеми инструментами.

    3 бесплатных запуска в день

    Запускайте любой инструмент до 3 раз в день даже при нулевом балансе кредитов.

    Нужно больше? Купите пакет кредитов для неограниченного доступа.

    Примеры кода

    1. Отправить задание

    curl -X POST "https://api.example.com/api/v1/tools/amazon-scraper/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "searchQuery": "wireless headphones",
    "maxResults": 5
  }
}'

    2. Проверить статус

    curl -X GET "https://api.example.com/api/v1/tools/jobs/{jobId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

    3. Опрашивать до завершения (bash)

    # Replace {jobId} with the actual job ID from step 1
JOB_ID="your-job-id-here"
API_KEY="YOUR_API_KEY"

while true; do
  RESPONSE=$(curl -s "https://api.example.com/api/v1/tools/jobs/$JOB_ID" \
    -H "Authorization: Bearer $API_KEY")

  STATUS=$(echo $RESPONSE | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "Status: $STATUS"

  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESPONSE" | python3 -m json.tool
    break
  fi

  sleep 2
done

    Доставка через вебхуки

    Вместо опроса вы можете получать результаты через webhook. Передайте необязательный webhookUrl при запуске инструмента, и Mapiok отправит POST-запрос с результатом на ваш URL после завершения задания.

    Запуск с вебхуком

    curl -X POST "https://api.example.com/api/v1/tools/amazon-scraper/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "searchQuery": "wireless headphones",
    "maxResults": 5
  },
  "webhookUrl": "https://your-server.com/webhooks/mapiok"
}'

    Содержимое вебхука

    {
  "event": "job.completed",
  "jobId": "abc123xyz",
  "toolSlug": "amazon-scraper",
  "status": "success",
  "result": { "items": [{ "title": "...", "price": 29.99, "rating": 4.5 }] },
  "creditsCharged": 2,
  "error": null,
  "errorCode": null,
  "timestamp": "2026-02-14T12:00:00.000Z"
}

    Проверка подписи

    Каждый webhook содержит заголовок X-Mapiok-Signature (HMAC-SHA256). Проверьте его с помощью секрета подписи вебхука из страницы API ключей.

    import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  return signatureHeader.length === expected.length &&
    timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

// Express.js handler
app.post('/webhooks/mapiok', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-mapiok-signature'];
  if (!verifySignature(req.body, signature, process.env.MAPIOK_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  console.log(payload.event, payload.jobId, payload.result || payload.error);
  res.status(200).send('OK');
});

    Политика повторных попыток: Если ваш эндпоинт недоступен или возвращает статус, отличный от 2xx, Mapiok повторит попытку до 3 раз с экспоненциальной задержкой (5 с, 30 с, 120 с). URL вебхука должен использовать HTTPS. Ваш эндпоинт должен отвечать в течение 10 секунд.

    Примеры ответов

    Ответ при создании задания
    {
  "data": {
    "jobId": "abc123xyz",
    "status": "pending",
    "estimatedCredits": 1,
    "contractState": "healthy",
    "contractVersion": 3
  }
}
    Ответ при завершении задания
    {
  "data": {
    "status": "success",
    "creditsUsed": 1,
    "processingTime": 3200,
    "result": {
      "items": [
        {
          "title": "Wireless Headphones",
          "price": 29.99,
          "rating": 4.5
        }
      ]
    }
  }
}
    Ответ при ошибке задания
    {
  "data": {
    "status": "failed",
    "error": "Target URL returned 403 Forbidden",
    "errorCode": "provider_error",
    "creditsUsed": 0
  }
}
    Ответ с ошибкой (например, 402)
    {
  "error": "Insufficient credits",
  "details": {
    "required": 1,
    "available": 0
  }
}

    Лучшие практики

    Рекомендуется
    • • Используйте вебхуки вместо опроса для серверных сценариев
    • • Проверяйте подписи вебхуков перед обработкой
    • • Используйте экспоненциальные задержки при опросе
    • • Корректно обрабатывайте ошибки превышения лимита (429)
    • • Храните API ключи в переменных окружения
    • • Проверяйте баланс кредитов перед массовыми операциями
    Не рекомендуется
    • • Раскрывать API ключи в клиентском коде
    • • Слишком часто опрашивать API (соблюдайте лимиты запросов)
    • • Игнорировать ответы с ошибками
    • • Хардкодить API ключи в исходном коде
    • • Выполнять синхронные блокирующие вызовы

    Готовы начать?