Open API

Импорт на поръчки в Agility

Използвайте store-scoped API ключ. За директно влизане в таблото ползвайте POST /orders/import. За приемане към нашата система (Google Sheets) — POST /orders/system.

Свали .mdВход

Base URL

https://www.agility.bg/api/v1

Endpoint

POST /orders/importPOST /orders/system

Limit

500 orders/request

Общ преглед

Как работи

1. Създавате ключ

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

2. Изпращате поръчки

Външната система прави POST с масив `orders` (до 500).

3. Поръчките са в Agility

С `/orders/import` поръчките минават през pipeline-а и влизат в таблото веднага. С `/orders/system` се записват в Sheets за последващ sync.

Бърз старт

  1. 1От таблото отворете Настройки → Синхронизиране на поръчки.
  2. 2Запазете секрета. Показва се само при създаване.
  3. 3Изпратете поръчки към POST /orders/import с Bearer token за директен импорт.

Authentication

API ключ

Всяка заявка трябва да съдържа store-scoped ключ в `Authorization` header. Отменени или невалидни ключове връщат `401`.

HTTP header
Authorization: Bearer agl_live_ВАШИЯТ_КЛЮЧ

Endpoint

POST /orders/import

Директно в Agility

Директен импорт в Agility: валидация, мачване на адреси/офиси и запис в магазина. Това е endpoint-ът за външен софтуер, който трябва да пълни таблото веднага.

MethodPOSTURLhttps://www.agility.bg/api/v1/orders/importBody{ orders: [...] }

Endpoint

POST /orders/system

Към системата (Sheets)

Приема поръчки към нашата система (Google Sheets tab за магазина). Потребителят после синхронизира и импортира от таблото. Подходящ, когато искате междинен буфер.

MethodPOSTURLhttps://www.agility.bg/api/v1/orders/systemBody{ orders: [...] }

Reference

Payload fields

Същият `orders` масив работи и за двата endpoint-а. Полетата по-долу са Shopify-съвместими; приемат се и snake_case alias-и (`order_code`, `customer_phone`, …).

Namerequired

Unique order number. Rows with the same value are grouped as one order.

Email

Customer email. Stored when available.

Financial Status

Payment state. `paid` marks prepaid; `pending`/`unpaid` are treated as unpaid unless payment method says COD.

Paid at

Payment timestamp. Compatibility field; usually optional.

Fulfillment Status

Compatibility field. Our system controls import status.

Fulfilled at

Compatibility fulfillment timestamp.

Accepts Marketing

Compatibility customer marketing flag.

Currency

Currency code, for example `EUR` or `BGN`.

Subtotal

Product subtotal. Used as fallback with `Shipping` and `Taxes` when `Total` is missing.

Shipping

Shipping amount charged to the customer.

Taxes

Tax amount. Used only for fallback total calculation.

Totalrequired

Final order total and COD base for COD orders.

Discount Code

Discount code stored with the order.

Discount Amount

Discount amount stored with the order.

Shipping Methodrequired

Delivery method text, for example `Speedy to_address` or `Econt to_office`.

Created at

Order creation date/time in ISO 8601 format.

Lineitem quantity

Quantity for this line item.

Lineitem namerequired

Product name used in item display and shipment notes.

Lineitem price

Product unit price.

Lineitem compare at price

Fallback item price when `Lineitem price` is missing.

Lineitem sku

Product SKU.

Lineitem requires shipping

Compatibility line item flag.

Lineitem taxable

Compatibility line item tax flag.

Lineitem fulfillment status

Compatibility line item fulfillment state.

Billing Name

Fallback customer name if `Shipping Name` is missing.

Billing Street

Fallback address if shipping address is missing.

Billing Address1

Fallback address line.

Billing Address2

Compatibility billing address line 2.

Billing Company

Compatibility billing company.

Billing City

Fallback city if `Shipping City` is missing.

Billing Zip

Fallback postal code if `Shipping Zip` is missing.

Billing Province

Compatibility billing region.

Billing Country

Stored on the order for multi-country routing (fallback: `Shipping Country`).

Billing Phone

Fallback phone if `Shipping Phone` is missing.

Shipping Namerequired

Customer full name for delivery and waybill creation.

