> For the complete documentation index, see [llms.txt](https://docs.esimpay.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.esimpay.net/api/zakazy.md).
# Заказы
Полный жизненный цикл заказа и статус подключения.
Создание, пополнение, активация, возврат и отслеживание заказов eSIM.
## Активировать пакет ON\_DEMAND
> \
> Активирует пакет данных, купленный с \`activationMode=ON\_DEMAND\`. \
> Требуются заголовки \`CF-MERCHANT-ID\` и \`CF-ACCESS-SIGN\`.\
> \
> \---\
> \
> \*\*Требования:\*\*\
> \- У пакета \`activationMode\` должен быть \`ON\_DEMAND\`\
> \- Пакет ещё не должен быть активирован (\`activatedAt = null\`)\
> \
> \---\
> \
> \*\*Подпись:\*\* получите через \`POST /customer/sign\`, скопируйте \`signature\` в заголовок \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/activate":{"post":{"operationId":"activate_order","summary":"Активировать пакет ON_DEMAND","description":"\nАктивирует пакет данных, купленный с `activationMode=ON_DEMAND`. \nТребуются заголовки `CF-MERCHANT-ID` и `CF-ACCESS-SIGN`.\n\n---\n\n**Требования:**\n- У пакета `activationMode` должен быть `ON_DEMAND`\n- Пакет ещё не должен быть активирован (`activatedAt = null`)\n\n---\n\n**Подпись:** получите через `POST /customer/sign`, скопируйте `signature` в заголовок `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 тела запроса","required":true}],"responses":{"200":{"description":"Пакет успешно активирован","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"idPack":{"type":"integer"},"status":{"type":"string"}}}}}},"400":{"description":"Некорректные параметры, пакет не найден или уже активирован","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["idPack"],"type":"object","properties":{"idPack":{"description":"ID пакета, полученный при создании пакета","type":"integer"}}}}},"required":true}}}}}
```
## Получить информацию о подключении eSIM-профиля
> \
> Возвращает информацию о подключении eSIM-профиля по ICCID. \
> Требуются заголовки \`CF-MERCHANT-ID\` и \`CF-ACCESS-SIGN\`.\
> \
> \---\
> \
> \*\*Подпись:\*\* для GET передайте в \`POST /customer/sign\` поле \`payload\` как \`{}\`, скопируйте \`signature\` в \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/connectivity":{"get":{"operationId":"connectivity_order","summary":"Получить информацию о подключении eSIM-профиля","description":"\nВозвращает информацию о подключении eSIM-профиля по ICCID. \nТребуются заголовки `CF-MERCHANT-ID` и `CF-ACCESS-SIGN`.\n\n---\n\n**Подпись:** для GET передайте в `POST /customer/sign` поле `payload` как `{}`, скопируйте `signature` в `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 запроса","required":true},{"schema":{"type":"string"},"name":"iccid","in":"query","description":"ICCID eSIM-профиля","required":true}],"responses":{"200":{"description":"Информация о подключении успешно получена","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"connectivity":{"type":"object","properties":{"active":{"type":"boolean"},"eid":{"type":"string"},"iccid":{"type":"string"},"imsi":{"type":"string"},"lastCountryCodeChange":{"type":"string"},"lastDataConsumed":{"type":"string"},"lastNetwork":{"type":"string"},"lastTimeConnected":{"type":"string"},"state":{"type":"string"}}}}}}}},"400":{"description":"Некорректные параметры или eSIM-профиль не найден","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"]}}}}
```
## Получить статус заказа
> \
> Возвращает текущий статус заказа по \`uidCustomer\`.\
> \
> \---\
> \
> \*\*Статус заказа \`status\`:\*\*\
> \
> \| Значение | Описание |\
> \|-------|-------------|\
> \| \`in\_processing\` | Заказ обрабатывается — eSIM ещё не выдан |\
> \| \`completed\` | eSIM выдан — возвращается полный объект с данными |\
> \| \`canceled\` | Заказ отменён — средства возвращены на баланс |\
> \
> При \`completed\` — возвращается полный объект с \`esimProfile\`, \`customer\` и списком \`activatedItems\`. \
> При \`in\_processing\` или \`canceled\` — только базовые идентификаторы.\
> \
> \---\
> \
> \*\*Подпись:\*\* для GET передайте в \`POST /customer/sign\` поле \`payload\` как \`{}\`, скопируйте \`signature\` в \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/getStatus":{"get":{"operationId":"get_order_status","summary":"Получить статус заказа","description":"\nВозвращает текущий статус заказа по `uidCustomer`.\n\n---\n\n**Статус заказа `status`:**\n\n| Значение | Описание |\n|-------|-------------|\n| `in_processing` | Заказ обрабатывается — eSIM ещё не выдан |\n| `completed` | eSIM выдан — возвращается полный объект с данными |\n| `canceled` | Заказ отменён — средства возвращены на баланс |\n\nПри `completed` — возвращается полный объект с `esimProfile`, `customer` и списком `activatedItems`. \nПри `in_processing` или `canceled` — только базовые идентификаторы.\n\n---\n\n**Подпись:** для GET передайте в `POST /customer/sign` поле `payload` как `{}`, скопируйте `signature` в `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 тела запроса","required":true},{"schema":{"type":"string"},"name":"uidCustomer","in":"query","description":"UUID заказа, полученный при создании","required":true}],"responses":{"200":{"description":"Статус успешно получен","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"uidCustomer":{"type":"string"},"orderId":{"type":"string"},"status":{"type":"string","enum":["in_processing","completed","canceled"]},"createdAt":{"type":"string"},"esimProfile":{"description":"Только при status=completed","type":["object","null"],"properties":{"iccid":{"type":"string"},"imsi":{"type":"string"},"activationCode":{"type":"string"},"appleUniversalLink":{"type":["string","null"]},"androidUniversalLink":{"type":["string","null"]},"installationUrl":{"type":["string","null"]},"state":{"type":"string"},"active":{"type":"boolean"},"activatedAt":{"type":["string","null"]}}},"customer":{"description":"Только при status=completed","type":["object","null"],"properties":{"uidCustomer":{"type":"string"},"profileUrl":{"type":["string","null"]}}},"activatedItems":{"description":"Список пакетов. Только при status=completed","type":["array","null"],"items":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"activationMode":{"type":"string"},"countrySet":{"type":"string"},"salesDate":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"activatedAt":{"type":["string","null"]},"validity":{"type":"object","properties":{"size":{"type":"integer"},"unit":{"type":"string"}}},"availableBalance":{"type":"object","properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}},"size":{"type":"object","properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}},"salePrice":{"type":"number"},"reward":{"description":"Вознаграждение мерчанта в USD","type":["number","null"]},"rewardPercent":{"description":"Процент наценки вознаграждения","type":["number","null"]},"status":{"type":"string"}}}},"totalAvailableBalance":{"description":"Общий остаток по всем пакетам","type":["object","null"],"properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}}}}}}},"400":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Заказ не найден","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"]}}}}
```
## Возврат средств за пакет данных
> \
> Запрашивает возврат средств за купленный пакет данных. \
> Требуются заголовки \`CF-MERCHANT-ID\` и \`CF-ACCESS-SIGN\`.\
> \
> \---\
> \
> \*\*Условия возврата — все должны выполняться:\*\*\
> \
> \| Условие | Описание |\
> \|-----------|-------------|\
> \| Статус пакета | Действителен (не истёк) и не использован (остаток данных полный) |\
> \| Активация | Пакет ещё не активирован (\`activatedAt = null\`) |\
> \| Месячный лимит | Лимит возвратов за текущий месяц не исчерпан |\
> \
> При выполнении всех условий стоимость пакета возвращается на баланс мерчанта. \
> Иначе система вернёт ошибку.\
> \
> \---\
> \
> \*\*Подпись:\*\* получите через \`POST /customer/sign\`, скопируйте \`signature\` в заголовок \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/refund":{"post":{"operationId":"refund_order","summary":"Возврат средств за пакет данных","description":"\nЗапрашивает возврат средств за купленный пакет данных. \nТребуются заголовки `CF-MERCHANT-ID` и `CF-ACCESS-SIGN`.\n\n---\n\n**Условия возврата — все должны выполняться:**\n\n| Условие | Описание |\n|-----------|-------------|\n| Статус пакета | Действителен (не истёк) и не использован (остаток данных полный) |\n| Активация | Пакет ещё не активирован (`activatedAt = null`) |\n| Месячный лимит | Лимит возвратов за текущий месяц не исчерпан |\n\nПри выполнении всех условий стоимость пакета возвращается на баланс мерчанта. \nИначе система вернёт ошибку.\n\n---\n\n**Подпись:** получите через `POST /customer/sign`, скопируйте `signature` в заголовок `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 тела запроса","required":true}],"responses":{"200":{"description":"Возврат выполнен — средства зачислены на баланс мерчанта","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"idPack":{"type":"integer"},"status":{"type":"string"}}}}}},"400":{"description":"Некорректные параметры, пакет не найден, уже активирован или условия возврата не выполнены","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["idPack"],"type":"object","properties":{"idPack":{"description":"ID пакета, полученный при создании пакета","type":"integer"}}}}},"required":true}}}}}
```
## Создать заказ
> \
> Создаёт новый заказ на покупку пакета eSIM. \
> Требуются заголовки \`CF-MERCHANT-ID\` и \`CF-ACCESS-SIGN\`. \
> Списывает баланс мерчанта и запускает выдачу eSIM-профиля.\
> \
> \---\
> \
> \*\*Параметр \`activationMode\`:\*\*\
> \
> \| Значение | Описание |\
> \|-------|-------------|\
> \| \`NOW\` | Пакет активируется сразу после покупки \*(по умолчанию)\* |\
> \| \`FIRST\_USE\` | Пакет активируется при первом подключении к сети |\
> \| \`ON\_DEMAND\` | Пакет активируется вручную через API |\
> \
> \---\
> \
> \*\*Подпись:\*\* получите через \`POST /customer/sign\`, скопируйте \`signature\` в заголовок \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/submit":{"post":{"operationId":"create_order","summary":"Создать заказ","description":"\nСоздаёт новый заказ на покупку пакета eSIM. \nТребуются заголовки `CF-MERCHANT-ID` и `CF-ACCESS-SIGN`. \nСписывает баланс мерчанта и запускает выдачу eSIM-профиля.\n\n---\n\n**Параметр `activationMode`:**\n\n| Значение | Описание |\n|-------|-------------|\n| `NOW` | Пакет активируется сразу после покупки *(по умолчанию)* |\n| `FIRST_USE` | Пакет активируется при первом подключении к сети |\n| `ON_DEMAND` | Пакет активируется вручную через API |\n\n---\n\n**Подпись:** получите через `POST /customer/sign`, скопируйте `signature` в заголовок `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 тела запроса","required":true}],"responses":{"200":{"description":"Заказ успешно создан","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"esimProfile":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"salePrice":{"type":"number"}}},"uidCustomer":{"type":"string"},"orderId":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Некорректные параметры запроса или продукт не найден","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Недостаточно средств на балансе мерчанта","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Заказ с таким orderId уже существует","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"uidCustomer":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["productId"],"type":"object","properties":{"orderId":{"description":"Уникальный идентификатор заказа на стороне мерчанта","type":"string"},"productId":{"description":"Идентификатор продукта (пакета)","type":"string"},"activationMode":{"description":"Режим активации eSIM","type":"string","enum":["NOW","FIRST_USE","ON_DEMAND"]},"callback":{"description":"URL для webhook-уведомлений о статусе заказа","type":["string","null"]}}}}},"required":true}}}}}
```
## Купить дополнительный пакет для существующего eSIM-профиля
> \
> Создаёт дополнительный пакет данных для уже существующего eSIM-профиля. \
> Требуются заголовки \`CF-MERCHANT-ID\` и \`CF-ACCESS-SIGN\`. \
> Списывает баланс мерчанта и ставит пакет в очередь на активацию.\
> \
> \---\
> \
> \*\*Параметр \`activationMode\`:\*\*\
> \
> \| Значение | Описание |\
> \|-------|-------------|\
> \| \`NOW\` | Пакет активируется сразу после покупки \*(по умолчанию)\* |\
> \| \`FIRST\_USE\` | Пакет активируется при первом подключении к сети |\
> \| \`ON\_DEMAND\` | Пакет активируется вручную через API |\
> \
> \---\
> \
> \*\*Подпись:\*\* получите через \`POST /customer/sign\`, скопируйте \`signature\` в заголовок \`CF-ACCESS-SIGN\`.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Создание, пополнение, активация, возврат и отслеживание заказов eSIM."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/topup":{"post":{"operationId":"top_up_order","summary":"Купить дополнительный пакет для существующего eSIM-профиля","description":"\nСоздаёт дополнительный пакет данных для уже существующего eSIM-профиля. \nТребуются заголовки `CF-MERCHANT-ID` и `CF-ACCESS-SIGN`. \nСписывает баланс мерчанта и ставит пакет в очередь на активацию.\n\n---\n\n**Параметр `activationMode`:**\n\n| Значение | Описание |\n|-------|-------------|\n| `NOW` | Пакет активируется сразу после покупки *(по умолчанию)* |\n| `FIRST_USE` | Пакет активируется при первом подключении к сети |\n| `ON_DEMAND` | Пакет активируется вручную через API |\n\n---\n\n**Подпись:** получите через `POST /customer/sign`, скопируйте `signature` в заголовок `CF-ACCESS-SIGN`.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Идентификатор мерчанта для аутентификации","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"Подпись HMAC-SHA256 тела запроса","required":true}],"responses":{"200":{"description":"Пакет поставлен в очередь на активацию","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"uidCustomer":{"type":"string"},"package":{"type":"object","properties":{"id":{"type":"integer"},"productId":{"type":"string"},"name":{"type":"string"},"orderId":{"type":["string","null"]},"status":{"type":"string"},"salePrice":{"type":"number"}}}}}}}},"400":{"description":"Некорректные параметры запроса, профиль или продукт не найден","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Недостаточно средств на балансе мерчанта","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Заказ с таким orderId уже существует","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"uidCustomer":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["uidCustomer","productId"],"type":"object","properties":{"uidCustomer":{"description":"UUID существующего eSIM-профиля","type":"string"},"productId":{"description":"Идентификатор продукта (пакета)","type":"string"},"orderId":{"description":"Уникальный идентификатор заказа на стороне мерчанта","type":"string"},"activationMode":{"description":"Режим активации пакета","type":"string","enum":["NOW","FIRST_USE","ON_DEMAND"]},"callback":{"description":"URL для webhook-уведомлений о статусе заказа","type":["string","null"]}}}}},"required":true}}}}}
```