Skip to content

На этой странице

API Мерчанта - Инвойсы

Блок merchant предоставляет API для управления инвойсами (счетами) - создание, получение, изменение статуса и настройка параметров.

Интерактивное тестирование

На этой странице вы можете протестировать API в реальном времени! Введите ваш API ключ в поле ниже и нажимайте кнопки "Тестировать" для отправки запросов к серверу https://cp-merch-dev.wsdemo.online/api.

Если возникает CORS ошибка:

  • Используйте кнопки "📋 Копировать curl" для получения готовых команд
  • Выполните команды в терминале или используйте Postman
  • Установите расширение браузера для отключения CORS (например, "CORS Unblock")

Обзор

API инвойсов позволяет:

  • Создавать новые инвойсы для приема платежей
  • Получать информацию об инвойсах
  • Изменять статус инвойсов
  • Получать сводную статистику
  • Настраивать параметры инвойсов

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

Все запросы к API требуют аутентификации через Bearer токен в заголовке Authorization.

POST

Создать инвойс

POST /v1/invoices

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

Параметры

ПараметрТипОбязательныйОписание
currencystringДаУникальный идентификатор монеты (например, eth, btc)
amountnumberДаКоличество монет в инвойсе
externalIdstringНетВнешний ID инвойса

Ответы

201 Created

Инвойс успешно создан

400 Bad Request

Неверные параметры запроса

PUT

Изменить статус инвойса

PUT /v1/invoices

Изменяет статус указанного инвойса.

Параметры

ПараметрТипОбязательныйОписание
invoiceIdstringДаID инвойса
statusstringДаНовый статус инвойса

Ответы

201 Created

Статус успешно изменен

400 Bad Request

Неверные параметры запроса

GET

Получить список инвойсов

GET /v1/invoices/getAll

Возвращает список всех инвойсов с возможностью фильтрации и пагинации.

Параметры

ПараметрТипОбязательныйОписание
pagenumberНетНомер страницы (по умолчанию 1)
perPagenumberНетКоличество элементов на странице (по умолчанию 20)
statusarrayНетФильтр по статусу
addressstringНетФильтр по адресу
currencystringНетФильтр по валюте
fromstringНетДата начала фильтра (YYYY-MM-DD)
tostringНетДата окончания фильтра (YYYY-MM-DD)

Ответы

200 OK

Список инвойсов получен

GET

Получить инвойс

GET /v1/invoices

Возвращает информацию о конкретном инвойсе по его ID.

Параметры

ПараметрТипОбязательныйОписание
idstringДаID инвойса

Ответы

200 OK

Информация об инвойсе получена

400 Bad Request

Неверный ID инвойса

GET

Получить инвойс по внешнему ID

GET /v1/invoices/getByExternalId

Возвращает информацию о конкретном инвойсе по его внешнему ID.

Параметры

ПараметрТипОбязательныйОписание
externalIdstringДаВнешний ID инвойса

Ответы

200 OK

Информация об инвойсе получена

400 Bad Request

Неверный внешний ID

GET

Получить сводку

GET /v1/invoices/summary

Возвращает информацию с суммой всех выставленных инвойсов и суммой всех полученных средств.

Ответы

200 OK

Сводная информация получена

GET

Получить настройки инвойсов

GET /v1/invoices/configureSettings

Получает текущие настройки конфигурации инвойсов.

Ответы

200 OK

Настройки получены

PUT

Настроить параметры инвойсов

PUT /v1/invoices/configureSettings

Настраивает параметры инвойсов для различных сетей и валют.

Параметры

ПараметрТипОбязательныйОписание
settingsobjectДаОбъект с настройками инвойсов

Ответы

201 Created

Настройки успешно обновлены

400 Bad Request

Неверные параметры

Конфигурация API

Создать инвойс

bash
curl -X POST "https://cp-merch-dev.wsdemo.online/api/v1/invoices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "eth",
    "amount": 0.001,
    "externalId": "demo_123"
  }'

Ответ:

json
{
  "id": "inv_abc123def456",
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
  "amount": "0.001",
  "currency": "eth",
  "externalId": "demo_123"
}

Получить список инвойсов

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Ответ:

json
{
  "count": 150,
  "data": [
    {
      "id": "inv_abc123def456",
      "address": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
      "amount": "0.001",
      "received": "0.001",
      "currency": "eth",
      "symbol": "ETH",
      "network": "ethereum",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00Z",
      "externalId": "demo_123",
      "transactions": [
        {
          "id": "tx_123",
          "from": "0x123...",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
          "amount": "0.001",
          "hash": "0xabc123...",
          "status": "confirmed",
          "block": 18500000
        }
      ]
    }
  ]
}

