KSeF - National e-Invoice System

KSeF es una plataforma del Ministerio de Finanzas de Polonia para facturas estructuradas. El plugin prepara tu tienda para la integración con KSeF - detecta los pedidos que requieren factura de IVA, añade una columna de estado y hooks para la integración con sistemas de facturación.

Estado legal de KSeF

KSeF se encuentra en fase de implementación. El plugin no emite facturas en KSeF, pero facilita la integración con sistemas que sí lo hacen (por ejemplo, Fakturownia, iFirma, wFirma, InFakt).

Funciones principales del módulo KSeF:

1. Detección automática de pedidos con número NIP
2. Columna de estado KSeF en la lista de pedidos
3. Hooks para la integración con sistemas de facturación externos
4. Metadatos del pedido listos para transferir al sistema KSeF

Detección de pedidos con NIP

Cuando un cliente proporciona un NIP al realizar el pedido (el campo NIP forma parte del módulo Checkout), el plugin automáticamente:

1. Valida el formato del NIP (10 dígitos, verificación de la suma de control)
2. Marca el pedido como uno que requiere factura de IVA
3. Guarda el NIP en los metadatos del pedido
4. Opcionalmente obtiene los datos de la empresa desde la API de GUS/CEIDG

Validación del NIP

El plugin comprueba la validez del NIP en dos niveles:

• Formato - 10 dígitos, suma de control correcta (pesos: 6, 5, 7, 2, 3, 4, 5, 6, 7)
• Verificación en línea - comprobación opcional en la base de datos VIES (para NIP de la UE) o la API de GUS

Columna de estado KSeF

En la lista de pedidos (WooCommerce > Pedidos) aparece una columna KSeF con iconos de estado:

Icono	Estado	Descripción
Gris	No aplicable	Pedido sin NIP, no se requiere factura
Azul	Pendiente	Pedido con NIP, factura por emitir
Verde	Emitida	La factura ha sido emitida (estado establecido por hook)
Rojo	Error	Se produjo un problema al emitir la factura

Puedes filtrar los pedidos por estado KSeF, por ejemplo, mostrar solo los que están a la espera de factura.

Acciones masivas

En la lista de pedidos puedes marcar de forma masiva varios pedidos como “emitidos en KSeF”.

Hooks

polski/ksef/invoice_ready

Se activa cuando un pedido con NIP está pagado y listo para la emisión de la factura. El hook principal para la integración con sistemas de facturación.

/**
 * @param int      $order_id   WooCommerce order ID.
 * @param WC_Order $order      Order object.
 * @param string   $nip        Customer NIP number.
 * @param array    $invoice_data Invoice data (company name, address, NIP).
 */
add_action('polski/ksef/invoice_ready', function (int $order_id, WC_Order $order, string $nip, array $invoice_data): void {
    // Example: send data to the Fakturownia API
    $api_token = get_option('fakturownia_api_token');
    $account = get_option('fakturownia_account');

    $invoice_payload = [
        'invoice' => [
            'kind'             => 'vat',
            'number'           => null, // auto-numbering
            'sell_date'        => $order->get_date_paid()->format('Y-m-d'),
            'issue_date'       => current_time('Y-m-d'),
            'payment_type'     => 'transfer',
            'seller_name'      => get_option('woocommerce_store_name'),
            'buyer_name'       => $invoice_data['company_name'],
            'buyer_tax_no'     => $nip,
            'buyer_street'     => $invoice_data['address'],
            'buyer_city'       => $invoice_data['city'],
            'buyer_post_code'  => $invoice_data['postcode'],
            'positions'        => [],
        ],
    ];

    foreach ($order->get_items() as $item) {
        $invoice_payload['invoice']['positions'][] = [
            'name'       => $item->get_name(),
            'quantity'   => $item->get_quantity(),
            'total_price_gross' => $item->get_total() + $item->get_total_tax(),
            'tax'        => round(($item->get_total_tax() / $item->get_total()) * 100),
        ];
    }

    $response = wp_remote_post("https://{$account}.fakturownia.pl/invoices.json", [
        'body'    => wp_json_encode($invoice_payload),
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Token token=' . $api_token,
        ],
    ]);

    if (!is_wp_error($response) && wp_remote_retrieve_response_code($response) === 201) {
        $body = json_decode(wp_remote_retrieve_body($response), true);
        update_post_meta($order_id, '_ksef_status', 'issued');
        update_post_meta($order_id, '_ksef_invoice_id', $body['id'] ?? '');
    } else {
        update_post_meta($order_id, '_ksef_status', 'error');
    }
}, 10, 4);

polski/ksef/is_required

Filtro que permite determinar mediante código si un pedido requiere una factura KSeF.

/**
 * @param bool     $is_required Whether a KSeF invoice is required.
 * @param WC_Order $order       Order object.
 * @return bool
 */
add_filter('polski/ksef/is_required', function (bool $is_required, WC_Order $order): bool {
    // Example: require KSeF invoice for orders above 450 PLN
    if ($order->get_total() > 450) {
        return true;
    }

    return $is_required;
}, 10, 2);

Ejemplo - marcado automático del estado tras la integración

/**
 * Update KSeF status after receiving a response from the invoicing system.
 */
add_action('my_invoicing/invoice_created', function (int $order_id, string $ksef_number): void {
    $order = wc_get_order($order_id);
    if (!$order) {
        return;
    }

    $order->update_meta_data('_ksef_status', 'issued');
    $order->update_meta_data('_ksef_number', $ksef_number);
    $order->add_order_note(
        sprintf('Invoice issued in KSeF. KSeF number: %s', $ksef_number)
    );
    $order->save();
}, 10, 2);

Metadatos del pedido

El módulo KSeF guarda los siguientes metadatos en los pedidos:

Clave meta	Descripción
_billing_nip	Número NIP del cliente
_billing_company	Nombre de la empresa
_ksef_required	Si el pedido requiere factura (yes/no)
_ksef_status	Estado de la factura (pending, issued, error)
_ksef_number	Número de factura KSeF (tras la emisión)
_ksef_invoice_id	ID de la factura en el sistema externo

Configuración

Ajustes del módulo KSeF: WooCommerce > Ajustes > Polski > KSeF.

Opción	Descripción	Valor predeterminado
Activar el módulo KSeF	Activa la detección y el seguimiento	Sí
Validación del NIP en línea	Comprobar el NIP en la API de GUS/VIES	No
Obtención automática de datos de la empresa	Obtener datos de GUS tras introducir el NIP	No
Estado que activa el hook	Estado del pedido en el que se activa invoice_ready	processing

Solución de problemas

La columna KSeF no se muestra en la lista de pedidos Haz clic en “Opciones de pantalla” y marca la columna KSeF. Asegúrate de que el módulo esté activado en los ajustes.

El NIP no se guarda en el pedido Comprueba que el campo NIP esté activado en WooCommerce > Ajustes > Polski > Checkout. El campo debe estar activo para que los clientes puedan rellenarlo.

El hook invoice_ready no se activa Comprueba el ajuste “Estado que activa el hook”. De forma predeterminada, el hook se activa con el estado “Procesando”. Para estados personalizados, cambia esta opción.

Próximos pasos

• Informar de problemas: GitHub Issues
• Debates y preguntas: GitHub Discussions

Esta página tiene únicamente carácter informativo y no constituye asesoramiento legal. Consulta a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.