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

Версия: v1. Всички endpoints изискват API ключ и работят с JSON.

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

  • Header: X-API-Key: your_api_key
  • Без валиден ключ: 401 Unauthorized
  • Ключът се валидира спрямо потребителски профил в системата.

Как да получите API ключ (в момента)

  • Регистрирайте акаунт в платформата.
  • След регистрация влезте в профила си.
  • Генерирайте API ключ от секцията за API достъп.

След генериране на ключа можете да го използвате веднага за вашите интеграции.

Rate Limit

  • 60 заявки/минута на API ключ
  • 1000 заявки/час на API ключ
  • При превишаване: 429 Too Many Requests

1) Проверка на телефон (single)

POST/api/v1/phone-check

Body:

{
  "phone_number": "0890123456"
}

cURL:

curl -X POST "https://nepostop.com/api/v1/phone-check" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"phone_number":"0888000002"}'

Примерен отговор:

{
  "phone_number": "0888000002",
  "found": true,
  "stats": {
    "total": 3,
    "delivered": 2,
    "undelivered": 1,
    "delivered_percentage": 67,
    "undelivered_percentage": 33
  }
}

2) Проверка на телефони (bulk)

POST/api/v1/phone-check/bulk

Body:

{
  "phone_numbers": [
    "0888000001",
    "0888000004",
    "0879555505"
  ]
}

cURL:

curl -X POST "https://nepostop.com/api/v1/phone-check/bulk" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"phone_numbers":["0888000001","0888000004","0879555505"]}'

3) Добавяне на пратка (single)

POST/api/v1/shipments

Body:

{
  "phone_number": "0888111002",
  "shipping_number": "SHP-123456"
}

cURL:

curl -X POST "https://nepostop.com/api/v1/shipments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"phone_number":"0888111002","shipping_number":"SHP-123456"}'

Ако подадеш demo телефон за shipments, endpoint-ът връща успешен отговор, но не записва ред в базата.

4) Добавяне на пратки (bulk)

POST/api/v1/shipments/bulk

Body:

{
  "shipments": [
    {
      "phone_number": "0888111001",
      "shipping_number": "SHP-1001"
    },
    {
      "phone_number": "0888111004",
      "shipping_number": "SHP-1002"
    }
  ]
}

cURL:

curl -X POST "https://nepostop.com/api/v1/shipments/bulk" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"shipments":[{"phone_number":"0888111001","shipping_number":"SHP-1001"},{"phone_number":"0888111004","shipping_number":"SHP-1002"}]}'

При добавяне на пратка през API статусът винаги се записва като Изчакване. Не е необходимо да подаваш поле status.

Валидации

  • Телефон: само валиден български мобилен номер (08XXXXXXXX, 3598XXXXXXXX, +3598XXXXXXXX).
  • Bulk phone-check: максимум 100 номера в заявка.
  • Bulk shipments: максимум 200 пратки в заявка.

Тестови dummy номера

  • 0888000001 → 3 успешни доставки
  • 0888000002 → 2 успешни, 1 непотърсена
  • 0888000003 → 1 успешна, 2 непотърсени
  • 0888000004 → 2 непотърсени
  • 0888000005 → 1 успешна, 1 непотърсена

Тези номера са предназначени за тестове на интеграции и връщат фиксирани резултати през /api/v1/phone-check и /api/v1/phone-check/bulk.

Тестови dummy номера за добавяне на пратки

  • 0888111001
  • 0888111002
  • 0888111003
  • 0888111004
  • 0888111005

Ако използваш тези номера в /api/v1/shipments или /api/v1/shipments/bulk, API-то ще върне успешен и реалистичен response, но няма да записва данни в базата.

Обратно към началната страница