Logo
Sign Up

wFirma

Learn how to connect and configure wFirma for automated invoice generation.

wFirma is a Polish cloud-based accounting platform widely used by small businesses and freelancers in Poland. This guide covers both connecting your wFirma account and configuring it for optimal order processing.

Before You Start

Prerequisites

Part 1: Connecting wFirma

Step 1: Generate API Keys

  1. Log into your wFirma account at https://www.wfirma.pl
  2. Navigate to Settings → Security → Applications
  3. Generate new API keys:
    • Create an Access Key
    • Create a Secret Key
  4. Copy both keys for use in BrickInvoice
  5. Note your Company ID - Find this in your wFirma account settings

Step 2: Configure Connection

  1. Navigate to: /home/accounting/connect
  2. Select "wFirma" from the package dropdown
  3. Fill in your connection details:
    • Access Key: The access key you generated in Step 1
    • Secret Key: The secret key you generated in Step 1
  4. Click "Connect to wFirma" to verify the connection and save the configuration

Security Note

Your API keys are:

  • Encrypted before storage in the BrickInvoice database
  • Never shared with third parties
  • Used only for authenticated API calls to wFirma
  • Can be regenerated in wFirma settings if compromised

Part 2: Configuring wFirma Settings

After successfully connecting wFirma, you'll need to configure how orders are processed and mapped to your accounting system.

Invoice Line Item Structure

Each order creates an invoice with separate line items for different product types and customer locations. You'll need to configure Goods for:

Product Line Items (Standard Products)

  • LEGO parts and sets subject to standard VAT rates
  • Separate Goods based on customer location:
    • Domestic: Sales within Poland (standard VAT rate)
    • EU: Sales to other EU countries (standard VAT rate)
    • Export/Other: International sales outside the EU (0% VAT)
  • Each Good needs appropriate VAT code based on Polish tax rules

Margin Scheme Line Items (Second-hand Goods)

  • Products subject to margin scheme (special VAT treatment for used goods)
  • Separate Goods based on customer location:
    • Domestic: Margin scheme sales within Poland
    • EU: Margin scheme sales to other EU countries
    • Export/Other: Margin scheme sales outside the EU
  • VAT codes typically set to margin scheme rate
  • Note: Only applicable if you use margin scheme for second-hand goods

Handling Fees Line Items

  • Processing and handling costs
  • Single Good that applies to all regions
  • Set appropriate VAT code (usually same as standard rate)

Shipping Line Items

  • Shipping and delivery costs
  • Single Good that applies to all regions
  • Set appropriate VAT code (usually same as standard rate)

VAT Code Configuration

wFirma requires you to configure VAT codes for different transaction types:

Standard VAT:

  • Used for domestic and EU sales of standard products
  • In Poland, typically 23% for standard rate
  • Same VAT code applies to both domestic and EU sales

Export VAT:

  • Used for sales outside the EU
  • Typically 0% for export sales
  • Applied to all line items for non-EU customers

Margin Scheme VAT (Optional):

  • Special VAT treatment for second-hand goods
  • Only configure if you sell margin scheme products
  • Usually 0% or special margin rate

Goods Mapping

For each line item type and region, you'll map a wFirma Good:

Product Sales:

  • Domestic Product - For Polish customers (e.g., "LEGO Parts - Poland 23%")
  • EU Product - For other EU customers (e.g., "LEGO Parts - EU 23%")
  • Export Product - For non-EU customers (e.g., "LEGO Parts - Export 0%")

Margin Scheme Sales:

  • Domestic Margin - For Polish customers (e.g., "Margin Scheme - Poland")
  • EU Margin - For other EU customers (e.g., "Margin Scheme - EU")
  • Export Margin - For non-EU customers (e.g., "Margin Scheme - Export")

Other Items:

  • Shipping Good - For shipping costs (e.g., "Shipping Costs")
  • Handling Fees Good - For processing fees (e.g., "Handling Fees")

For example, if you don't want to seperate domestic and EU sales, you can choose the same good.

Configuration Tips

1. Create Goods in wFirma First

  • Go to wFirma → Goods/Products menu
  • Create Goods for each category and region
  • Set appropriate VAT codes for each good
  • Use clear, descriptive names

