PlugKit
Fakturownia Pro WCDocumentacionWP-CLI & REST API Reference

WP-CLI & REST API Reference

Fakturownia Pro for WooCommerce exposes a full WP-CLI command set and extends the WooCommerce REST API. Use these interfaces for server-side automation, CI/CD deployments, cron-based bulk processing, and ERP integrations.

WP-CLI commands running in terminal showing invoice creation output

WP-CLI Commands

All commands are under the wp fakturownia namespace. Commands require the plugin to be installed and activated and must be run from the WordPress installation root directory.

Connection and Status

wp fakturownia status

Displays the current plugin status: API connection health, HPOS mode, queue stats, and cron schedule.

wp fakturownia status

Example output:

Fakturownia Pro for WooCommerce v1.4.2
API Status:       Connected (account: My Company Sp. z o.o.)
HPOS Mode:        Active
Queue:            3 pending, 0 processing, 1 failed, 1843 completed
Cron:             Active (next: 2025-04-01 14:32:00)
Debug logging:    Off

Use this command after deployment or configuration changes to confirm the plugin is operating correctly.

wp fakturownia test-connection

Fires a live API call to Fakturownia and reports success or failure with the full HTTP response.

wp fakturownia test-connection

Useful in deployment pipelines where you want to confirm connectivity before orders start flowing:

# In a deployment script:
wp fakturownia test-connection || { echo "Fakturownia API connection failed"; exit 1; }

Invoice Operations

wp fakturownia invoice create <order-id>

Immediately generates an invoice for the specified WooCommerce order, bypassing the rule system.

# Generate invoice for order 1234
wp fakturownia invoice create 1234
 
# Generate a specific document type
wp fakturownia invoice create 1234 --type=receipt
wp fakturownia invoice create 1234 --type=proforma
wp fakturownia invoice create 1234 --type=correction
 
# Overwrite an existing invoice (regenerate)
wp fakturownia invoice create 1234 --force

| Flag | Description | |---|---| | --type=<type> | Document type: invoice (default), receipt, proforma, correction | | --force | Regenerate even if the order already has an invoice | | --no-email | Suppress the PDF attachment email that would otherwise fire | | --format=<format> | Output format: table (default), json, csv |

Example output:

Success: Invoice FS/2025/001 generated for order #1234.
Invoice ID: 12345678
Document type: invoice
Issue date: 2025-04-01
Gross amount: 299.00 PLN

wp fakturownia invoice get <order-id>

Retrieves the invoice data stored for an order without calling the Fakturownia API.

wp fakturownia invoice get 1234
wp fakturownia invoice get 1234 --format=json

Example output:

+-------------------+------------------+
| Field             | Value            |
+-------------------+------------------+
| Invoice ID        | 12345678         |
| Invoice number    | FS/2025/001      |
| Document type     | invoice          |
| Status            | generated        |
| Generated at      | 2025-04-01 14:30 |
| Fakturownia URL   | https://...      |
+-------------------+------------------+

wp fakturownia invoice download <order-id> [--output=<path>]

Downloads the invoice PDF for an order and saves it locally.

# Save to current directory as invoice-1234.pdf
wp fakturownia invoice download 1234
 
# Save to specific path
wp fakturownia invoice download 1234 --output=/tmp/invoices/order-1234.pdf

Useful for archiving PDFs outside of Fakturownia, for accounting systems that require local PDF storage, or for generating batch PDF packages.

Bulk Operations

wp fakturownia bulk-sync [--status=<status>] [--from=<date>] [--to=<date>] [--dry-run]

Generates invoices in bulk for orders that match the specified criteria and do not yet have an invoice. This is the primary command for retroactive invoice generation on historical orders.

# Generate invoices for all completed orders without invoices
wp fakturownia bulk-sync --status=completed
 
# Generate for a date range
wp fakturownia bulk-sync --status=processing --from=2025-01-01 --to=2025-03-31
 
# Preview what would be generated without actually creating invoices
wp fakturownia bulk-sync --status=completed --dry-run
 
# Generate for multiple statuses
wp fakturownia bulk-sync --status=processing,completed

| Flag | Description | |---|---| | --status=<status> | Comma-separated WooCommerce order statuses to process | | --from=<date> | Start date in YYYY-MM-DD format | | --to=<date> | End date in YYYY-MM-DD format | | --dry-run | Show what would be generated without creating documents | | --batch-size=<n> | Orders per batch (default: 25). Lower on shared hosting to avoid timeouts | | --delay=<ms> | Milliseconds to wait between API calls (default: 200). Prevents rate limiting | | --skip-existing | Skip orders that already have invoices (default: true) | | --format=<format> | Output: table, json, progress |

Bulk sync runs synchronously in the terminal session. For very large backlogs (10,000+ orders), use --batch-size=10 --delay=500 to reduce API load and add the queue to the background:

