Revised:
1. Какво представлява
REST API на WareRushAI позволява на външни програми да четат данните на дадена компания: продукти, наличности по локации, поръчки, продукти с липсващи данни и грешки при листване в marketplace канали. В тази версия той е само за четене и работи върху същите услуги и проверки на права, както уеб приложението и MCP конекторът. Базовият адрес е https://app.warerushai.com/api/v1. Достъпът до API се пуска поетапно: докато не бъде активиран за платформата, всяко извикване връща 404 и не могат да се създават ключове.
2. Създаване на API ключ
Собственик или администратор отваря Настройки, след това Интеграции, после API ключове, задава име на ключа, избира правата за достъп (catalog.read, inventory.read, orders.read, account.read), срок на валидност и лимит на минута, и го създава. Пълният ключ започва с wra_live_ и се показва само веднъж. WareRushAI съхранява само еднопосочен хеш и първите символи, така че изгубен ключ не може да бъде възстановен: създайте нов. Можете да отмените ключ по всяко време или да го ротирате: новият ключ се показва веднъж, а старият продължава да работи още 24 часа.
3. Удостоверяване
Изпращайте ключа в хедъра Authorization: Authorization: Bearer wra_live_... през HTTPS. Никога не поставяйте ключа в уеб адреса; заявка, която прави това, се отхвърля с грешка key_in_url. Пример: curl -H "Authorization: Bearer $WRA_KEY" "https://app.warerushai.com/api/v1/products?limit=20". Приемат се и OAuth 2.1 токени за достъп от MCP конектора, със съответните права, одобрени от потребителя.
4. Крайни точки (Endpoints)
GET /me (ключът, неговите лимити и днешното потребление), GET /products (търсене и списък, с query, limit, cursor), GET /products/{id}, GET /locations, GET /inventory (редове с наличности, с пагинация), GET /inventory/summary, GET /orders (с updated_since, status, source, limit, cursor), GET /missing-data и GET /marketplace-errors (с channel). Всяка крайна точка изисква съответното право: catalog.read за продукти, липсващи данни и грешки от marketplace, inventory.read за локации и наличности, orders.read за поръчки. Поддържа се само методът GET; други методи връщат 405.
5. Пагинация и периодични проверки (polling)
Списъците връщат data, next_cursor и has_more, с максимум 50 елемента на страница (limit от 1 до 50, по подразбиране 20). Предайте обратно next_cursor като cursor, за да получите следващата страница. За polling тригери в Zapier, Make и n8n извиквайте GET /orders?updated_since=2026-11-15T08:00:00Z и запазвайте времето на последната успешна проверка: получавате поръчките, създадени или променени оттогава насам, подредени от най-новите към най-старите.
6. Лимити и грешки
Всеки ключ има ограничение за заявки в минута (по подразбиране 60, максимум 600) и опционален дневен лимит. Всяка компания разполага и с дневен лимит според плана си: по подразбиране 1 000 извиквания за Starter, 10 000 за Business и 100 000 за Pro. При достигане на лимит API връща 429 с хедър Retry-After. Хедърите X-RateLimit-Limit, X-RateLimit-Remaining, X-Daily-Limit и X-Daily-Remaining показват оставащия брой. Грешките винаги имат структурата {"error":{"code","message","request_id"}}; посочвайте request_id, когато се свързвате с поддръжката. Често срещани кодове: invalid_api_key (401), insufficient_scope (403), not_found (404), invalid_parameter (400), rate_limited и daily_quota_exceeded (429).
7. OpenAPI описание
Машинночетимото описание по OpenAPI 3.1 се намира на https://app.warerushai.com/api/v1/openapi.json и не изисква ключ. Импортирайте го в Postman, Zapier, Make, n8n или AI асистент, за да заредите всички крайни точки, параметри и структури на отговорите. Промените се правят без нарушаване на съществуващите полета; версията е /api/v1.
8. Сигурност
Ключовете принадлежат точно на една компания и се валидират при всяко извикване; даден ключ никога не може да чете данни на друга компания и спира да работи, ако администраторът, който го е създал, напусне компанията. Ключовете никога не се записват в логове или съобщения за грешки, а дневникът на извикванията показва само пътя, статуса и часа. Финансови данни като покупни цени не се предоставят чрез това API.
