---
title: 40. Boxnow
description: "BoxNow е куриерска услуга за доставка до автоматични пощенски станции (APM) и шкафчета. В Изпрати.БГ интеграцията `BoxNow` свързва системата с BoxNow Partner API чрез OAuth2 и позволява: - създаване и проследяване на пратки; - генериране на етикети (PDF/ZPL); - зареждане на офиси/точки за получаване…"
url: "https://izprati.bg/docs/boxnow/"
updated: "2026-07-27"
category: Куриери
---

# 40. Boxnow

BoxNow е куриерска услуга за доставка до автоматични пощенски станции (APM) и шкафчета. В Изпрати.БГ интеграцията `BoxNow` свързва системата с BoxNow Partner API чрез OAuth2 и позволява:

- създаване и проследяване на пратки;
- генериране на етикети (PDF/ZPL);
- зареждане на офиси/точки за получаване (service points);
- калкулация на цена по теглови диапазони;
- автоматично обновяване на точките (cron: всеки ден в 21:00).

## Предварителни изисквания

1. Договор с BoxNow и достъп до партньорския портал.
2. OAuth2 идентификационни данни от BoxNow:
   - Client ID
   - Client Secret
     Те са различни от потребителско име/парола за уеб портала.

## Стъпка 1: Създаване на интеграция BoxNow

Отворете Куриери → Конфигурирай и изберете BoxNow. Настройките са в две групи: Authentication и General Options.

## Стъпка 2: Удостоверяване (Authentication)

| Поле | Описание |
| --- | --- |
| Client ID | OAuth2 Client ID от BoxNow |
| Client Secret | OAuth2 Client Secret от BoxNow |

Без валидни credentials API заявките ще връщат грешки за автентикация (кодове X403 и др.).

> За тестване може да използвате stage сървъра; за реални пратки — production.

## Стъпка 3: Общи настройки (General Options)

### API URL

| Стойност | Употреба |
| --- | --- |
| Production (по подразбиране) | `https://api-production.boxnow.bg` — за реални пратки |
| Stage | `https://api-stage.boxnow.bg` — за тестове |

Ако полето е празно, системата използва production.

### Default Origin Location (начална локация)

Избира се от падащо меню (зарежда се от BoxNow API: `apps/boxnow/origins`).

- Това е складът/локацията на подател, от която излизат пратките.
- По подразбиране може да е „Any APM“ (`any-apm`), ако не изберете конкретна локация.
- За стабилна работа препоръчително е да изберете конкретен склад, договорен с BoxNow.

### Restrict Returns (ограничаване на връщания)

- Изключено (по подразбиране) — връщанията са разрешени.
- Включено — връщанията са забранени за пратките от тази интеграция.

### Default Compartment Size (размер на отделение)

Използва се, когато размерите на мястото (place) в пратката липсват:

| Код | Размер | Максимални размери |
| --- | --- | --- |
| 1 | Small | до 300×300×300 mm |
| 2 | Medium (по подразбиране) | до 450×450×450 mm |
| 3 | Large | до 600×600×600 mm |

### Pricing Ranges (ценови диапазони)

JSON масив с цени според тегло в грамове:

> ```
> [
>
> {"from": 0, "to": 3000, "price": 3},
>
> {"from": 3001, "to": 6000, "price": 6},
>
> {"from": 6001, "to": 10000, "price": 8},
>
> {"from": 10001, "to": 20000, "price": 10}
>
> ]
> ```

- `from` — минимално тегло (вкл.)
- `to` — максимално тегло (вкл.); ако липсва — без горна граница
- `price` — цена за диапазона (може да е `0` за безплатна доставка)

Ако не конфигурирате диапазони, се ползват вградените стойности по подразбиране (3 / 6 / 8 / 10 за съответните тегла до 20 kg).

## Стъпка 5: Тарифи и точки за получаване

### Тарифа

Интеграцията зарежда тарифа:

- Име: Boxnow Default rate
- Тип: самообслужване / service point (`TYPE_SELF_SERVICE_POINT`)
- Външен ID: `88`

### Точки за получаване (APM/шкафчета)

- Точките се синхронизират от BoxNow API.
- Автоматично: всеки ден в 21:00 (cron `update-service-points`).
- При нужда стартирайте ръчно зареждане от администрацията на куриерските услуги (ако е налично във вашата инсталация).

Клиентът при поръчка трябва да избере BoxNow точка (service point) — без нея пратката не може да се експортира.

## Стъпка 6: Изисквания при създаване на пратка

При експорт към BoxNow заявката трябва да има:

| Поле | Задължително |
| --- | --- |
| Име на получател | Да |
| Телефон на получател | Да |
| Имейл на получател | Препоръчително |
| Service point (BoxNow локация) | Да |
| Поне едно място (place) с артикули | Да |
| Липсващ tracking номер | Да (нова пратка) |

### Ограничения

- Максимално тегло: 20 000 g (20 kg)
- Максимален обем: 600×600×600 mm (216 000 000 mm³)
- При превишаване калкулаторът/експортът връща съобщение за грешка.

### Наложен платеж и плащане

- Поръчка платена → режим Prepaid (без НП).
- Поръчка неплатена → режим COD (наложен платеж).

Сумата за събиране включва стойността на поръчката и при нужда цената на доставката (според настройките на подателя/услугата).

## Стъпка 7: Етикети и проследяване

След успешен експорт:

1. BoxNow връща ID на пратка и tracking номер.
2. От OrderAdmin можете да отпечатате етикет (PDF или ZPL) чрез услугата за етикети на интеграцията.
3. Статусите се обновяват според API и конфигурираните задачи за проследяване.

При повторен опит, ако пратката вече е създадена в BoxNow, но в Изпрати.БГ липсва tracking, системата може да възстанови данните от запазения `exportResult` без нова заявка към API.

## Стъпка 8: Тестване преди production

1. Задайте API URL = Stage.
2. Въведете test Client ID / Secret от BoxNow.
3. Създайте тестова пратка с малко тегло и валидна тестова точка.
4. Проверете: калкулация → експорт → етикет → tracking.
5. Сменете на Production и production credentials преди реални поръчки.

## Често срещани проблеми

| Проблем | Възможна причина | Решение |
| --- | --- | --- |
| Грешка при автентикация | Грешни Client ID/Secret | Проверете credentials в BoxNow портала |
| „Shipment service point is missing“ | Няма избрана BoxNow точка | Изберете service point при поръчката |
| „No available rates found“ | Липсва връзка/тарифа | Проверете connection и заредете тарифи |
| „Order is too heavy“ | Над 20 kg | Разделете пратката или изберете друга услуга |
| Празен списък с origin locations | Невалидни credentials или липсва интеграция | Запазете auth и презаредете формата |
| Грешна цена при калкулация | Невалиден JSON в Pricing Ranges | Поправете JSON формата |