# Recommended for large backlogs:
nohup wp fakturownia bulk-sync --status=completed \
  --from=2024-01-01 --to=2024-12-31 \
  --batch-size=10 --delay=500 \
  --format=progress > /tmp/bulk-sync.log 2>&1 &
echo "Bulk sync started in background. PID: $!"

Then monitor progress:

tail -f /tmp/bulk-sync.log

wp fakturownia bulk-download [--status=<status>] [--output-dir=<path>]

Downloads PDFs for all invoiced orders matching the criteria and saves them to a local directory.

wp fakturownia bulk-download \
  --status=completed \
  --from=2025-01-01 --to=2025-03-31 \
  --output-dir=/var/www/html/wp-content/invoices/Q1-2025/

Files are named {order-id}-{invoice-number}.pdf. Existing files are skipped unless --force is passed.

Queue Management

wp fakturownia queue list [--status=<status>]

Lists jobs in the invoice generation queue.

# List all pending jobs
wp fakturownia queue list --status=pending
 
# List all failed jobs
wp fakturownia queue list --status=failed
 
# List all jobs in all statuses
wp fakturownia queue list

| Status | Meaning | |---|---| | pending | Waiting to be processed by the next cron run | | processing | Currently being processed (or stuck if the cron died mid-run) | | failed | Failed and retry count has not been exhausted | | failed_permanent | Failed and retry limit reached — requires manual intervention | | completed | Successfully generated |

wp fakturownia queue process [--limit=<n>]

Manually processes the queue, bypassing the WP-Cron schedule. Useful when WP-Cron is unreliable or disabled.

# Process all pending jobs
wp fakturownia queue process
 
# Process at most 50 jobs
wp fakturownia queue process --limit=50

Use this in a real system cron as a reliable alternative to WP-Cron:

# crontab entry: process queue every minute
* * * * * /usr/local/bin/wp fakturownia queue process --limit=100 \
  --path=/var/www/html --quiet

wp fakturownia queue retry <job-id> / wp fakturownia queue retry --all-failed

Retries a specific failed job or all permanently failed jobs.

# Retry a specific job
wp fakturownia queue retry 456
 
# Retry all permanently failed jobs (resets retry counter)
wp fakturownia queue retry --all-failed

After fixing the underlying issue (API token expired, Fakturownia account suspended, rate limit hit), use --all-failed to requeue everything that failed.

wp fakturownia queue clear --status=<status>

Removes jobs in the specified status from the queue. Use with caution.

# Remove all completed jobs older than 30 days (queue maintenance)
wp fakturownia queue clear --status=completed --older-than=30
 
# Remove all permanently failed jobs (after investigation)
wp fakturownia queue clear --status=failed_permanent

Settings

wp fakturownia settings get [<key>]

Reads plugin settings.

# Get all settings as JSON
wp fakturownia settings get --format=json
 
# Get a specific setting
wp fakturownia settings get api_timeout

wp fakturownia settings set <key> <value>

Updates a plugin setting from the command line. Useful in deployment pipelines for environment-specific configuration.

wp fakturownia settings set api_timeout 30
wp fakturownia settings set debug_logging false
wp fakturownia settings set max_retries 5

Setting the API token securely (avoid shell history):

# Read token from environment variable
wp fakturownia settings set api_token "$FAKTUROWNIA_API_TOKEN"

REST API Endpoints

Fakturownia Pro extends the WooCommerce REST API under /wp-json/fakturownia-pro/v1/.

Authentication

All REST endpoints require authentication. Use WooCommerce REST API keys:

  1. Go to WooCommerce → Settings → Advanced → REST API
  2. Click "Add Key"
  3. Set description, user (must have edit orders capability), and permissions (Read/Write for invoice operations)
  4. Copy the Consumer Key and Consumer Secret

Authenticate using HTTP Basic Auth:

curl -s https://yourstore.com/wp-json/fakturownia-pro/v1/invoices \
  -u "ck_your_consumer_key:cs_your_consumer_secret"

Or using query parameters (less secure — avoid in production logs):

curl -s "https://yourstore.com/wp-json/fakturownia-pro/v1/invoices?consumer_key=ck_xxx&consumer_secret=cs_xxx"

Endpoints Reference

GET /wp-json/fakturownia-pro/v1/invoices

Returns a list of invoices.

Query parameters:

| Parameter | Type | Description | |---|---|---| | per_page | integer | Results per page (default: 10, max: 100) | | page | integer | Page number | | order_id | integer | Filter to a specific WooCommerce order ID | | status | string | Filter by status: generated, failed, pending, skipped | | date_from | string | ISO 8601 date filter (generated after) | | date_to | string | ISO 8601 date filter (generated before) |

Example request:

curl -s "https://yourstore.com/wp-json/fakturownia-pro/v1/invoices?per_page=5&status=failed" \
  -u "ck_xxx:cs_xxx" | jq .

