Commerce API: поръчките от магазин на собствена платформа
Сървърът на магазина ви праща поръчките, клиентите, продуктите и връщанията към CDP, за да броят отчетите и това, което браузърът не вижда.
Магазин на 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, от най-старите; клиентите и продуктите — при промяна или веднъж на ден.