REST API v1.0

API Документация

Интегрирайте Европът в вашата система и автоматизирайте вашите пратки

Начало Автентикация Калкулация Пратки Проследяване Офиси Webhooks Грешки

Начало

Base URL

https://api.evropat.bg/v1/

Формат на заявките

Всички заявки използват Content-Type: application/json
Отговорите са винаги в JSON формат
Датите са в ISO 8601 формат: YYYY-MM-DDTHH:mm:ssZ
Цените са в EUR (евро) с 2 знака след десетичната запетая

Автентикация

Всички заявки към API-то изискват API ключ, който се предава чрез Authorization header:

Authorization: Bearer YOUR_API_KEY

Важно: Получаване на API ключ

За да получите API ключ, трябва да имате сключен договор с Европът. Свържете се с нас на [email protected] или на телефон 0700 10 717.

Калкулиране на цена

POST /shipments/calculate

Параметри на заявката

Параметър	Тип	Задължителен	Описание
from_city	string	Да	Град на подател
to_city	string	Да	Град на получател
weight	float	Да	Тегло в килограми
delivery_type	string	Да	"office" \| "address"
cod_amount	float	Не	Сума за наложен платеж (EUR)
declared_value	float	Не	Обявена стойност (EUR)

Пример

curl -X POST https://api.evropat.bg/v1/shipments/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_city": "София",
    "to_city": "Пловдив",
    "weight": 2.5,
    "delivery_type": "office",
    "cod_amount": 50.00
  }'

Отговор

{
  "success": true,
  "data": {
    "price": 4.29,
    "price_with_vat": 5.15,
    "price_with_fuel": 6.68,
    "fuel_surcharge": 1.53,
    "cod_fee": 1.00,
    "insurance_fee": 0,
    "currency": "EUR",
    "zone": "G",
    "estimated_delivery": "2026-01-27"
  }
}

Създаване на пратка

POST /shipments/create

Параметри на заявката

Параметър	Тип	Описание
sender	object	Данни на подател (name, phone, city, address)
recipient	object	Данни на получател (name, phone, city, address)
packages	array	Масив от пакети (weight, length, width, height)
delivery_type	string	"office" \| "address"
office_id	integer	ID на офис (при доставка до офис)
cod_amount	float	Наложен платеж (EUR)
description	string	Описание на съдържанието

Отговор

{
  "success": true,
  "data": {
    "tracking_number": "EP1234567890",
    "waybill_url": "https://api.evropat.bg/waybills/EP1234567890.pdf",
    "label_url": "https://api.evropat.bg/labels/EP1234567890.pdf",
    "price": 6.68,
    "currency": "EUR",
    "estimated_delivery": "2026-01-27"
  }
}

Проследяване на пратка

GET /shipments/{`{tracking_number}`}

Пример

curl -X GET https://api.evropat.bg/v1/shipments/EP1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Отговор

{
  "success": true,
  "data": {
    "tracking_number": "EP1234567890",
    "status": "in_transit",
    "status_label": "В движение",
    "sender": {
      "city": "София"
    },
    "recipient": {
      "city": "Пловдив"
    },
    "history": [
      {
        "date": "2026-01-25T10:30:00Z",
        "status": "Приета в офис София Център",
        "location": "София"
      },
      {
        "date": "2026-01-25T18:00:00Z",
        "status": "Изпратена към дестинация",
        "location": "София"
      }
    ]
  }
}

Офиси

GET /offices

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

GET /cities

Връща списък с обслужвани населени места с информация за зона и график на обслужване.

Webhooks

Можете да регистрирате webhook URL, на който ще получавате известия при промяна на статуса на пратките.

Събития

shipment.created

Създадена нова пратка

shipment.picked_up

Пратката е взета

shipment.in_transit

Пратката е в движение

shipment.delivered

Пратката е доставена

shipment.returned

Пратката е върната

cod.transferred

Преведен наложен платеж

Кодове за грешки

HTTP код	Описание
200	Успешна заявка
400	Невалидни параметри на заявката
401	Невалиден или липсващ API ключ
403	Забранен достъп до ресурса
404	Ресурсът не е намерен
429	Превишен лимит на заявки (rate limiting)
500	Вътрешна сървърна грешка