Skip to content
WooCommerce & WordPress Plugin Docs

Accounting integrations

El módulo conecta WooCommerce con los sistemas polacos de facturación: wFirma, Fakturownia e iFirma. Las facturas se envían automáticamente, con reintentos ante errores de la API.

Sistemas compatibles

Section titled “Sistemas compatibles”
SistemaFormato de APIVersión de APIAutenticación
wFirmaXMLv2API key + API secret
FakturowniaJSONv3API token
iFirmaJSONv1Login + API key (clave de facturas)

Solo puede estar activa una integración de contabilidad a la vez.

Configuración

Section titled “Configuración”

Vaya a WooCommerce > Ajustes > Polski PRO > Contabilidad.

Selección de proveedor

Section titled “Selección de proveedor”

Seleccione el sistema de contabilidad e introduzca las credenciales de autenticación.

wFirma

Section titled “wFirma”
AjusteDescripción
API keyClave API del panel de wFirma
API secretSecreto de la API
Company IDIdentificador de la empresa en wFirma
Invoice seriesSerie de numeración (p. ej. “FV”, “FVS”)

Fakturownia

Section titled “Fakturownia”
AjusteDescripción
SubdomainNombre del subdominio (p. ej. mojafirma.fakturownia.pl)
API tokenToken de API de los ajustes de la cuenta
Department IDOpcional - ID del departamento que emite las facturas
Invoice languagepl o en

iFirma

Section titled “iFirma”
AjusteDescripción
LoginLogin de la cuenta de iFirma
Invoice API keyClave API para emitir facturas
Subscriber API keyClave API del suscriptor (para obtener datos)

Ajustes comunes

Section titled “Ajustes comunes”
AjusteValor predeterminadoDescripción
Emisión automáticaSíEmitir la factura automáticamente tras el pago del pedido
Estado desencadenanteprocessingEstado del pedido que desencadena la emisión de la factura
Tipo de documentoFactura con IVAFactura con IVA, Factura proforma, Recibo
Añadir al correoSíAdjuntar el PDF de la factura al correo del pedido
Reintentar ante errorSíReintentar ante un error de la API
Número máximo de intentos5Límite de reintentos

Sincronización de facturas

Section titled “Sincronización de facturas”

Flujo automático

Section titled “Flujo automático”
  1. El pedido de WooCommerce cambia de estado a processing (u otro estado configurado)
  2. El módulo recopila los datos del pedido y los asigna al formato del proveedor
  3. Los datos se envían de forma asíncrona a la API del sistema de contabilidad
  4. Tras la creación correcta, el ID de la factura se guarda en el meta del pedido
  5. El PDF de la factura se descarga y se adjunta al correo del cliente

Asignación de datos

Section titled “Asignación de datos”

El módulo asigna automáticamente los datos del pedido de WooCommerce al formato de API requerido:

Datos de WooCommercewFirma (XML)Fakturownia (JSON)iFirma (JSON)
Nombre de la empresa<contractor><name>buyer_nameKontrahent.Nazwa
NIF (NIP)<contractor><nip>buyer_tax_noKontrahent.NIP
Dirección<contractor><street>buyer_streetKontrahent.Ulica
Líneas del pedido<invoicecontents>positionsPozycje
Tipo de IVA<vat_code>taxStawkaVat
Método de pago<paymentmethod>payment_typeSposobZaplaty

Formato XML (wFirma)

Section titled “Formato 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>

Formato JSON (Fakturownia)

Section titled “Formato 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"
  }
}

Mecanismo de reintentos

Section titled “Mecanismo de reintentos”

Retroceso exponencial

Section titled “Retroceso exponencial”

Cuando la API devuelve un error (HTTP 5xx, tiempo de espera agotado, error de conexión), el módulo programa automáticamente un reintento con retroceso exponencial:

IntentoRetardoTiempo desde el primer intento
1Inmediatamente0 s
230 s30 s
32 min2 min 30 s
48 min10 min 30 s
532 min42 min 30 s

El retardo se calcula con la fórmula: delay = base_delay * 2^(attempt - 1), donde base_delay = 30 seconds.

Errores no sujetos a reintento

Section titled “Errores no sujetos a reintento”

Los errores del cliente (HTTP 4xx) no se reintentan automáticamente porque indican un problema con los datos, no un problema de la API:

  • 400 Bad Request - datos no válidos
  • 401 Unauthorized - token de API incorrecto
  • 403 Forbidden - permisos insuficientes
  • 422 Unprocessable Entity - validación de datos

Estos errores se registran y requieren la intervención del administrador.

Envío asíncrono

Section titled “Envío asíncrono”

Las facturas se envían de forma asíncrona mediante WC_Action_Scheduler, lo que significa que no bloquean el proceso de realización del pedido. El cliente ve la confirmación del pedido de inmediato, y la factura se genera en segundo plano.

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

Ejemplo - registro en un sistema externo:

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 de error

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

Ejemplo - notificación al administrador:

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

Filtro de datos de la factura

Section titled “Filtro de datos de la factura”
/**
 * 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;

Ejemplo - añadir notas a la factura:

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

Panel de administración

Section titled “Panel de administración”

Estado de sincronización

Section titled “Estado de sincronización”

En la lista de pedidos de WooCommerce se añade una columna “Factura” que muestra:

  • Icono verde - factura emitida correctamente
  • Icono amarillo - envío en curso / reintento
  • Icono rojo - error (haga clic para ver los detalles)
  • Icono gris - no aplicable (sin emisión automática)

Emisión manual

Section titled “Emisión manual”

En la página de edición del pedido, en el panel Factura, el administrador puede:

  1. Emitir una factura manualmente (si la emisión automática falló)
  2. Descargar el PDF de la factura
  3. Reintentar el envío de la factura
  4. Ver el registro de intentos y errores

Resolución de problemas

Section titled “Resolución de problemas”

La factura no se emite automáticamente Compruebe si el estado desencadenante es correcto. Asegúrese de que Action Scheduler esté en ejecución (WooCommerce > Estado > Acciones programadas). Consulte el registro de errores en WooCommerce > Estado > Registros.

Error “Unauthorized” al conectar con la API Verifique las credenciales de autenticación. En el caso de wFirma, compruebe si el API key y el secret son de la cuenta principal (no de una subcuenta). En Fakturownia, asegúrese de que el subdominio sea correcto.

Facturas duplicadas El módulo evita los duplicados comprobando el meta _polski_pro_invoice_id antes de emitir. Si se producen duplicados, compruebe si otro plugin está desencadenando el mismo hook del pedido.

Próximos pasos

Section titled “Próximos pasos”
Esta página tiene únicamente fines informativos y no constituye asesoramiento jurídico. Consulte a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.