Получить инвойс по ID

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices?id=inv_abc123def456" \
  -H "X-Api-Key: YOUR_API_KEY"

Получить инвойс по внешнему ID

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getByExternalId?externalId=demo_123" \
  -H "X-Api-Key: YOUR_API_KEY"

Получить сводку

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/summary" \
  -H "X-Api-Key: YOUR_API_KEY"

Ответ:

json
[
  {
    "totalAmount": "10.5",
    "totalReceived": "8.3",
    "currencySlug": "btc"
  },
  {
    "totalAmount": "150.0",
    "totalReceived": "142.5",
    "currencySlug": "eth"
  }
]

Изменить статус инвойса

bash
curl -X PUT "https://cp-merch-dev.wsdemo.online/api/v1/invoices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "inv_abc123def456",
    "status": "completed"
  }'

Получить настройки инвойсов

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/configureSettings" \
  -H "X-Api-Key: YOUR_API_KEY"

Go HTTP Client

go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    // Создать новый инвойс
    payload := map[string]interface{}{
        "currency":   "eth",
        "amount":     0.001,
        "externalId": "demo_123",
    }
    
    jsonData, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest("POST", "https://cp-merch-dev.wsdemo.online/api/v1/invoices", bytes.NewBuffer(jsonData))
    req.Header.Set("X-Api-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Создан инвойс: %s\n", body)
    
    // Получить список инвойсов
    req2, _ := http.NewRequest("GET", "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20", nil)
    req2.Header.Set("X-Api-Key", "YOUR_API_KEY")
    
    resp2, err := client.Do(req2)
    if err != nil {
        panic(err)
    }
    defer resp2.Body.Close()
    
    body2, _ := io.ReadAll(resp2.Body)
    fmt.Printf("Список инвойсов: %s\n", body2)
}

Структуры данных

go
// Запрос на создание инвойса
type CreateInvoiceRequest struct {
    Currency   string  `json:"currency"`
    Amount     float64 `json:"amount"`
    ExternalID string  `json:"externalId,omitempty"`
}

// Ответ при создании инвойса
type CreatedInvoiceResponse struct {
    ID         string `json:"id"`
    Address    string `json:"address"`
    Amount     string `json:"amount"`
    Currency   string `json:"currency"`
    ExternalID string `json:"externalId"`
}

// Информация об инвойсе
type InvoiceResponse struct {
    ID          string        `json:"id"`
    Address     string        `json:"address"`
    Amount      string        `json:"amount"`
    Received    string        `json:"received"`
    Overpayment string        `json:"overpayment,omitempty"`
    Currency    string        `json:"currency"`
    Symbol      string        `json:"symbol"`
    Network     string        `json:"network"`
    Status      string        `json:"status"`
    CreatedAt   time.Time     `json:"createdAt"`
    ExternalID  string        `json:"externalId,omitempty"`
    Transactions []Transaction `json:"transactions"`
}

// Транзакция
type Transaction struct {
    ID          string    `json:"id"`
    From        string    `json:"from"`
    To          string    `json:"to"`
    Amount      string    `json:"amount"`
    Hash        string    `json:"hash"`
    Status      string    `json:"status"`
    RateUSD     float64   `json:"rate_USD"`
    Block       int64     `json:"block"`
    CreatedDate time.Time `json:"createdDate"`
}

// Сводка
type SummaryResponse struct {
    TotalAmount   string `json:"totalAmount"`
    TotalReceived string `json:"totalReceived"`
    CurrencySlug  string `json:"currencySlug"`
}

JavaScript Fetch

javascript
// Создать новый инвойс
const createInvoice = async () => {
  const response = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currency: 'eth',
      amount: 0.001,
      externalId: 'demo_123'
    })
  });
  
  const invoice = await response.json();
  console.log('Создан инвойс:', invoice);
  
  // Получить список инвойсов
  const listResponse = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20', {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const invoicesList = await listResponse.json();
  console.log('Найдено инвойсов:', invoicesList.count);
  
  // Получить инвойс по ID
  const invoiceResponse = await fetch(`https://cp-merch-dev.wsdemo.online/api/v1/invoices?id=${invoice.id}`, {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const invoiceDetails = await invoiceResponse.json();
  console.log('Статус инвойса:', invoiceDetails.status);
  
  // Получить сводку
  const summaryResponse = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices/summary', {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const summary = await summaryResponse.json();
  summary.forEach(s => {
    console.log(`Валюта ${s.currencySlug}: выставлено ${s.totalAmount}, получено ${s.totalReceived}`);
  });
};

createInvoice();

Обработка ошибок

javascript
try {
  const response = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currency: 'eth',
      amount: 0.001
    })
  });
  
  if (!response.ok) {
    throw new Error(`HTTP ошибка! статус: ${response.status}`);
  }
  
  const invoice = await response.json();
  console.log(invoice);
} catch (error) {
  console.error('Ошибка API:', error.message);
}

