README

Laravel пакет для роботи з API Нової Пошти з підтримкою наложеного платежу та контролю оплати.

🚀 Встановлення

composer require pashynskyi/nova-poshta

📋 Вимоги

• PHP >= 8.0
• Laravel >= 8.0
• GuzzleHttp >= 7.0
• API ключ Нової Пошти

⚡ Швидкий старт

Базове використання

use Pashynskyi\NovaPoshta\Invoice;

$invoice = new Invoice('your-api-key');

$invoice
    ->setPayerType('Recipient')
    ->setWeight('0.5')
    ->setSeatsAmount(1)
    ->setDescription('Товар')
    ->setCost('100')
    ->setSender('sender-ref')
    ->setCitySender('city-ref')
    ->setSenderAddress('warehouse-ref')
    ->setContactSender('contact-ref')
    ->setSendersPhone('380501234567')
    ->setCityRecipient('recipient-city-ref')
    ->setRecipientAddress('recipient-warehouse-ref')
    ->setRecipientName('Іван Іванов')
    ->setRecipientsPhone('380501234567');

$result = $invoice->send();

💰 Наложений платіж (Cash on Delivery)

✅ Рекомендований спосіб (працює з API 2024):

// Звичайний наложений платіж
$invoice->setCashOnDelivery(1200);

// З контролем оплати (кошти на банківський рахунок)
$invoice->setCashOnDeliveryWithControl(1200, true, 'transfer-123');

🔧 Альтернативні способи:

// Метод 1: Розширений контроль
$invoice->setCashOnDelivery(1200);
$invoice->setPaymentControl(1200);
$invoice->setMoneyTransferNumber('transfer-123');

// Метод 2: Старий підхід (може не працювати)
$invoice->setBackwardDeliveryPrice(1200, 'Recipient');

🏦 Контроль оплати

Для отримання коштів на банківський рахунок замість готівки:

Вимоги:

• Договір з Новою Поштою
• Договір з NovaPay
• Статус ЮО або ФОП

Використання:

// Базовий контроль оплати
$invoice->setPaymentControl(true);

// З конкретною сумою
$invoice->setPaymentControl(1200);

// З номером переказу
$invoice->setMoneyTransferNumber('MT-12345');

// Все разом
$invoice->setCashOnDeliveryWithControl(1200, true, 'MT-12345');

🏠 Доставка додому

$invoice->setDeliveryToDoors('вул. Хрещатик', '1', '15');
// Автоматично встановлює ServiceType: 'WarehouseDoors'

📞 Контактна особа отримувача

$invoice->setRecipientContactName('Іван Іванов');

🔧 Додаткові послуги

$invoice->setAdditionalService('CashOnDelivery');

📊 Повний приклад з наложеним платежем

use Pashynskyi\NovaPoshta\Invoice;

$invoice = new Invoice('your-api-key');

// Базові параметри
$invoice
    ->setPayerType('Recipient')
    ->setVolumeGeneral(0.004)
    ->setWeight('0.5')
    ->setSeatsAmount(1)
    ->setDescription('Кросівки Nike')
    ->setCost('1200')
    ->setSender('sender-counterparty-ref')
    ->setCitySender('sender-city-ref')
    ->setSenderAddress('sender-warehouse-ref')
    ->setContactSender('sender-contact-ref')
    ->setSendersPhone('380501234567')
    ->setCityRecipient('recipient-city-ref')
    ->setRecipientAddress('recipient-warehouse-ref')
    ->setRecipientName('Петро Петренко')
    ->setRecipientsPhone('380509876543')
    ->setRecipientContactName('Петро Петренко');

// Наложений платіж з контролем оплати
$invoice->setCashOnDeliveryWithControl(1200, true, 'ORDER-12345');

// Відправка
try {
    $result = $invoice->send();
    echo "Накладна створена: " . $result[0]['IntDocNumber'];
} catch (Exception $e) {
    echo "Помилка: " . $e->getMessage();
}

🚨 Відомі проблеми та рішення

Помилка: "Передана послуга Післяплата недоступна"

Причина: Зміни в API Нової Пошти 2024

Рішення: Використовуйте новий метод

// ❌ Не працює
$invoice->setBackwardDeliveryPrice($price);

// ✅ Працює
$invoice->setCashOnDelivery($price);

Контроль оплати не працює

Перевірте:

1. Наявність договору з NovaPay
2. Активацію послуги в кабінеті
3. Правильність API ключа

🔄 Міграція з попередніх версій

Версія 1.1.x → 1.2.0

// Було:
$invoice->setBackwardDeliveryPrice($price);

// Стало:
$invoice->setCashOnDelivery($price);

// Нова функція - контроль оплати:
$invoice->setCashOnDeliveryWithControl($price, true);

🚀 Синхронізація даних (оптимізовано)

Швидка синхронізація

# Синхронізація всіх даних (оптимізовано)
php artisan np:sync

# Тільки склади з пагінацією (для великих датасетів)
php artisan np:sync --entity=w --paginated --page-size=10000

# З налаштуванням розміру батчу
php artisan np:sync --batch-size=2000

# Без логування (максимальна швидкість)
php artisan np:sync --no-logging

# Показати статистику
php artisan np:sync --stats

Програмне використання

use Pashynskyi\NovaPoshta\Saver;

$saver = new Saver('your-api-key');

// Налаштування оптимізації
$saver->setBatchSize(2000)      // Розмір батчу
      ->setLogging(false);      // Вимкнути логування

// Звичайна синхронізація
$saver->saveWarehouses();

// Пагінована синхронізація (для великих датасетів)
$saver->saveWarehousesWithPagination(20000);

// Статистика
$stats = $saver->getStats();
echo "Складів: " . $stats['warehouses'];

📊 Покращення продуктивності

🔧 Налаштування оптимізації

// Для малих серверів
$saver = new Saver($apiKey, 500);  // Менший батч

// Для потужних серверів  
$saver = new Saver($apiKey, 5000); // Більший батч

// Пагінація для дуже великих датасетів
$saver->saveWarehousesWithPagination(10000);

⚠️ Проблеми з пам'яттю на сервері

Якщо виникає помилка Allowed memory size exhausted при синхронізації складів:

# Збільшити memory limit
php artisan np:sync --entity=w --memory-limit=512M

# Зменшити розмір сторінки
php artisan np:sync --entity=w --page-size=2000

# Комбінований підхід
php artisan np:sync --memory-limit=256M --page-size=3000

Примітка: Склади Nova Poshta (50,000+ записів) завжди синхронізуються з пагінацією для економії пам'яті.

📝 API Reference

Основні методи

Параметри API

🐛 Звіти про помилки

Якщо знайшли помилку або маєте пропозицію, створіть issue в репозиторії.

📄 Ліцензія

MIT License

👨‍💻 Автор

Alexander Pashynskyi

• Email: pashynskyi@gmail.com

Версія: 1.2.0
Дата оновлення: 16.11.2024
Сумісність: Nova Poshta API v2.0 (2024)