Удостоверяване в API

Всяка заявка изисква твоя API ключ (започва с efc_). Генерираш го от приложението: „Cont → Setări → API“ (Акаунт → Настройки → раздел API). Пази го като парола.

Базов URL

https://eficio.ro/api/v2

Хедър за удостоверяване

Изпращай ключа като Authorization: Bearer или, алтернативно, като X-Api-Key.

curl https://eficio.ro/api/v2/account \
  -H "Authorization: Bearer efc_cheia_ta"

Контекстът на фирмата се определя автоматично от ключа — не е нужно да изпращаш „company_id“. Виждаш само данните на своята фирма.

Конвенции

Всички отговори са в JSON (UTF-8). Единичен резултат идва в обвивката { "data": … }, а списък идва с { "data": […], "meta": … }. Изпращай телата на POST/PATCH заявките като JSON с хедъра Content-Type: application/json.

Единичен отговор

{
  "data": { "id": 12, "name": "Tricou bumbac organic", "price": 99.90 }
}

Странициране

Списъците приемат per_page (1–100, по подразбиране 50) и page. Обектът meta ти показва къде се намираш.

GET https://eficio.ro/api/v2/products?per_page=20&page=2

{
  "data": [ … ],
  "meta": { "current_page": 2, "per_page": 20, "total": 134, "last_page": 7 }
}

Грешки

При грешка получаваш съответния HTTP код и обвивка { "error": …, "message": … }. Полето error е стабилен код за програмна обработка, а message е текст за хората.

{ "error": "validation_error", "message": "Trimite cel puțin un câmp de actualizat." }

HTTP код	error	Кога
401	missing_token	Липсва хедърът с ключа.
401	invalid_token	Невалиден или отменен ключ.
403	no_user	Фирмата няма свързан потребител.
404	not_found	Ресурсът не съществува.
422	validation_error	Невалидни данни в тялото на заявката.

Акаунт & статистика

GET /account

Профилът на фирмата ти: име, ЕИК, адрес, план и статус на абонамента.

GET /stats

Бърза статистика: продукти, поръчки по статус, клиенти и стойността на поръчките.

Продукти

GET /products

Списък на каталога по страници.

Параметри

Поле	Тип		Описание
search	string	по избор	Търси в името, SKU, EAN, MPN.
status	string	по избор	Филтър: active \| draft \| archived.
updated_after	date	по избор	Само продукти, променени след тази дата (ISO 8601).
per_page	int	по избор	Елементи на страница, 1–100 (по подразбиране 50).
page	int	по избор	Номерът на страницата.

POST /products

Създава продукт. „name“ е единственото задължително поле; SKU и slug се генерират автоматично, ако липсват.

Параметри

Поле	Тип		Описание
name	string	задълж.	Наименованието на продукта (макс. 191).
type	string	по избор	simple \| variable (по подразбиране simple).
status	string	по избор	active \| draft \| archived (по подразбиране draft).
sku	string	по избор	Вътрешен код, уникален във фирмата.
ean	string	по избор	EAN баркод.
mpn	string	по избор	Код на производителя.
brand_id	int	по избор	Марката (трябва да съществува във фирмата).
category_id	int	по избор	Категорията (трябва да съществува във фирмата).
price	number	по избор	Продажна цена.
sale_price	number	по избор	Намалена цена.
cost_price	number	по избор	Доставна цена.
vat_rate	int	по избор	Ставка на ДДС, 0–100.
stock_quantity	int	по избор	Начална наличност.
track_stock	bool	по избор	Следи наличността.
highlights	array	по избор	Списък с булет точки (низове).
short_description	string	по избор	Кратко описание.
long_description	string	по избор	Подробно описание.
weight_grams	int	по избор	Тегло (г) — плюс length_mm, width_mm, height_mm.
meta_title	string	по избор	SEO — плюс meta_description.

Пример за тяло

{
  "name": "Tricou bumbac organic",
  "sku": "TRI-BMB-01",
  "price": 99.90,
  "vat_rate": 21,
  "stock_quantity": 50,
  "status": "active"
}

GET /products/{id}

Един продукт с всички свързани данни (марка, категория, варианти, изображения, етикети).

PATCH /products/{id}

Обновява полетата на продукта (всяко от горните, без „type“). Минимум едно поле.

PATCH /products/{id}/price

Обновява само цените. Изпрати поне едно поле.

Параметри

Поле	Тип		Описание
price	number	по избор	Продажна цена.
sale_price	number	по избор	Намалена цена.
cost_price	number	по избор	Доставна цена.
vat_rate	int	по избор	Ставка на ДДС, 0–100.

PATCH /products/prices/bulk

Обновява цени масово, по id ИЛИ sku. Отговор: {updated, not_found}.

Пример за тяло

{
  "items": [
    { "id": 12, "price": 89.90 },
    { "sku": "TRI-BMB-01", "sale_price": 79.90 }
  ]
}

PATCH /products/{id}/stock

Задава абсолютна наличност („quantity“) или прилага относителна корекция („delta“).

Параметри

Поле	Тип		Описание
quantity	int	по избор	Задава наличността на тази стойност (≥0).
delta	int	по избор	Относителна корекция (може да е отрицателна).
variant_id	int	по избор	За конкретен вариант на продукта.

Пример за тяло

{ "delta": -3 }

PATCH /products/stock/bulk

Масова промяна на наличности. Всеки елемент: id|sku, по избор variant_id|variant_sku, плюс quantity или delta.

Пример за тяло

{
  "items": [
    { "sku": "TRI-BMB-01", "quantity": 40 },
    { "id": 18, "delta": 5 }
  ]
}

GET /products/stock/list

Списък с наличностите на всички продукти (филтър search, странициране).

Поръчки

GET /orders

