Перейти до вмісту
Polski for WooCommerce

Бухгалтерські інтеграції

Модуль з’єднує WooCommerce з польськими системами рахунків-фактур: wFirma, Fakturownia та iFirma. Рахунки-фактури надсилаються автоматично з повтором при помилках API.

Підтримувані системи

Section titled “Підтримувані системи”
СистемаФормат APIВерсія APIАвтентифікація
wFirmaXMLv2API key + API secret
FakturowniaJSONv3API token
iFirmaJSONv1Login + API key (ключ рахунків-фактур)

У будь-який момент може бути активною лише одна бухгалтерська інтеграція.

Налаштування

Section titled “Налаштування”

Перейдіть до WooCommerce > Налаштування > Polski PRO > Бухгалтерія.

Вибір провайдера

Section titled “Вибір провайдера”

Виберіть бухгалтерську систему та вкажіть дані автентифікації.

wFirma

Section titled “wFirma”
ПараметрОпис
API keyКлюч API з панелі wFirma
API secretСекрет API
ID компаніїІдентифікатор компанії у wFirma
Серія рахунків-фактурСерія нумерації (наприклад, “FV”, “FVS”)

Fakturownia

Section titled “Fakturownia”
ПараметрОпис
СубдоменНазва субдомену (наприклад, mojafirma.fakturownia.pl)
API tokenТокен API з налаштувань облікового запису
ID відділуНеобов’язково - ID відділу, що виставляє рахунки-фактури
Мова рахунка-фактуриpl або en

iFirma

Section titled “iFirma”
ПараметрОпис
LoginЛогін до облікового запису iFirma
Ключ API рахунків-фактурКлюч API для виставлення рахунків-фактур
Ключ API абонентаКлюч API абонента (для отримання даних)

Спільні налаштування

Section titled “Спільні налаштування”
ПараметрЗначення за замовчуваннямОпис
Автоматичне виставленняТакВиставляти рахунок-фактуру автоматично після оплати замовлення
Статус-тригерprocessingСтатус замовлення, що запускає виставлення рахунка-фактури
Тип документаРахунок-фактура ПДВРахунок-фактура ПДВ, Проформа, Рахунок
Додати до листаТакПрикласти PDF рахунка-фактури до листа замовлення
Повтор при помилціТакПовторити спробу при помилці API
Максимальна кількість спроб5Ліміт повторних спроб

Синхронізація рахунків-фактур

Section titled “Синхронізація рахунків-фактур”

Автоматичний потік

Section titled “Автоматичний потік”
  1. Замовлення WooCommerce змінює статус на processing (або інший налаштований)
  2. Модуль збирає дані замовлення та перетворює їх у формат провайдера
  3. Дані надсилаються асинхронно до API бухгалтерської системи
  4. Після успішного створення ID рахунка-фактури зберігається в мета замовлення
  5. PDF рахунка-фактури завантажується та прикладається до листа клієнту

Зіставлення даних

Section titled “Зіставлення даних”

Модуль автоматично зіставляє дані замовлення WooCommerce з необхідним форматом API:

Дані WooCommercewFirma (XML)Fakturownia (JSON)iFirma (JSON)
Назва компанії<contractor><name>buyer_nameKontrahent.Nazwa
NIP<contractor><nip>buyer_tax_noKontrahent.NIP
Адреса<contractor><street>buyer_streetKontrahent.Ulica
Позиції замовлення<invoicecontents>positionsPozycje
Ставка ПДВ<vat_code>taxStawkaVat
Спосіб оплати<paymentmethod>payment_typeSposobZaplaty

Формат XML (wFirma)

Section titled “Формат XML (wFirma)”
<api>
  <invoices>
    <invoice>
      <contractor>
        <name>Firma Testowa Sp. z o.o.</name>
        <nip>1234567890</nip>
        <street>ul. Testowa 1</street>
        <city>Warszawa</city>
        <zip>00-001</zip>
      </contractor>
      <invoicecontents>
        <invoicecontent>
          <name>Produkt testowy</name>
          <unit>szt.</unit>
          <count>2</count>
          <price>100.00</price>
          <vat_code>23</vat_code>
        </invoicecontent>
      </invoicecontents>
      <paymentmethod>transfer</paymentmethod>
      <paymentdate>2026-04-12</paymentdate>
    </invoice>
  </invoices>
</api>

Формат JSON (Fakturownia)

Section titled “Формат JSON (Fakturownia)”
{
  "invoice": {
    "kind": "vat",
    "number": null,
    "buyer_name": "Firma Testowa Sp. z o.o.",
    "buyer_tax_no": "1234567890",
    "buyer_street": "ul. Testowa 1",
    "buyer_city": "Warszawa",
    "buyer_post_code": "00-001",
    "positions": [
      {
        "name": "Produkt testowy",
        "quantity": 2,
        "total_price_gross": "246.00",
        "tax": "23"
      }
    ],
    "payment_type": "transfer",
    "payment_to": "2026-04-12"
  }
}

Механізм retry

Section titled “Механізм retry”

Exponential backoff

Section titled “Exponential backoff”

Коли API повертає помилку (HTTP 5xx, timeout, помилка з’єднання), модуль автоматично планує повторну спробу з експоненціальною затримкою:

СпробаЗатримкаЧас від першої спроби
1Одразу0 с
230 с30 с
32 хв2 хв 30 с
48 хв10 хв 30 с
532 хв42 хв 30 с

Затримка обчислюється за формулою: delay = base_delay * 2^(attempt - 1), де base_delay = 30 секунд.