2. Use Consistent Naming

  • Example: "LEGO Parts - Domestic 23%", "Shipping"
  • Makes it easier to identify Goods in BrickInvoice configuration
  • Helps with bookkeeping and reporting

3. Review VAT Settings

  • Domestic (Poland): Usually 23% standard VAT rate
  • EU: Usually 23% standard VAT rate
  • Export: 0% for sales outside the EU
  • Margin Scheme: 0% or special margin rate (for second-hand goods only)

4. Test with Sample Order

  • Process one test order to verify configuration
  • Check created invoice in wFirma
  • Verify VAT amounts and good assignments are correct
  • Ensure customer information syncs properly

Part 3: Invoice Features

Automatic Invoice Creation

When orders are synchronized:

  1. Customer Sync: Customer data (contractor) is created or updated in wFirma
  2. Invoice Generation: Invoice is created with proper line item structure
  3. VAT Application: Correct VAT rates applied based on customer location and selected goods

Customer Management

BrickInvoice automatically manages customers (contractors) in your wFirma system:

  • Customer Creation: New contractors are automatically created based on order data
  • Customer Updates: Existing contractor information is updated when needed
  • Customer Search: System searches by BrickLink/Brick Owl username to avoid duplicates
  • Address Information: Billing addresses are mapped from order data

Troubleshooting

Connection Issues

"Failed to Connect to wFirma"

  • Invalid API keys: Verify your Access Key and Secret Key are correct
  • API access disabled: Check if API access is enabled in your wFirma account
  • Network issues: Verify your internet connection and wFirma service status

"Authentication Failed"

  • Keys revoked: Check if you regenerated keys in wFirma (old keys become invalid)
  • Account suspended: Verify your wFirma subscription is active
  • Permission issues: Ensure your wFirma user has API access permissions

Configuration Issues

"Goods Not Loading"

  • Check connection: Verify wFirma is still connected
  • Permissions: Ensure your wFirma user has access to Goods
  • Empty goods: Check that you have created goods in wFirma
  • Refresh: Try refreshing the configuration page

"Invoice Creation Failed"

  • Missing goods: Verify all required goods are configured
  • Invalid VAT: Selected good may have invalid or expired VAT code
  • Good settings: Verify Goods have correct VAT codes in wFirma
  • Customer data: Ensure order has complete customer information

Common Errors

"Good {id} not found"

  • Cause: Configured good was deleted or deactivated in wFirma
  • Solution: Update good mappings in BrickInvoice configuration

"VAT code not valid"

  • Cause: VAT code has expired validity period in wFirma
  • Solution: Update VAT codes in wFirma or select different goods with valid VAT codes

Disconnecting wFirma

To disconnect wFirma:

  1. Navigate to: /home/accounting/connect
  2. Click "Disconnect" button
  3. Confirm the disconnection
  4. Connection credentials are removed from BrickInvoice

Note: Existing invoices in wFirma are not affected by disconnecting. You can reconnect at any time with the same or new API keys.

Best Practices

VAT Configuration for Polish Businesses

Standard Setup:

  • Domestic (Poland): 23% standard VAT rate
  • EU Sales: 23% standard VAT rate (reverse charge for B2B handled by wFirma)
  • Export Sales: 0% (no VAT for non-EU sales)
  • Margin Scheme: 0% or margin rate (special treatment for second-hand goods)

Goods Organization

Recommended Goods Structure:

Goods in wFirma:
├── LEGO Parts - Domestic (23% VAT)
├── LEGO Parts - EU (23% VAT)
├── LEGO Parts - Export (0% VAT)
├── Margin - Domestic (0% Margin)
├── Margin - EU (0% Margin)
├── Margin - Export (0% Margin)
├── Shipping (23% VAT)
└── Handling Fees (23% VAT)

Next Steps

After configuring wFirma:

  1. Test integration - Process a few test orders
  2. Verify invoices - Check that draft invoices are created correctly in wFirma
  3. Review VAT treatment - Ensure VAT rates are applied correctly based on customer location
  4. Set up automation - Configure automated invoice generation schedules

Support

If you encounter issues with the wFirma integration:

  • Connection issues: Verify API keys
  • Configuration help: Review goods mappings and VAT settings
  • Invoice errors: Check wFirma goods setup and customer data
  • Technical support: Use the contact form with specific error details