Example response:

[
  {
    "id": 1,
    "order_id": 1234,
    "invoice_id": "12345678",
    "invoice_number": "FS/2025/001",
    "document_type": "invoice",
    "status": "failed",
    "generated_at": null,
    "error_message": "Connection timeout after 15s",
    "retry_count": 2,
    "fakturownia_url": null
  }
]

GET /wp-json/fakturownia-pro/v1/invoices/{order_id}

Returns the invoice record for a specific order.

curl -s "https://yourstore.com/wp-json/fakturownia-pro/v1/invoices/1234" \
  -u "ck_xxx:cs_xxx"

POST /wp-json/fakturownia-pro/v1/invoices/{order_id}/generate

Generates (or regenerates) an invoice for a specific order.

Request body:

{
  "document_type": "invoice",
  "force": false,
  "send_email": true
}

Response (success):

{
  "success": true,
  "invoice_number": "FS/2025/042",
  "invoice_id": "98765432",
  "document_type": "invoice",
  "fakturownia_url": "https://mycompany.fakturownia.pl/invoices/98765432"
}

POST /wp-json/fakturownia-pro/v1/invoices/{order_id}/retry

Retries a failed invoice generation job for the specified order.

curl -s -X POST "https://yourstore.com/wp-json/fakturownia-pro/v1/invoices/1234/retry" \
  -u "ck_xxx:cs_xxx"

GET /wp-json/fakturownia-pro/v1/queue

Returns current queue statistics and optionally the queue contents.

curl -s "https://yourstore.com/wp-json/fakturownia-pro/v1/queue" \
  -u "ck_xxx:cs_xxx"

Response:

{
  "pending": 3,
  "processing": 0,
  "failed": 1,
  "failed_permanent": 0,
  "completed": 1843,
  "oldest_pending_age_minutes": 2
}

Automation Examples

Cron-Based Queue Processing (Recommended for DISABLE_WP_CRON Sites)

If your server has DISABLE_WP_CRON = true in wp-config.php, replace WP-Cron with a real system cron:

# /etc/cron.d/fakturownia-woocommerce
# Runs every minute, processes up to 100 queue items
* * * * * www-data /usr/local/bin/wp fakturownia queue process \
  --limit=100 --path=/var/www/html --quiet > /dev/null 2>&1

CI/CD: Verify Connection After Deployment

In your deployment pipeline, run a health check after deploying a new plugin version or configuration change:

#!/bin/bash
# post-deploy.sh
set -e
 
echo "Verifying Fakturownia Pro connection..."
wp fakturownia test-connection --path=/var/www/html
 
echo "Checking queue health..."
FAILED=$(wp fakturownia queue list --status=failed_permanent --format=count --path=/var/www/html)
if [ "$FAILED" -gt "0" ]; then
  echo "WARNING: $FAILED permanently failed jobs in queue"
  exit 1
fi
 
echo "Fakturownia Pro: OK"

ERP Integration: Poll for New Invoices

For an ERP system that needs to be notified when new invoices are generated, poll the REST API periodically:

#!/bin/bash
# Fetch invoices generated in the last 15 minutes
SINCE=$(date -u -d '15 minutes ago' '+%Y-%m-%dT%H:%M:%SZ')
 
curl -s "https://yourstore.com/wp-json/fakturownia-pro/v1/invoices?date_from=$SINCE&status=generated&per_page=100" \
  -u "$WC_API_KEY:$WC_API_SECRET" \
  | jq '.[] | {order_id: .order_id, invoice_number: .invoice_number, fakturownia_url: .fakturownia_url}'

Monthly Archive: Bulk PDF Download

At the start of each month, archive the previous month's invoice PDFs:

#!/bin/bash
# archive-invoices.sh
YEAR=$(date -d 'last month' '+%Y')
MONTH=$(date -d 'last month' '+%m')
FROM="${YEAR}-${MONTH}-01"
TO="${YEAR}-${MONTH}-$(cal -1 $(date -d 'last month' '+%B %Y') | awk 'NF{f=$NF} END{print f}')"
OUTPUT="/var/www/invoices/archive/${YEAR}-${MONTH}/"
 
mkdir -p "$OUTPUT"
 
wp fakturownia bulk-download \
  --status=completed \
  --from="$FROM" \
  --to="$TO" \
  --output-dir="$OUTPUT" \
  --path=/var/www/html
 
echo "Archive complete: $(ls "$OUTPUT" | wc -l) PDFs saved to $OUTPUT"

Next Steps

Edit this page on GitHub
Was this page helpful?

Documentacion

InstallationConfigurationInvoice RulesComplianceTroubleshootingChangelogCustomer Invoice PortalHPOS CompatibilityWP-CLI & REST API ReferenceDocument Settings