# API за разработчици: GraphQL, REST, CLI и MCP | CloudCart

Admin GraphQL, Storefront API, REST и webhooks, CLI с JSON изход и Dev MCP за AI агенти. Лимитите са публични, документацията е на cloudcart.dev.

Източник: https://cloudcart.com/developers · CloudCart

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

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

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

[Създайте магазин за €1](https://my.cloudcart.com/bg/register)
[Портал за разработчици](https://cloudcart.dev/)

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

[AI Toolkit в GitHub](https://github.com/cloudcart/ai-toolkit)

Три 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
200 OK · 41 ms
[Документация](https://cloudcart.dev/docs/rest-api)

/api/gql

### Admin GraphQL

- Самоописваща се схема с интроспекция
- Personal Access Token, одит на всяка мутация
- Това ползват CLI и AI агентите

POST /api/gql
{ products(first: 1, sku: "RS-30") { edges { node { id name pricing { from } } } } }
200 OK · 38 ms
[Документация](https://cloudcart.dev/docs/admin-api)

/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 } } } }
200 OK · 23 ms
[Документация](https://cloudcart.dev/docs/storefront-api)

01Webhooks в реално време при всяка промяна на поръчка, продукт или клиент. [Документация →](https://cloudcart.dev/docs/webhooks)
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Асистентът пита на какъв език да работите и Ви отговаря на него.

### Отворете AI асистента
Claude Code, ChatGPT Codex, Cursor, VS Code или Gemini CLI.

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

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

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

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

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

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

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

AI Toolkit и CLI

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

Вашият AI агентClaude · Cursor …

Обнови цените на всички серуми с +5 %
Намира операцията в схематаsemantic_search → productsBulkAdjustPrice
Намира категорията „Серуми“cloudcart app execute → categoryId 12
Проверява я, преди да я пуснеvalidate_graphql_codeblocks → ✓ SUCCESS
Пуска я през CloudCart CLIcloudcart app execute → exit 0
Чака магазина да приключиbulkOperationStatus → COMPLETED · 12
Готово: 12 продукта в „Серуми“ са с 5 % по-високи цени.

CloudCart CLIapp execute
productsBulkAdjustPricecategoryId: 12PERCENT_DELTA · 5--json

exit 0 · queuedCount 12

Админ · Продукти

Продукти › Серум с розово масло

Серум с розово масло

Детайли

ИмеСерум с розово масло
Категория Серуми
SKURS-30
Цена42,00 €42,00 €+5 %

$ 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](https://github.com/cloudcart/ai-toolkit)

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

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

› „Синхронизирай наличностите от нашия WMS на всеки час“› „Синхронизирай наличностите от нашия 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

Нова колекция Есенна колекция

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

РазгледайКъм серумите

ПродуктиВиж всички

Серум с хиалурон38,00 €
Нощен серум54,00 €
Комплект серум и крем68,00 €
Серум с розово масло42,00 €

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

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

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

### API-тата

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

### Deploy и Nova

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

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

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

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

[Nitrogen документация](https://cloudcart.dev/docs/nitrogen)

Ресурси

## Директните линкове

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

[Admin GraphQL cloudcart.dev/docs/admin-api](https://cloudcart.dev/docs/admin-api)
[Storefront API cloudcart.dev/docs/storefront-api](https://cloudcart.dev/docs/storefront-api)
[REST API cloudcart.dev/docs/rest-api](https://cloudcart.dev/docs/rest-api)
[REST справочник developers.cloudcart.com/2.0/overview](https://developers.cloudcart.com/2.0/overview)
[Webhooks cloudcart.dev/docs/webhooks](https://cloudcart.dev/docs/webhooks)
[Nitrogen cloudcart.dev/docs/nitrogen](https://cloudcart.dev/docs/nitrogen)

[cloudcart.dev · портал cloudcart.dev](https://cloudcart.dev/)

инструменти

[CLI cloudcart.dev/docs/cli](https://cloudcart.dev/docs/cli)
[AI Toolkit · GitHub github.com/cloudcart/ai-toolkit](https://github.com/cloudcart/ai-toolkit)
[Postman postman.com/cloudcartapi/cloudcart-public](https://www.postman.com/cloudcartapi/cloudcart-public/collection/rb83ao3/cloudcart-api)
[GPT асистент за API-то chatgpt.com/g/…official-cloudcart-api](https://chatgpt.com/g/g-67d8113d687081918f764e71c844d13b-official-cloudcart-api)
помощ и партньори

[Помощен център help.cloudcart.com](https://help.cloudcart.com/bg/support/home)
[Партньори /partners](https://cloudcart.com/partners)

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

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

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

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

X-RateLimit-Limit: 100X-RateLimit-Remaining: 100429 · Retry-After: 60
Лимитът е за 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.

[### Партньори Агенции и специалисти печелят с CloudCart като експерт, афилиейт или риселър Отворете →](https://cloudcart.com/partners)
[### CloudCart Pay Плащания с карта, без договор с банка Отворете →](https://cloudcart.com/cloudcart-pay)
[### AURA AI служителят: пише описания и SEO, превежда, предлага кампании Отворете →](https://cloudcart.com/aura)

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

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

[Говорете с консултант на CloudCart](https://cloudcart.com/contact)