Списък с поръчки по страници (странициране per_page/page, филтър search/status).

POST /orders

Създава поръчка. Клиентът: съществуващ „customer_id“ ИЛИ обект „customer“ (създава се по имейл). Минимум един ред в „items“.

Параметри

Поле	Тип		Описание
customer_id	int	по избор	Съществуващ клиент на фирмата.
customer	object	по избор	Нов клиент: name (задълж.), email, phone, company_name, cui, reg_com.
items	array	задълж.	Редовете на поръчката (виж по-долу).
items[].product_id	int	по избор	Продуктът — задължително, ако липсва „sku“.
items[].sku	string	по избор	Алтернатива на product_id.
items[].quantity	int	задълж.	Количество (≥1).
items[].variant_id	int	по избор	Задължително, ако продуктът има варианти.
items[].unit_price	number	по избор	Единична цена (по подразбиране от продукта/варианта).
items[].tax_rate	number	по избор	Ставка на ДДС за реда, 0–100.
status	string	по избор	new \| confirmed \| processing \| shipped \| cancelled \| returned.
payment_status	string	по избор	unpaid \| paid \| partial \| refunded.
currency	string	по избор	ISO код от 3 букви.
shipping_total	number	по избор	Цена на доставката.
discount_total	number	по избор	Обща отстъпка.
source_order_id	string	по избор	ID на поръчката във външната ти система.

Пример за тяло

{
  "customer": { "name": "Ion Popescu", "email": "ion@exemplu.ro", "phone": "0712345678" },
  "payment_status": "paid",
  "items": [
    { "sku": "TRI-BMB-01", "quantity": 2, "unit_price": 99.90 }
  ]
}

GET /orders/{id}

Една поръчка с редовете, общите суми, клиента, товарителницата и фактурата.

PATCH /orders/{id}

Обновява поръчката. Промяната на „status“ минава през вътрешния поток (история + известия). Минимум едно поле.

Параметри

Поле	Тип		Описание
status	string	по избор	Преход на статуса (виж стойностите по-горе).
payment_status	string	по избор	Статус на плащането.
payment_method	string	по избор	Метод на плащане.
shipping_method	string	по избор	Начин на доставка.
note	string	по избор	Бележка към промяната на статуса (макс. 500).
notes	string	по избор	Бележките към поръчката.
labels	array	по избор	Етикети (низове, макс. 60).

Пример за тяло

{ "status": "confirmed", "note": "Confirmată telefonic" }

POST /orders/{id}/awb

Генерира товарителница за поръчката. Идемпотентна заявка — ако вече има товарителница, я връща. Ако нямаш свързан куриер, се издава локална тестова товарителница.

Параметри

Поле	Тип		Описание
courier	string	по избор	fan \| sameday \| cargus \| dpd \| gls \| dragonstar \| urgent \| posta \| other (по подразбиране fan).
weight	number	по избор	Тегло на колета (кг).
parcels	int	по избор	Брой колети (≥1).
cod_amount	number	по избор	Наложен платеж (по подразбиране: 0, ако поръчката е платена, иначе общата сума).

Пример за тяло

{ "courier": "sameday", "weight": 1.2, "parcels": 1 }

POST /orders/{id}/invoice

Издава фактурата на поръчката. Без тяло на заявката. Идемпотентна заявка — ако фактурата вече съществува, я връща (статус 200).

Клиенти

GET /customers

Списък с клиенти по страници (филтър search).

GET /customers/{id}

Един клиент с пълните данни.

PATCH /customers/{id}

Обновява данните на клиента.

Параметри

Поле	Тип		Описание
name	string	по избор	Име (ако е изпратено, не може да е празно).
email	string	по избор	Имейл.
phone	string	по избор	Телефон.
company_name	string	по избор	Наименование на фирмата.
cui	string	по избор	ЕИК (CUI).
reg_com	string	по избор	Номер в търговския регистър.
notes	string	по избор	Бележки (макс. 2000).

Етикети

GET /tags

Списък с етикети (филтър search).

POST /tags

Създава етикет.

Параметри

Поле	Тип		Описание
name	string	задълж.	Наименование (макс. 60).
color	string	по избор	Цвят (hex или име, макс. 32).

PUT /tags/{id}

Преименува / сменя цвета на етикета.

DELETE /tags/{id}

Изтрива етикета.

POST /tags/{id}/attach

Прикрепя етикета към продукти.

Параметри

Поле	Тип		Описание
product_ids	array	задълж.	Списък с идентификатори на продукти.

Пример за тяло

{ "product_ids": [12, 18, 25] }

POST /tags/{id}/detach

Премахва етикета от продукти (същото тяло като при attach).

Категории

GET /categories

Дървото на категориите в каталога.

GET /categories/{id}

Една категория.

Връщания

GET /returns

Списък със заявки за връщане.

GET /returns/{id}

Една заявка за връщане с нейните редове.

Оферти в маркетплейси

GET /offers

Списък с оферти в маркетплейсите.

GET /offers/{id}

Една оферта.

Канали & връзки

GET /marketplaces/list

Свързаните маркетплейси (без данните за достъп).

GET /couriers

Настроените куриери.

GET /billing-software

Свързаните програми за фактуриране.

GET /websites/list

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

GET /fulfillments/list

Достъпните складове / fulfillment центрове.

Справочни данни

GET /general/currencies

Списъкът с валути.

GET /general/languages

Списъкът с езици.

GET /general/countries

Списъкът с държави.

API eficio

Удостоверяване в API

Конвенции

Странициране

Грешки

Акаунт & статистика

Продукти

Поръчки

Клиенти

Етикети

Категории

Връщания

Оферти в маркетплейси

Канали & връзки

Справочни данни

Бисквитките на eficio.ro