Preskočiť na obsah
Polski for WooCommerce

Účtovné integrácie

Modul prepája WooCommerce s poľskými fakturačnými systémami: wFirma, Fakturownia a iFirma. Faktúry sa odosielajú automaticky, s opakovaním pri chybách API.

Podporované systémy

Section titled “Podporované systémy”
SystémFormát APIVerzia APIAutentifikácia
wFirmaXMLv2API key + API secret
FakturowniaJSONv3API token
iFirmaJSONv1Login + API key (kľúč faktúr)

V danom momente môže byť aktívna iba jedna účtovná integrácia.

Konfigurácia

Section titled “Konfigurácia”

Prejdite do WooCommerce > Nastavenia > Polski PRO > Účtovníctvo.

Výber poskytovateľa

Section titled “Výber poskytovateľa”

Vyberte účtovný systém a zadajte autentifikačné údaje.

wFirma

Section titled “wFirma”
NastaveniePopis
API keyKľúč API z panelu wFirma
API secretSecret API
ID firmyIdentifikátor firmy vo wFirma
Séria faktúrSéria číslovania (napr. “FV”, “FVS”)

Fakturownia

Section titled “Fakturownia”
NastaveniePopis
SubdoménaNázov subdomény (napr. mojafirma.fakturownia.pl)
API tokenToken API z nastavení účtu
ID oddeleniaVoliteľne - ID oddelenia vystavujúceho faktúry
Jazyk faktúrypl alebo en

iFirma

Section titled “iFirma”
NastaveniePopis
LoginLogin do účtu iFirma
Kľúč API faktúrKľúč API na vystavovanie faktúr
Kľúč API predplatiteľaKľúč API predplatiteľa (na načítavanie dát)

Spoločné nastavenia

Section titled “Spoločné nastavenia”
NastaveniePredvolená hodnotaPopis
Automatické vystavovanieÁnoVystaviť faktúru automaticky po uhradení objednávky
Spúšťací stavprocessingStav objednávky spúšťajúci vystavenie faktúry
Typ dokumentuFaktúra s DPHFaktúra s DPH, Proforma faktúra, Účet
Pridať k e-mailuÁnoPriložiť PDF faktúry k e-mailu objednávky
Retry pri chybeÁnoOpakovať pokus pri chybe API
Maximálny počet pokusov5Limit opakovaných pokusov

Synchronizácia faktúr

Section titled “Synchronizácia faktúr”

Automatický priebeh

Section titled “Automatický priebeh”
  1. Objednávka WooCommerce zmení stav na processing (alebo iný nakonfigurovaný)
  2. Modul zozbiera dáta objednávky a namapuje ich na formát poskytovateľa
  3. Dáta sú odoslané asynchrónne na API účtovného systému
  4. Po úspešnom vytvorení sa ID faktúry uloží do metadát objednávky
  5. PDF faktúry sa stiahne a priloží k e-mailu zákazníka

Mapovanie dát

Section titled “Mapovanie dát”

Modul automaticky mapuje dáta objednávky WooCommerce na požadovaný formát API:

Dáta WooCommercewFirma (XML)Fakturownia (JSON)iFirma (JSON)
Názov firmy<contractor><name>buyer_nameKontrahent.Nazwa
IČ DPH<contractor><nip>buyer_tax_noKontrahent.NIP
Adresa<contractor><street>buyer_streetKontrahent.Ulica
Položky objednávky<invoicecontents>positionsPozycje
Sadzba DPH<vat_code>taxStawkaVat
Platobná metóda<paymentmethod>payment_typeSposobZaplaty

Formát XML (wFirma)

Section titled “Formát 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>

Formát JSON (Fakturownia)

Section titled “Formát 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"
  }
}

Mechanizmus retry

Section titled “Mechanizmus retry”

Exponential backoff

Section titled “Exponential backoff”

Keď API vráti chybu (HTTP 5xx, timeout, chyba pripojenia), modul automaticky naplánuje opakovaný pokus s exponenciálnym oneskorením:

PokusOneskorenieČas od prvého pokusu
1Okamžite0 s
230 s30 s
32 min2 min 30 s
48 min10 min 30 s
532 min42 min 30 s

Oneskorenie sa počíta vzorcom: delay = base_delay * 2^(attempt - 1), kde base_delay = 30 sekúnd.

Chyby nepodliehajúce retry

Section titled “Chyby nepodliehajúce retry”

Chyby klienta (HTTP 4xx) sa neopakujú automaticky, pretože indikujú problém s dátami, nie s API:

  • 400 Bad Request - neplatné dáta
  • 401 Unauthorized - chybný token API
  • 403 Forbidden - chýbajúce oprávnenia
  • 422 Unprocessable Entity - validácia dát

Tieto chyby sú logované a vyžadujú zásah administrátora.

Asynchrónne odosielanie

Section titled “Asynchrónne odosielanie”

Faktúry sa odosielajú asynchrónne pomocou WC_Action_Scheduler, čo znamená, že neblokujú proces skladania objednávky. Zákazník vidí potvrdenie objednávky ihneď a faktúra sa generuje na pozadí.

/**
 * 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);

Príklad - logovanie do externého systému:

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);

Hook chyby

Section titled “Hook chyby”
/**
 * 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);

Príklad - notifikácia administrátora:

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);

Filter dát faktúry

Section titled “Filter dát faktúry”
/**
 * 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;

Príklad - pridanie poznámok k faktúre:

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);

Administračný panel

Section titled “Administračný panel”

Stav synchronizácie

Section titled “Stav synchronizácie”

Na zozname objednávok WooCommerce je pridaný stĺpec “Faktúra” zobrazujúci:

  • Zelená ikona - faktúra úspešne vystavená
  • Žltá ikona - v procese odosielania / retry
  • Červená ikona - chyba (kliknite pre podrobnosti)
  • Sivá ikona - netýka sa (bez automatického vystavovania)

Ručné vystavovanie

Section titled “Ručné vystavovanie”

Na stránke úpravy objednávky, v paneli Faktúra, administrátor môže:

  1. Vystaviť faktúru ručne (ak automatické vystavovanie zlyhalo)
  2. Stiahnuť PDF faktúry
  3. Zopakovať odoslanie faktúry
  4. Zobraziť log pokusov a chýb

Riešenie problémov

Section titled “Riešenie problémov”

Faktúra sa nevystavuje automaticky Skontrolujte, či je spúšťací stav správny. Uistite sa, že Action Scheduler funguje (WooCommerce > Stav > Naplánované akcie). Skontrolujte log chýb v WooCommerce > Stav > Logy.

Chyba “Unauthorized” pri pripojení k API Overte autentifikačné údaje. V prípade wFirma skontrolujte, či API key a secret sú z hlavného účtu (nie podúčtu). Vo Fakturowni sa uistite, že subdoména je správna.

Duplikáty faktúr Modul chráni pred duplikátmi kontrolou meta _polski_pro_invoice_id pred vystavením. Ak duplikáty vznikajú, skontrolujte, či iný plugin nespúšťa ten istý hook objednávky.

Ďalšie kroky

Section titled “Ďalšie kroky”
Táto stránka slúži len na informačné účely a nepredstavuje právne poradenstvo. Pred implementáciou sa poraďte s právnikom. Polski for WooCommerce je open source softvér (GPLv2) poskytovaný bez záruky.