Помилки, що не підлягають retry

Section titled “Помилки, що не підлягають retry”

Помилки клієнта (HTTP 4xx) не повторюються автоматично, оскільки вказують на проблему з даними, а не з API:

  • 400 Bad Request - неправильні дані
  • 401 Unauthorized - помилковий токен API
  • 403 Forbidden - відсутність прав
  • 422 Unprocessable Entity - валідація даних

Ці помилки логуються та потребують втручання адміністратора.

Асинхронне надсилання

Section titled “Асинхронне надсилання”

Рахунки-фактури надсилаються асинхронно за допомогою WC_Action_Scheduler, що означає, що вони не блокують процес оформлення замовлення. Клієнт бачить підтвердження замовлення одразу, а рахунок-фактура генерується у фоні.

/**
 * Akcja wywoływana po pomyślnym wystawieniu faktury.
 *
 * @param int    $order_id   ID zamówienia
 * @param string $invoice_id ID faktury w systemie księgowym
 * @param string $provider   Nazwa dostawcy ('wfirma', 'fakturownia', 'ifirma')
 */
do_action('polski_pro/accounting/invoice_created', int $order_id, string $invoice_id, string $provider);

Приклад - логування до зовнішньої системи:

add_action('polski_pro/accounting/invoice_created', function (
    int $order_id,
    string $invoice_id,
    string $provider
): void {
    error_log(sprintf(
        '[Polski PRO] Faktura %s wystawiona w %s dla zamówienia #%d',
        $invoice_id,
        $provider,
        $order_id
    ));
}, 10, 3);

Хук помилки

Section titled “Хук помилки”
/**
 * Akcja wywoływana po wyczerpaniu prób wysłania faktury.
 *
 * @param int    $order_id   ID zamówienia
 * @param string $provider   Nazwa dostawcy
 * @param string $error      Komunikat błędu
 * @param int    $attempts   Liczba wykonanych prób
 */
do_action('polski_pro/accounting/invoice_failed', int $order_id, string $provider, string $error, int $attempts);

Приклад - сповіщення адміністратора:

add_action('polski_pro/accounting/invoice_failed', function (
    int $order_id,
    string $provider,
    string $error,
    int $attempts
): void {
    $admin_email = get_option('admin_email');
    wp_mail(
        $admin_email,
        sprintf('Błąd wystawienia faktury - zamówienie #%d', $order_id),
        sprintf(
            "Nie udało się wystawić faktury w %s po %d próbach.\n\nBłąd: %s\n\nSprawdź zamówienie: %s",
            $provider,
            $attempts,
            $error,
            admin_url(sprintf('post.php?post=%d&action=edit', $order_id))
        )
    );
}, 10, 4);

Фільтр даних рахунка-фактури

Section titled “Фільтр даних рахунка-фактури”
/**
 * Filtruje dane faktury przed wysłaniem do API.
 *
 * @param array     $invoice_data Dane faktury w formacie dostawcy
 * @param \WC_Order $order        Zamówienie WooCommerce
 * @param string    $provider     Nazwa dostawcy
 */
apply_filters('polski_pro/accounting/invoice_data', array $invoice_data, \WC_Order $order, string $provider): array;

Приклад - додавання приміток до рахунка-фактури:

add_filter('polski_pro/accounting/invoice_data', function (
    array $invoice_data,
    \WC_Order $order,
    string $provider
): array {
    if ($provider === 'fakturownia') {
        $invoice_data['invoice']['description'] = sprintf(
            'Zamówienie internetowe #%s',
            $order->get_order_number()
        );
    }
    return $invoice_data;
}, 10, 3);

Адміністративна панель

Section titled “Адміністративна панель”

Статус синхронізації

Section titled “Статус синхронізації”

На списку замовлень WooCommerce додано стовпець “Рахунок-фактура”, що показує:

  • Зелена іконка - рахунок-фактура виставлений успішно
  • Жовта іконка - в процесі надсилання / retry
  • Червона іконка - помилка (натисніть, щоб побачити деталі)
  • Сіра іконка - не стосується (немає автоматичного виставлення)

Ручне виставлення

Section titled “Ручне виставлення”

На сторінці редагування замовлення, в панелі Рахунок-фактура, адміністратор може:

  1. Виставити рахунок-фактуру вручну (якщо автоматичне виставлення не спрацювало)
  2. Завантажити PDF рахунка-фактури
  3. Повторити надсилання рахунка-фактури
  4. Переглянути лог спроб та помилок

Вирішення проблем

Section titled “Вирішення проблем”

Рахунок-фактура не виставляється автоматично Перевірте, чи статус-тригер правильний. Переконайтеся, що Action Scheduler працює (WooCommerce > Статус > Заплановані дії). Перевірте лог помилок у WooCommerce > Статус > Логи.

Помилка “Unauthorized” при з’єднанні з API Перевірте дані автентифікації. Для wFirma перевірте, чи API key та secret з основного облікового запису (не субрахунку). Для Fakturownia переконайтеся, що субдомен правильний.

Дублікати рахунків-фактур Модуль захищає від дублікатів перевіркою мета _polski_pro_invoice_id перед виставленням. Якщо дублікати виникають, перевірте, чи інший плагін не запускає той самий хук замовлення.

Подальші кроки

Section titled “Подальші кроки”
Ця сторінка має виключно інформаційний характер і не є юридичною консультацією. Перед впровадженням зверніться до юриста. Polski for WooCommerce - це програмне забезпечення з відкритим кодом (GPLv2), що надається без гарантій.