Python Requests

python
import requests
import json

# Конфигурация API
API_BASE = 'https://cp-merch-dev.wsdemo.online/api/v1'
headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Создать новый инвойс
payload = {
    'currency': 'eth',
    'amount': 0.001,
    'externalId': 'demo_123'
}

response = requests.post(f'{API_BASE}/invoices', 
                        headers=headers, 
                        json=payload)

if response.status_code == 201:
    invoice = response.json()
    print(f"Создан инвойс: {invoice['id']}, адрес: {invoice['address']}")
    
    # Получить список инвойсов
    list_response = requests.get(f'{API_BASE}/invoices/getAll?page=1&perPage=20', 
                                headers=headers)
    
    if list_response.status_code == 200:
        invoices_list = list_response.json()
        print(f"Найдено инвойсов: {invoices_list['count']}")
    
    # Получить инвойс по ID
    invoice_response = requests.get(f'{API_BASE}/invoices?id={invoice["id"]}', 
                                   headers=headers)
    
    if invoice_response.status_code == 200:
        invoice_details = invoice_response.json()
        print(f"Статус инвойса: {invoice_details['status']}")
    
    # Получить сводку
    summary_response = requests.get(f'{API_BASE}/invoices/summary', 
                                   headers=headers)
    
    if summary_response.status_code == 200:
        summary = summary_response.json()
        for s in summary:
            print(f"Валюта {s['currencySlug']}: выставлено {s['totalAmount']}, получено {s['totalReceived']}")
else:
    print(f"Ошибка: {response.status_code}")

Обработка ошибок

python
try:
    response = requests.post(f'{API_BASE}/invoices', 
                            headers=headers, 
                            json={
                                'currency': 'eth',
                                'amount': 0.001
                            })
    
    response.raise_for_status()  # Вызывает HTTPError для плохих ответов
    invoice = response.json()
    print(invoice)
except requests.exceptions.HTTPError as e:
    print(f"HTTP ошибка: {e}")
except requests.exceptions.RequestException as e:
    print(f"Ошибка запроса: {e}")

PHP cURL

php
<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://cp-merch-dev.wsdemo.online/api/v1';

// Создать новый инвойс
$payload = json_encode([
    'currency' => 'eth',
    'amount' => 0.001,
    'externalId' => 'demo_123'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/invoices');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    $invoice = json_decode($response, true);
    echo "Создан инвойс: " . $invoice['id'] . ", адрес: " . $invoice['address'] . "\n";
    
    // Получить список инвойсов
    $ch2 = curl_init();
    curl_setopt($ch2, CURLOPT_URL, $baseUrl . '/invoices/getAll?page=1&perPage=20');
    curl_setopt($ch2, CURLOPT_HTTPHEADER, [
        'X-Api-Key: ' . $apiKey
    ]);
    curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
    
    $listResponse = curl_exec($ch2);
    $listHttpCode = curl_getinfo($ch2, CURLINFO_HTTP_CODE);
    curl_close($ch2);
    
    if ($listHttpCode === 200) {
        $invoicesList = json_decode($listResponse, true);
        echo "Найдено инвойсов: " . $invoicesList['count'] . "\n";
    }
    
    // Получить сводку
    $ch3 = curl_init();
    curl_setopt($ch3, CURLOPT_URL, $baseUrl . '/invoices/summary');
    curl_setopt($ch3, CURLOPT_HTTPHEADER, [
        'X-Api-Key: ' . $apiKey
    ]);
    curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true);
    
    $summaryResponse = curl_exec($ch3);
    $summaryHttpCode = curl_getinfo($ch3, CURLINFO_HTTP_CODE);
    curl_close($ch3);
    
    if ($summaryHttpCode === 200) {
        $summary = json_decode($summaryResponse, true);
        foreach ($summary as $s) {
            echo "Валюта {$s['currencySlug']}: выставлено {$s['totalAmount']}, получено {$s['totalReceived']}\n";
        }
    }
} else {
    echo "Ошибка: " . $httpCode . "\n";
}
?>

Обработка ошибок

php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/invoices');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'currency' => 'eth',
    'amount' => 0.001
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'cURL ошибка: ' . curl_error($ch) . "\n";
} elseif ($httpCode >= 400) {
    echo "HTTP ошибка: " . $httpCode . "\n";
    echo "Ответ: " . $response . "\n";
} else {
    $invoice = json_decode($response, true);
    print_r($invoice);
}

curl_close($ch);
?>

Released under the MIT License.