AI агент
Свържете магазина си с AI агент

За разработчици

API за разработчици: платформа, която кодът и AI-ят ви разбират

Admin GraphQL, Storefront API, REST и webhooks. CLI с JSON изход на всяка команда. Dev MCP, с който вашият AI агент чете схемата и проверява заявката, преди да я пусне. Всичко е документирано на cloudcart.dev.

GraphQL и REST · CLI и Dev MCP · Headless витрини

AI Toolkit в GitHub

Три API

Едно API за всяка задача

REST за външни интеграции, Admin GraphQL за админа и агентите, Storefront GraphQL за витрината. Един и същ магазин зад трите.

/api/v2

JSON-API v2 · REST

  • Външни интеграции: ERP, Make, Zapier, скриптове
  • API ключ на магазин
  • JSON:API 1.0, един ресурс на заявка
GET /api/v2/products?filter[sku]=RS-30 X-CloudCart-ApiKey: ••• Accept: application/vnd.api+json
Документация
/api/gql

Admin GraphQL

  • Самоописваща се схема с интроспекция
  • Personal Access Token, одит на всяка мутация
  • Това ползват CLI и AI агентите
POST /api/gql { products(first: 1, sku: "RS-30") { edges { node { id name pricing { from } } } } }
Документация
/api/sf

Storefront GraphQL

  • Headless витрини: Next.js, Nuxt, SvelteKit, Remix, Astro
  • Storefront токен с обхват + клиентски JWT
  • Заявки от браузъра на клиента
POST /api/sf X-Storefront-Access-Token: ••• { product(handle: "serum-s-rozovo-maslo") { title priceRange { minVariantPrice { formatted } } } }
Документация
01Webhooks в реално време при всяка промяна на поръчка, продукт или клиент. Документация →
02Токени: API ключове за интеграциите, Personal Access Tokens за CLI и GraphQL, Storefront токени с обхват за витрините.

AI асистент + Nitrogen

Свързване за минута

Свързвате AI асистента си с CloudCart с едно изречение. После му казвате каква витрина искате, а той я пише с Nitrogen и я пуска на живо през GitHub.

Изречението за AI асистента
Fetch and follow the instructions at https://raw.githubusercontent.com/cloudcart/ai-toolkit/main/prompt.md to set up my AI agent for CloudCart

Асистентът пита на какъв език да работите и Ви отговаря на него.

  1. Отворете AI асистента

    Claude Code, ChatGPT Codex, Cursor, VS Code или Gemini CLI.

  2. Поставете изречението

    Асистентът слага всичко сам.

  3. Дайте ключ за достъп

    Настройки → „PAT токени“ → нов ключ. Готово, пишете.

PAT токенът: ключът на асистента към магазина

Само толкова права, колкото са нужни

При създаването избирате само четене, пълен достъп или отделни права по ресурси. Токенът работи с CloudCart CLI и Admin GraphQL.

Срок и IP адреси

Може да зададете дата, до която токенът важи, и до 20 IP адреса или мрежи, от които се приема.

Под Ваш контрол

Токени създава само собственикът на магазина. Стойността се показва веднъж. Спирате или изтривате токена с едно кликване и достъпът спира веднага.

Официалните инструкции: github.com/cloudcart/ai-toolkit · Nitrogen: cloudcart.dev/docs/nitrogen

AI Toolkit и CLI

Работи с вашия AI агент

$ cloudcart app execute --query 'mutation { productsBulkAdjustPrice(selector: { categoryId: 12 }, change: { op: PERCENT_DELTA, value: 5 }) { jobId queuedCount } }' --json

CloudCart CLI е команден ред за вашия магазин, създаден с мисъл за AI агентите. Вграден е и работи веднага. Всяка команда отговаря с JSON и с ясен изходен код - дали е минала и защо не. Затова скрипт или AI агент я ползва толкова лесно, колкото и инженер.

JSON изходи изходни кодове на всяка команда
Скриптируемот агенти и от CI
Разбиране на изображенияв командния ред

Вижте в GitHub

Създавате нова интеграция

Описвате я и Claude генерира GraphQL операциите, валидира ги и свързва логиката

› „Синхронизирай наличностите от нашия WMS на всеки час“

Пишете и тествате заявки

Claude чете схемата, пише заявката и я проверява през Dev MCP преди изпълнение

› „Кои продукти нямат снимка?“

Чернови на Nitrogen компоненти

Компонент за витрината, върху Storefront API, готов за вашия framework

› „Карта на продукт с избор на разновидност“

Dev MCP дава същото на Claude Code, ChatGPT Codex, Cursor, VS Code и Gemini CLI: четат схемата и проверяват заявката, преди да я пуснат.

Nitrogen - нашата headless технология

Пишете витрината на React Router и Tailwind

Nitrogen е на React Router и Tailwind, със стартер от CloudCart. Storefront API може да ползва и друга рамка, но хостингът на Nova е за Nitrogen. Каталогът, поръчките, плащанията и наличностите остават в CloudCart.

localhost:5173dev

Три версии · изберете една

Вашият езиков моделОпишете промяната…

Началната страница на примерния магазин yourstore.bg. Разработчикът пише на своя езиков модел „Дай ми три есенни версии на началната“ и получава три версии: топли тонове, тъмен банер и цяла снимка. Избраната става началната страница - промяната е в кода на витрината.

API-тата

  • Storefront GraphQL с публичен и частен токен
  • Customer Account API: вход без парола, с 6-цифрен код
  • Досегашната тема и Nitrogen работят едновременно, на различни домейни

Deploy и Nova

  • cloudcart nitrogen deploy от CLI или вашия CI
  • Или GitHub App: deploy при всеки push
  • Nova: Cloudflare Workers, <handle>.cloudcart.dev, само production, env променливи

Какво правите сами

  • robots.txt и sitemap.xml
  • 301 пренасочванията
  • Контактната форма и cookie съгласието

Те не идват автоматично на Nitrogen домейн - приложението ви ги прави. Описано е в документацията.

Nitrogen документация

Лимити и правила

Казани предварително, не след първия 429

Лимитите са публични, за да планирате интеграцията, преди да я напишете.

Заявки в минута, по план

Лимитът е за JSON-API v2 (/api/v2). Всеки отговор носи X-RateLimit-Limit, X-RateLimit-Remaining и Retry-After; при превишаване - 429 с JSON тяло. Всички ключове на магазина делят един бюджет. Лимитът важи за основния домейн на магазина.

Webhooks

Приемникът трябва да отговаря с 2xx и да поема пикове - масова промяна в каталога праща много събития наведнъж. Адрес, който постоянно връща грешка, се изключва автоматично.

Доставката на един webhook чака до 30 секунди.

Таймаути

30 секунди за заявка към JSON-API v2 и към админа. Голямо четене, което не се събира в тях, се пагинира, а не се разширява.

Защитите срещу злоупотреба (ботове, флууд) не се публикуват; клиент, който ги задейства, получава 429 или 403.

Говорете с нашите инженери

Носите задачата, ние показваме кое API я решава и къде е документирано.