Batch операции

Массовое создание счетов через CSV файл

POST /api/v1/batch/invoices

Batch операции

cURL

curl --request POST \
  --url https://loveandpay.io/api/v1/batch/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "sendEmails": true,
  "defaultCurrency": "<string>",
  "defaultRedirectUrl": "<string>"
}
'

200

{
  "batchId": "<string>",
  "total": 123,
  "created": 123,
  "failed": 123,
  "invoices": [
    {}
  ],
  "errors": [
    {}
  ]
}

Массовое создание счетов

Позволяет создать множество счетов одним запросом через загрузку CSV файла.

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

x-api-key · string · required

Ваш API ключ

Формат CSV файла

CSV файл должен содержать следующие колонки:

Колонка	Обязательная	Описание
amount	Да	Сумма счёта
currency	Да	Валюта (USD, EUR, RUB, KZT)
description	Нет	Описание счёта
email	Нет	Email клиента для уведомления
externalId	Нет	Ваш внутренний ID для связки
redirectUrl	Нет	URL редиректа после оплаты

Пример CSV файла

amount,currency,description,email,externalId
100.00,USD,Заказ #1001,[e-mail],order_1001
250.50,USD,Заказ #1002,[e-mail],order_1002
75.00,EUR,Подписка Pro,[e-mail],sub_monthly_003
500.00,RUB,Услуги консалтинга,[e-mail],service_004

Пример запроса

cURL

curl -X POST "https://loveandpay.io/api/v1/batch/invoices" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@invoices.csv" \
  -F "sendEmails=true"

Параметры запроса

file · file · required

CSV файл со списком счетов (максимум 1000 строк, 5MB)

sendEmails · boolean · default: "false"

Отправить email с ссылкой на оплату указанным в CSV адресатам

defaultCurrency · string

Валюта по умолчанию, если не указана в CSV

defaultRedirectUrl · string

URL редиректа по умолчанию

Пример ответа

batchId · string

Уникальный идентификатор batch-операции

total · number

Общее количество строк в файле

created · number

Количество успешно созданных счетов

failed · number

Количество ошибок

invoices · array

Массив созданных счетов

errors · array

Массив ошибок с указанием строки

Успешный ответ (201)

{
  "batchId": "batch_abc123def456",
  "total": 4,
  "created": 3,
  "failed": 1,
  "invoices": [
    {
      "id": "inv_001",
      "amount": 100.00,
      "currency": "USD",
      "externalId": "order_1001",
      "paymentUrl": "https://pay.loveandpay.io/inv_001",
      "status": "pending"
    },
    {
      "id": "inv_002",
      "amount": 250.50,
      "currency": "USD",
      "externalId": "order_1002",
      "paymentUrl": "https://pay.loveandpay.io/inv_002",
      "status": "pending"
    },
    {
      "id": "inv_003",
      "amount": 75.00,
      "currency": "EUR",
      "externalId": "sub_monthly_003",
      "paymentUrl": "https://pay.loveandpay.io/inv_003",
      "status": "pending"
    }
  ],
  "errors": [
    {
      "row": 4,
      "externalId": "service_004",
      "error": "Invalid currency: RUB is not supported for this account"
    }
  ]
}

Ограничения

Параметр	Значение
Максимум строк	1000
Максимум размер файла	5 MB
Формат	CSV (UTF-8)
Разделитель	Запятая (,)

Отслеживание статуса batch

После создания batch-операции вы можете отслеживать статус:

curl -X GET "https://loveandpay.io/api/v1/batch/invoices/batch_abc123def456" \
  -H "x-api-key: YOUR_API_KEY"

{
  "batchId": "batch_abc123def456",
  "status": "completed",
  "total": 4,
  "created": 3,
  "failed": 1,
  "paidCount": 2,
  "totalVolume": 350.50,
  "createdAt": "2024-01-15T10:30:00Z"
}

Примеры использования

Выставление счетов клиентам

const Papa = require('papaparse');

// Подготовка данных из вашей системы
const customers = await db.getCustomersForBilling();

const csvData = customers.map(c => ({
  amount: c.invoiceAmount,
  currency: 'USD',
  description: `Ежемесячная подписка - ${c.plan}`,
  email: c.email,
  externalId: `billing_${c.id}_${Date.now()}`
}));

// Генерация CSV
const csv = Papa.unparse(csvData);

// Загрузка через API
const form = new FormData();
form.append('file', new Blob([csv], { type: 'text/csv' }), 'billing.csv');
form.append('sendEmails', 'true');

const result = await fetch('/api/v1/batch/invoices', {
  method: 'POST',
  headers: { 'x-api-key': API_KEY },
  body: form
});

Экспорт и импорт из Excel

import pandas as pd

# Читаем Excel файл
df = pd.read_excel('invoices.xlsx')

# Преобразуем в нужный формат
df = df.rename(columns={
    'Сумма': 'amount',
    'Валюта': 'currency',
    'Описание': 'description',
    'Email клиента': 'email',
    'ID заказа': 'externalId'
})

# Сохраняем как CSV
df.to_csv('invoices.csv', index=False)

# Загружаем через API
# ... (см. пример выше)

Ошибки

Код	Описание
400	Неверный формат файла или превышен лимит
401	Неверный API ключ
413	Файл слишком большой
422	Ошибки валидации в CSV