Как да свържеш магазин на собствена платформа с eficio чрез Custom API

Защо да използваш Custom API

Ако магазинът ти е собствена разработка, не ти трябва плъгин: магазинът извиква директно endpoint-ите на eficio. Третира се по същия начин като магазин, свързан чрез модул: поръчките му влизат в eficio, а статусът на поръчката може да се връща автоматично в магазина.

• новите или обновените поръчки влизат в модула „Поръчки“;
• продуктите, категориите и марките на магазина могат да се изпращат в eficio;
• eficio уведомява магазина на callback URL, когато се промени поръчка, дошла от него.

Какво да подготвиш предварително

• разработчик, който може да прави HTTP заявки от магазина (POST с JSON);
• сигурно място в магазина, където се пази постоянният ключ, получен от eficio;
• по избор, публичен адрес в магазина, който може да получава известията от eficio (callback).

Стъпка 1 — Отвори страницата Custom API

В лявото меню отваряш „Integrări“ (Интеграции), в „Canale de vânzare“ (Канали за продажба) избираш „Magazine“ (Магазини) и натискаш „Conectează“ (Свържи) на картата Custom API. Страницата съдържа стъпките за свързване, списъка с endpoint-ите (кликваш върху адреса, за да го копираш) и бутона „Documentație API“ (API документация) с всички полета, примери на cURL и PHP и кодовете за грешки.

Стъпка 2 — Генерирай токена за свързване

Натискаш „Generează token“ (Генерирай токен) и потвърждаваш. Магазинът се появява в списъка със състояние „Așteaptă plugin“ (Чака плъгин), а токенът се показва отдолу; виждаш го отново с „Vezi token“ (Виж токена). Токенът е за еднократна употреба.

Стъпка 3 — Handshake: токенът става постоянен ключ

1. Магазинът изпраща POST /connect с токена и адреса на магазина.
2. Получава обратно постоянен api_token, който запазва.
3. При всички останали извиквания изпраща хедъра Authorization: Bearer <api_token> (или X-Eficio-Token).

След handshake магазинът преминава в „Conectat“ (Свързан).

Стъпка 4 — Изпрати поръчките и продуктите

Endpoint-ите са под /api/integrations/custom-api:

• POST /heartbeat: сигнал, че магазинът е онлайн; страницата препоръчва по едно извикване на всеки 15 минути;
• POST /orders: нова поръчка или обновяване на съществуваща;
• POST /products: продуктите на магазина, до 200 на извикване;
• POST /taxonomies: категориите и марките на магазина.

Стъпка 5 — Callback и какво взима eficio от магазина

С „Setează URL de callback“ (Задай callback URL) избираш магазина и адреса, на който eficio изпраща POST с хедъра X-Eficio-Token (ключът на магазина) и JSON тяло във формата {event, data}. Оставяш полето празно, ако предпочиташ магазинът сам да прави заявки към eficio.

От менюто на реда „Ce preia din magazin“ (Какво се взима от магазина) ти дава три опции, които се прилагат при всяко изпращане на каталога: „Preia prețurile de pe site“ (Взимай цените от сайта), „Preia stocul de pe site“ (Взимай наличността от сайта) – след това наличността продължава към каналите – и „Scoate produsele dezactivate pe site“ (Премахвай продуктите, деактивирани в сайта). Опциите могат да се изберат след първото изпращане на продукти.

Какво се случва, след като запазиш

• поръчките, изпратени към /orders, се появяват в модула „Поръчки“ и се обработват като всички останали;
• когато статусът на поръчка, дошла от магазина, се промени, eficio изпраща на callback адреса събитието order.status_changed с данните на поръчката;
• всяко изпращане към callback адреса се записва в дневника на магазина, който виждаш с „Loguri“ (Логове);
• за операции на ниво целия акаунт (продукти, наличности, фактури, товарителници) има и API на eficio v2, с ключове efc_…; публичната документация е на /api-docs.

Чести проблеми

• магазинът остава в „Așteaptă plugin“: извикването на /connect не е успяло или е използван друг токен; провери токена с „Vezi token“;
• извикванията получават отказ след свързването: липсва хедърът с api_token или връзката с магазина е прекъсната, или магазинът е изтрит;
• разкрил си ключа: „Regenerează token“ (Генерирай нов токен) анулира текущия токен, а магазинът трябва да повтори handshake;
• „Magazinul n-a trimis încă produse“ (Магазинът все още не е изпратил продукти) в „Ce preia din magazin“: първо изпрати каталога през /products.

Какво следва

• свържи куриер, например FAN Courier, за да стига статусът на доставката до поръчката;
• свържи програмата за фактуриране, например SmartBill;
• изпращай поръчките и към други системи с действието webhook от автоматичните потоци.

Често задавани въпроси