Skip to main content

Commerce API: поръчките от магазин на собствена платформа

Сървърът на магазина ви праща поръчките, клиентите, продуктите и връщанията към CDP, за да броят отчетите и това, което браузърът не вижда.

M
Екипът на Monfri
Обновена на ·5 мин четене

Магазин на WooCommerce, Shopify, CloudCart, OpenCart или Magento свързва данните си с няколко клика — вижте Свържете магазина си. Магазин на собствена платформа ги праща от своя сървър, през Commerce API. Тагът на Monfri в магазина продължава да следи посещенията; API-то добавя това, което браузърът не вижда: поръчки, скрити от блокер на реклами, откази, връщания, наложен платеж, който не е платен, историята отпреди тага и каталога.

Ключът

Ползвайте сървърен ключ, който не може нищо друго: в CDP — Configure → Settings → API keys → External API keys → Create external key, с обхват Commerce API (write orders, customers, products). Не давайте на магазин или на неговия разработчик ключ от вид write — той чете и променя и всеки профил в workspace-а. Пращайте ключа в хедъра, никога в адреса:

Authorization: Bearer <вашият сървърен ключ>

Ключът от тага на сайта е публичен и тук не работи. Заявка с ключа в адреса се отказва, преди ключът да бъде прочетен.

Какво се праща

Всички заявки отиват към https://cdp.monfri.net/v1/commerce, с JSON тяло до 1 MB и до 500 записа:

Заявка Тяло
POST /orders { "orders": [ … ] }
POST /customers { "customers": [ … ] }
POST /products { "products": [ … ] }
POST /refunds { "refunds": [ … ] }
POST /events { "events": [ … ] } — събитията за количката и checkout от сървъра
DELETE /products/{id} сваля продукт от продажба
GET /status колко поръчки, клиенти и продукти пази CDP и кога е пристигнал последният от всеки вид

Записът се създава или заменя по своето id, затова повторно пратена поръчка — с нов статус или доставена — заменя записаната. Пращайте целия запис всеки път: поле, което пропуснете, се изчиства, а статус, който пропуснете, се връща към стойността по подразбиране. Отговорът казва колко са приети и изброява неприетите с причината.

Отговори и грешки

Отговорът на POST е { "accepted": 3, "failed": 1, "errors": [ … ] }. Статусът е 200, когато е приет поне един запис — винаги четете failed — и 422, когато не е приет нито един. Поправете неприетите записи и пратете само тях; повторението на заявка е безопасно.

Статус Значение
400 Тялото не е { "orders": [ … ] }, списъкът е празен или ключът е в адреса
401 Няма ключ, или ключът е непознат, отменен или изтекъл
403 Ключът няма обхвата за Commerce API или е ключът от тага
404 DELETE /products/{id}: няма продукт с това id
409 Връзката Own platform (Commerce API) е прекъсната в CDP
413 Над 500 записа или тяло над 1 MB
429 Твърде много заявки — изчакайте секундите от хедъра Retry-After

Поръчка

Полетата: id, total и колкото имате от тези — email, customerId, status (pending, processing, completed, cancelled), financialStatus (pending, paid, partially_refunded, refunded), fulfillmentStatus, currency, shipping, tax, discount, coupons, paymentMethod, shippingMethod, createdAt и items (productId, name, quantity, price).

  • Същият номер на поръчката, който магазинът праща към Google в dataLayer при покупка. CDP пази една поръчка на номер, която и да пристигне първа — от браузъра или от сървъра.
  • Датите — с часовата зона, например 2026-10-29T09:12:00+02:00.
  • Сумите — в евро, или в левове с "currency": "BGN"; левовете се пазят в евро по 1,95583.
  • Наложен платеж е pending, докато парите не пристигнат.
  • Браузърът на купувача (по избор): пратете anonymousId — стойността на бисквитката cdp_anonymous_id в заявката при поръчка. Тя връзва поръчката на гост с браузъра, който е пазарувал и чел.

Продукти и връщания

Продукт: id, name, price и url, imageUrl, brand, categoryPath, stockStatus, compareAtPrice, variants (id, price, sku, attributes), когато ги имате. Вместо да пращате продуктите, можете да дадете на CDP адреса на Google Merchant XML feed в Commerce → Connections → Own platform (Commerce API); чете се при всяка синхронизация.

За да свалите продукт от продажба, извикайте DELETE /products/{id} или го пратете със "status": "archived". Продуктът остава в CDP, защото поръчките сочат към него, и се смята за изчерпан: не се препоръчва и не се рекламира.

Връщане: orderId, amount, type (refund, partial_refund, return, cancellation), reason и собственото id на връщането, когато го имате — без него връщането се разпознава по поръчката, вида, сумата и createdAt. Връщане, пратено повторно, се записва веднъж. Пратете поръчката преди връщането ѝ: връщане за поръчка, която CDP не пази, се отказва.

Колички и checkout

Прегледите на продукт, добавянето и махането от количката и стъпките на checkout идват от тага на Monfri в страниците на магазина: тагът чете събитията, които магазинът вече праща към Google в dataLayer (Enhanced Ecommerce или GA4), затова страниците не искат допълнителен код.

Магазин, който предпочита да ги праща от сървъра си, ползва POST /events. Събитието има type — product_viewed, product_added, product_removed, cart_viewed, checkout_started или checkout_step_completed — продукта (product) или количката (cart), за които е, и кой го е направил: anonymousId (стойността на бисквитката cdp_anonymous_id в заявката на купувача), customerId или email; едно от трите е задължително. Давайте на всяко събитие eventId: същото отново в рамките на 7 дни се записва веднъж. Покупката не е събитие — пратете я като поръчка.

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

Кога се праща

Поръчките — когато станат, и отново при промяна на статуса; историята — веднъж, на пакети до 500, от най-старите; клиентите и продуктите — при промяна или веднъж на ден.

Още от „Онлайн магазинът“

Помощ

Свързване на онлайн магазина

Внесете продуктите, клиентите и поръчките си в Monfri — съветникът за свързване, къде са ключовете на всяка платформа и какво да синхронизирате.

Прочети →
Помощ

Синхронизацията на магазина: колко често, какво и кога се проваля

Колко често идват данните от магазина, какво носи всяка синхронизация, проверките на данните и на самоличността и как се синхронизира отново, спира или свързва пак.

Прочети →
Помощ

Продуктите и категориите от магазина

Разглеждайте каталога на магазина в CDP, филтрирайте по наличност и марка, вижте прегледите, продажбите и конверсията на продукт и дървото с категории.

Прочети →
Помощ

Поръчките от магазина

Всяка поръчка в CDP — филтри по статус и плащане, сумите на поръчката, купувачът и хронологията ѝ и откъде идва всяко число.

Прочети →
Помощ

Клиентите от магазина

Клиентите на магазина ви в CDP — търсене, поръчките, похарчената сума и маркетинговото съгласие и клиентският профил зад всеки.

Прочети →
Помощ

Внос на продукти, поръчки и клиенти от файл

Внесете стари поръчки, клиенти или каталог с продукти в CDP от CSV или XML файл — качване, съпоставяне на колоните, преглед и резултат.

Прочети →

Не намерихте отговор?

Пишете ни и ни кажете какво се опитвахте да направите.