Shipping Street

Fallback/alternative shipping address text.

Shipping Address1required

Main delivery address text.

Shipping Address2

Extra shipping address details.

Shipping Company

Compatibility shipping company.

Shipping Cityrequired

Delivery city used for courier city validation.

Shipping Zip

Postal code. Strongly recommended for courier city matching.

Shipping Province

Compatibility shipping region.

Shipping Country

Fallback country when `Billing Country` is empty.

Shipping Phonerequired

Delivery phone used for search, history, and waybills.

Notes

Customer note and optional pickup-office metadata from some integrations.

Note Attributes

Extra metadata or item properties, used in shipment notes where possible.

Cancelled at

Compatibility cancellation timestamp.

Payment Methodrequired

Use `Cash on Delivery (COD)` for COD orders; otherwise send the prepaid provider/name.

Payment Reference

Compatibility external payment reference.

Refunded Amount

Compatibility refunded amount.

Vendor

Compatibility vendor field.

Outstanding Balance

Compatibility outstanding balance.

Employee

Compatibility POS employee field.

Location

Compatibility Shopify location/POS field.

Device ID

Compatibility POS device field.

Id

External/Shopify id. `Name` is still used as display order code.

Tags

Scanned for risk/report markers and customer verification display.

Risk Level

Compatibility Shopify risk level.

Source

Source channel, useful for debugging.

Lineitem discount

Compatibility per-line discount.

Phone

Fallback phone field.

Courierrequired

API-specific courier column. Allowed values: `Speedy`, `Econt`.

Example

Примерна заявка (директен импорт)

curl — /orders/import
curl -s -X POST   -H "Authorization: Bearer agl_live_KEY"   -H "Content-Type: application/json"   -d '{
    "orders": [
      {
        "Name": "#25001",
        "Created at": "2026-05-18T09:36:39.285Z",
        "Shipping Name": "Ivan Petrov",
        "Email": "ivan@example.com",
        "Shipping Phone": "0888123456",
        "Total": 49.90,
        "Shipping": 0,
        "Lineitem quantity": 1,
        "Lineitem name": "Product A",
        "Lineitem price": 49.90,
        "Shipping Method": "Speedy to_address",
        "Shipping Address1": "bul. Bulgaria 1",
        "Shipping City": "Sofia",
        "Shipping Zip": "1000",
        "Billing Country": "BG",
        "Courier": "Speedy",
        "Financial Status": "pending",
        "Payment Method": "Cash on Delivery (COD)",
        "Note Attributes": ""
      }
    ]
  }'   https://www.agility.bg/api/v1/orders/import

Пример — към системата (Sheets)

curl — /orders/system
curl -s -X POST   -H "Authorization: Bearer agl_live_KEY"   -H "Content-Type: application/json"   -d '{
    "orders": [
      {
        "Name": "#25001",
        "Created at": "2026-05-18T09:36:39.285Z",
        "Shipping Name": "Ivan Petrov",
        "Email": "ivan@example.com",
        "Shipping Phone": "0888123456",
        "Total": 49.90,
        "Shipping": 0,
        "Lineitem quantity": 1,
        "Lineitem name": "Product A",
        "Lineitem price": 49.90,
        "Shipping Method": "Speedy to_address",
        "Shipping Address1": "bul. Bulgaria 1",
        "Shipping City": "Sofia",
        "Shipping Zip": "1000",
        "Billing Country": "BG",
        "Courier": "Speedy",
        "Financial Status": "pending",
        "Payment Method": "Cash on Delivery (COD)",
        "Note Attributes": ""
      }
    ]
  }'   https://www.agility.bg/api/v1/orders/system

Responses

Отговори

200 — /orders/import

json
{
  "ok": true,
  "imported": 1,
  "skippedExisting": 0,
  "totalReadyForImport": 1
}

200 — /orders/system

json
{
  "ok": true,
  "system": {
    "accepted": 1,
    "parseErrors": []
  }
}

4xx / 5xx

Невалиден ключ, липсващ `orders` масив, над 500 поръчки или невалидни данни.

Security

Сигурност

  • Използвайте само HTTPS в production.
  • Всеки ключ е ограничен до един магазин.
  • При съмнение отменете ключа и създайте нов.