# Создание инвойса и проведения платежа \[new] - оплата криптовалютой

### 1. Общая информация

API позволяет создать инвойс и затем получить реквизиты для оплаты по созданному инвойсу.

Базовый URL: `https://external.api.nbcgate.tech`

Авторизация: для всех запросов передавайте интеграционный ключ в заголовке:

* `X-API-Key: <ваш_ключ>`

Заголовки запроса:

* `Content-Type: application/json`
* `Accept: application/json` (рекомендуется)

Префикс маршрутов: методы доступны по путям с префиксом `/api/...` (не `/invoice/...` с корня домена).

***

### 2. Этапы работы

#### Шаг 1. Создание инвойса

Создаётся новый инвойс с указанием суммы, монеты, pay link и продукта.

Метод и URL: `POST /api/invoice/create`

Пример запроса (cURL):

```bash
curl -X POST 'https://external.api.nbcgate.tech/api/invoice/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <ваш_ключ>' \
  -d '{
    "amount": 100,
    "coin_id": 1,
    "id": 12345,
    "product_id": 67890
  }'
```

Тело запроса:

| Поле         | Тип    | Обязательное | Описание                                   |
| ------------ | ------ | ------------ | ------------------------------------------ |
| `amount`     | number | да           | Сумма инвойса                              |
| `coin_id`    | number | да           | Идентификатор монеты/валюты в вашей модели |
| `id`         | number | да           | Идентификатор pay link                     |
| `product_id` | number | да           | Идентификатор продукта                     |

Успешный ответ (200): возвращается идентификатор созданного инвойса в поле `idInvoice` (не обёртка `success` / `invoice_id`).

Пример:

```json
{"idInvoice": 12345}
```

| Поле        | Тип    | Описание                                                       |
| ----------- | ------ | -------------------------------------------------------------- |
| `idInvoice` | number | Идентификатор инвойса для следующего шага (`/api/invoice/pay`) |

***

#### Шаг 2. Проведение платежа по инвойсу

По идентификатору инвойса возвращаются данные для перевода (адрес, сумма в криптовалюте, сеть, код актива и т.д.).

Метод и URL: `POST /api/invoice/pay`

Пример запроса (cURL):

```bash
curl -X POST 'https://external.api.nbcgate.tech/api/invoice/pay' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <ваш_ключ>' \
  -d '{
    "idInvoice": 12345
  }'
```

Тело запроса:

| Поле        | Тип    | Обязательное | Описание                                             |
| ----------- | ------ | ------------ | ---------------------------------------------------- |
| `idInvoice` | number | да           | Идентификатор инвойса из ответа шага 1 (`idInvoice`) |

Пример успешного ответа (200):

```json
{
  "address": "TRDkc3pmPnvYZ2UiDsmModEitJp7akTVyy",
  "amount": "444.274652",
  "rate": 0.116482,
  "name": "Tron Shasta Testnet",
  "code": "TRX",
  "transferCommissionWeis": 0,
  "pay_link_amount": 0,
  "paid_amount": 0,
  "commission_amount": 0,
  "merchant_commission_amount": 0,
  "client_commission_amount": 0
}
```

Описание полей ответа:

| Поле                         | Тип    | Описание                                             |
| ---------------------------- | ------ | ---------------------------------------------------- |
| `address`                    | string | Адрес для перевода                                   |
| `amount`                     | string | Сумма к переводу в криптовалюте (строка)             |
| `rate`                       | number | Курс                                                 |
| `name`                       | string | Название сети                                        |
| `code`                       | string | Код криптовалюты                                     |
| `transferCommissionWeis`     | number | Комиссия перевода (в единицах, зависящих от бэкенда) |
| `pay_link_amount`            | number | Сумма по pay link                                    |
| `paid_amount`                | number | Уже оплаченная сумма                                 |
| `commission_amount`          | number | Комиссия                                             |
| `merchant_commission_amount` | number | Комиссия мерчанта                                    |
| `client_commission_amount`   | number | Комиссия клиента                                     |

Часть числовых полей может быть `0`, если для данного сценария они не заполняются.

Как использовать ответ: отправьте на `address` сумму `amount` в сети/активе, соответствующих `name` и `code`.

***

### 3. Полный сценарий (два запроса подряд)

1. Создать инвойс — `POST /api/invoice/create` → в ответе `idInvoice`.
2. Получить реквизиты оплаты — `POST /api/invoice/pay` с телом `{ "idInvoice": <тот же id> }` → объект с `address`, `amount`, `code` и остальными полями.

В отличие от старой документации, нет полей вида `success`, `message` или отдельного `invoice_id` в JSON — идентификатор инвойса при создании — это `idInvoice`, а ответ на оплату — не «успех операции», а данные платежа.

***

### 4. Ошибки

Формат ошибок в этом сервисе: `statusCode`, `message`, при необходимости массив `errors` с полем `code`.

Типичные случаи:

| HTTP | Когда                                                                    |
| ---- | ------------------------------------------------------------------------ |
| 400  | Некорректное тело JSON, невалидные поля                                  |
| 401  | Нет или неверный `X-API-Key`                                             |
| 500  | Внутренняя ошибка при обращении к внутреннему сервису или разборе ответа |

Конкретные коды бизнес-ошибок (например, «инвойс не найден») зависят от нижележащего CryptoPay API; при ошибке обычно приходит 500 с текстом ошибки в `errors` / `field` в ответе сервиса.

***