Fatture in Cloud

Learn how to connect and configure Fatture in Cloud for automated invoice generation.

Before You Start
Email Pre-registration
Connecting Fatture in Cloud
Configuring Fatture in Cloud Settings
Invoice Features
Fee Sync
Troubleshooting
Disconnecting Fatture in Cloud
Best Practices
Next Steps
Support

Before You Start

Prerequisites

Active Fatture in Cloud subscription
Admin access to your Fatture account
Completed settings configuration
Connected BrickLink and/or BrickOwl stores

What You'll Need

Email Pre-registration - Contact BrickInvoice support first (required)
Fatture in Cloud Account - You'll authenticate using OAuth 2.0 (no API keys needed)
Company Access - Permission to create customers and invoices

Part 1: Email Pre-registration (Required)

Important: Register Before Connecting

Before you can connect to Fatture in Cloud, you must first register your email address with BrickInvoice support. This is required because Fatture uses a developer environment that requires pre-approved access.

Registration Steps

Identify your Fatture email - Use the same email address you use to log into Fatture in Cloud
Contact BrickInvoice - Visit the BrickInvoice contact form and submit:
- Your email address used for Fatture in Cloud
Wait for confirmation - BrickInvoice support will add your email to the developer environment
Proceed with connection - Once confirmed, you can connect your account

Why Pre-registration?

Fatture in Cloud requires developers to whitelist user email addresses in their developer environment. This security measure ensures only authorized users can connect their Fatture accounts to BrickInvoice.

Note: This is a one-time requirement. Once registered, you can connect and disconnect without needing to register again.

Part 2: Connecting Fatture in Cloud

Step 1: Initiate OAuth Connection

Navigate to: /home/accounting/connect
Select "Fatture in Cloud" from the package dropdown
Read the pre-registration notice - Ensure you've completed email registration
Click "Connect to Fatture in Cloud" - you'll be redirected to Fatture
Log into your Fatture account using your registered email
Select the company you want to connect (if you have multiple)
Authorize BrickInvoice to access your Fatture data

Step 2: Complete Connection

After authorizing:

You'll be redirected back to BrickInvoice
The connection will be verified and saved automatically
You'll be prompted to select your company for invoicing

Security Note

BrickInvoice uses OAuth 2.0 authentication, which means:

Your Fatture in Cloud credentials are never stored by BrickInvoice
Access tokens are encrypted in the database
Tokens automatically refresh when needed
You can revoke access anytime from Fatture settings

Part 3: Configuring Fatture in Cloud Settings

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

Understanding Fatture Products

Fatture in Cloud uses Products to represent items on invoices. Unlike some accounting systems that use general ledger accounts directly, Fatture requires you to:

Create Products in Fatture first (via Prodotti menu)
Configure each Product with appropriate VAT rates
Map Products in BrickInvoice to different transaction types and regions

Each product in Fatture includes:

Product name and description
Price information
VAT rate (automatically applied to invoice line items)
Category and notes

Company Selection

After connecting, you'll select which Fatture company to use for invoicing:

View available companies - All companies you have access to will be listed
Select primary company - Choose the company where invoices should be created
Save selection - This company will be used for all invoice creation

You can change the selected company later in the configuration settings.

General Settings

Invoice Description:

Description text that appears on each invoice
Placeholders: You can use the following placeholders for dynamic content:
- {order_number} - Automatically replaced with the order number including source prefix (e.g., "BL 123456" or "BO 789012")
- {payment_method} - Automatically replaced with the payment method used (e.g., "PayPal" or "Stripe")
- Example: "Order {order_number} - {payment_method}" becomes "Order BL 123456 - PayPal"

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 Products for:

Product Line Items (Standard Products)

LEGO parts and sets subject to standard VAT rates
Separate Products based on customer location:
- Domestic: Sales within Italy (e.g., 22% VAT)
- EU: Sales to other EU countries (e.g., 22% VAT for standard products)
- Export/Other: International sales outside the EU (e.g., 0% VAT)
Each Product needs appropriate VAT rate based on your tax rules
Description: You can customize the description using placeholders:
- {order_number} - The order number (e.g., "123456")
- {source} - The order source (e.g., "BrickLink" or "BrickOwl")
- {payment_method} - The payment method (e.g., "PayPal")

Margin Scheme Line Items (Second-hand Goods)

Products subject to margin scheme (special VAT treatment for used goods)
Separate Products based on customer location:
- Domestic: Margin scheme sales within Italy (0% or margin scheme rate)
- EU: Margin scheme sales to other EU countries (0% or margin scheme rate)
- Export/Other: Margin scheme sales outside the EU (0% VAT)
VAT rates typically set to 0% or margin scheme rate
Note: Only applicable if you use margin scheme for second-hand goods
Description: You can customize the description using placeholders:
- {order_number} - The order number (e.g., "123456")
- {source} - The order source (e.g., "BrickLink" or "BrickOwl")
- {payment_method} - The payment method (e.g., "PayPal")

Handling Fees Line Items

Processing and handling costs
Single Product that applies to all regions
Set appropriate VAT rate (usually same as standard rate)
Description: You can customize the description using placeholders:
- {order_number} - The order number (e.g., "123456")
- {source} - The order source (e.g., "BrickLink" or "BrickOwl")
- {payment_method} - The payment method (e.g., "PayPal")

Shipping Line Items

Shipping and delivery costs
Single Product that applies to all regions
Set appropriate VAT rate (usually same as standard rate)
Description: You can customize the description using placeholders:
- {order_number} - The order number (e.g., "123456")
- {source} - The order source (e.g., "BrickLink" or "BrickOwl")
- {payment_method} - The payment method (e.g., "PayPal")

Product Mapping

For each line item type and region, you'll map a Fatture Product:

Product Sales:

Domestic Product - For Italian customers (e.g., "LEGO Parts - Italy 22%")
EU Product - For other EU customers (e.g., "LEGO Parts - EU 22%")
Export Product - For non-EU customers (e.g., "LEGO Parts - Export 0%")
B2B Product (optional) - For B2B orders with reverse charge (e.g., "LEGO Parts - B2B 0%"). Only visible when B2B VAT Exempt is enabled in Order Sync settings.

Margin Scheme Sales:

Domestic Margin - For Italian customers (e.g., "Margin Scheme - Italy")
EU Margin - For other EU customers (e.g., "Margin Scheme - EU")
Export Margin - For non-EU customers (e.g., "Margin Scheme - Export")
B2B Margin (optional) - For B2B margin scheme orders with reverse charge. Only visible when B2B VAT Exempt is enabled.

Other Items:

Shipping Product - For shipping costs (e.g., "Shipping Costs")
Shipping Product (B2B) (optional) - For B2B shipping with reverse charge. Only visible when B2B VAT Exempt is enabled.
Handling Fees Product - For processing fees (e.g., "Handling Fees")
Handling Fees Product (B2B) (optional) - For B2B handling fees with reverse charge. Only visible when B2B VAT Exempt is enabled.

B2B Products: When an order is detected as B2B exempt, BrickInvoice uses the configured B2B Product for that line item instead of the regular domestic/EU/export product. The B2B Product should have a 0% or reverse charge VAT rate in Fatture.

Subject Configuration

The Subject field appears on Fatture invoices as an optional reference text:

This is a fixed text field (not variable/dynamic)
Enter a description like "BrickInvoice Order" or "LEGO Parts Order"
Can be left empty if you don't need a subject line
This text will appear on all invoices created from BrickInvoice

Configuration Tips

1. Create Products in Fatture First

Go to Fatture in Cloud → Prodotti (Products)
Create Products for each category and region
Set appropriate VAT rates for each product
Use clear, descriptive names

2. Use Consistent Naming

Example: "LEGO Parts - Domestic 22%", "Shipping - EU 0%"
Makes it easier to identify Products in BrickInvoice configuration
Helps with bookkeeping and reporting

3. Review VAT Settings

Domestic (Italy): Usually 22% standard VAT rate
EU: Usually 22% standard VAT rate (same as domestic for standard products)
Export: 0% for sales outside the EU
Margin Scheme: 0% or special margin scheme rate (for second-hand goods only)

4. Test with Sample Order

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

Part 4: Invoice Features

Automatic Invoice Creation

When orders are synchronized:

Customer Sync: Customer data is created or updated in Fatture
Invoice Generation: Invoice is created with proper line item structure
VAT Application: Correct VAT rates applied based on customer location and product
Invoice Number: Fatture automatically assigns an invoice number
Invoice URL: Direct link to view invoice in Fatture is provided

Customer Management

BrickInvoice automatically manages customers (clienti) in your Fatture system:

Customer Creation: New customers are automatically created based on order data
Customer Updates: Existing customer information is updated when needed
Customer Search: System searches by company/customer name to avoid duplicates
Address Information: Billing addresses are mapped from order data

Invoice URLs

BrickInvoice automatically generates direct links to view invoices in your Fatture interface. These URLs allow you to quickly navigate to the invoice in Fatture for review or further processing.

Example URL format: https://secure.fattureincloud.it/invoices/view/{invoice_id}

Part 5: Fee Sync

Payment Registration

Automatic Payment Registration: When an order paid via Stripe or PayPal is synced to Fatture in Cloud, the payment is automatically registered as a cashbook entry (prima nota) against the invoice.

Supported Payment Methods:

Stripe: Automatically registers Stripe payments
PayPal: Automatically registers PayPal payments

Note: Other payment methods (bank transfer, cash, etc.) are not automatically registered. These invoices will remain unpaid in Fatture and need to be manually marked as paid.

Configuration Required:

Enable per Payment Method: Enable payment registration for Stripe and/or PayPal
Payment Account per Source: Configure which Fatture payment account (conto) to use for payments
- BrickLink: Select your PayPal or Stripe payment account for BrickLink payments
- BrickOwl: Select your PayPal or Stripe payment account for BrickOwl payments

Payment Reference Format: Payment references are automatically generated as: Payment {source}_{order_number}

Example: Payment bricklink_12345678
Example: Payment brickowl_98765432

PayPal Fee Sync

Automatic PayPal Fee Registration: When PayPal orders are synced, the PayPal transaction fees are automatically registered as cashbook expenses in Fatture in Cloud.

Configuration Required:

Enable PayPal Fee Sync: Enable the fee sync feature
PayPal Connection: Active PayPal API credentials
Payment Account per Source: Which payment account (conto) the PayPal fee is booked from
- BrickLink: Select your PayPal payment account for BrickLink fees
- BrickOwl: Select your PayPal payment account for BrickOwl fees

Fee Reference Format: Fee references are automatically generated as: PayPal fee {source}_{order_number}

Example: PayPal fee bricklink_12345678
Example: PayPal fee brickowl_98765432

Benefits:

Accurate fee tracking per marketplace
Automatic expense categorization
No manual fee entry required
Proper financial reconciliation

Stripe Fee Sync

Automatic Stripe Fee Registration: When Stripe orders are synced, the Stripe transaction fees are automatically registered as cashbook expenses in Fatture in Cloud.

Important: This uses your own Stripe account, not the BrickLink or Brick Owl marketplace Stripe environment. You need to connect your Stripe account separately via Payments → Stripe before enabling this feature.

Configuration Required:

Stripe Connection: Connect your Stripe account via the Stripe connection page
Enable Stripe Fee Sync: Enable the fee sync feature in your accounting configuration
Payment Account per Source: Which payment account (conto) the Stripe fee is booked from
- BrickLink: Select your Stripe payment account for BrickLink fees
- BrickOwl: Select your Stripe payment account for BrickOwl fees

Fee Reference Format: Fee references are automatically generated as: Stripe fee {source}_{order_number}

Example: Stripe fee bricklink_12345678
Example: Stripe fee brickowl_98765432

Benefits:

Accurate Stripe fee tracking per marketplace
Automatic expense categorization
No manual fee entry required
Proper financial reconciliation

Troubleshooting

Connection Issues

"Email Not Registered" or "Connection Failed"

Cause: Your email hasn't been added to BrickInvoice's Fatture developer environment
Solution: Contact support@brickinvoice.com with your Fatture email address
Wait time: Usually processed within 24 hours

"Failed to Connect to Fatture"

Browser popup blockers: Disable for BrickInvoice domain
Invalid company: Ensure you selected the correct Fatture company
Wrong email: Verify you're using the registered email address

"Token Expired" or "Authentication Failed"

Automatic refresh: Tokens refresh automatically, but connection may have been revoked
Reconnect: Go to accounting settings and reconnect Fatture
Revoked access: Check if you revoked BrickInvoice access in Fatture settings

Configuration Issues

"Products Not Loading"

Check connection: Verify Fatture is still connected
Permissions: Ensure your Fatture user has access to Products
Empty products: Check that you have created products in Fatture
Refresh: Try refreshing the configuration page

"Company Not Found"

Access rights: Verify you have access to the company in Fatture
Company status: Ensure company is active in Fatture
Reconnect: Try disconnecting and reconnecting your account

"Invoice Creation Failed"

Missing products: Verify all required products are configured
Invalid VAT: Selected product may have invalid VAT rate
Product settings: Verify Products have correct VAT assignments in Fatture
Customer data: Ensure order has complete customer information

Common Errors

"No company selected"

Cause: Company ID not configured in settings
Solution: Go to accounting configuration and select your company

"Product {id} not found"

Cause: Configured product was deleted or made inactive in Fatture
Solution: Update product mappings in BrickInvoice configuration

"VAT rate mismatch"

Cause: Product's VAT rate in Fatture doesn't match expected rate
Solution: Review and update VAT rates in Fatture for configured products

Disconnecting Fatture in Cloud

To disconnect Fatture:

Navigate to: /home/accounting/connect
Click "Disconnect" button
Confirm the disconnection
Access is revoked both in BrickInvoice and Fatture

Note: Existing invoices in Fatture are not affected by disconnecting. Your email remains registered for future connections.

Best Practices

VAT Configuration for Italian Businesses

Standard Setup:

Domestic (Italy): 22% standard VAT rate
EU Sales: 22% standard VAT rate (same as domestic for standard products)
Export Sales: 0% (no VAT for non-EU sales)
Margin Scheme: 0% (special treatment for second-hand goods)

Product Organization

Recommended Product Structure:

Products in Fatture:
├── LEGO Parts - Domestic (22% VAT)
├── LEGO Parts - EU (22% VAT)
├── LEGO Parts - Export (0% VAT)
├── Margin - Domestic (0% Margin)
├── Margin - EU (0% Margin)
├── Margin - Export (0% Margin)
├── Shipping (22% VAT)
└── Handling Fees (22% VAT)

Next Steps

After configuring Fatture in Cloud:

Test integration - Process a few test orders
Verify invoices - Check that invoices are created correctly in Fatture
Review VAT treatment - Ensure VAT rates are applied correctly based on customer location
Set up automation - Configure automated invoice generation schedules
Monitor integration - Regularly check that orders sync properly

Support

If you encounter issues with the Fatture in Cloud integration:

Pre-registration: Use the BrickInvoice contact form
Connection issues: Verify email registration and Fatture credentials
Configuration help: Review product mappings and VAT settings
Invoice errors: Check Fatture product setup and customer data
Technical support: Use the contact form with specific error details

Fatture in Cloud

Learn how to connect and configure Fatture in Cloud for automated invoice generation.

Table of Contents

Before You Start

Prerequisites

What You'll Need

Part 1: Email Pre-registration (Required)

Important: Register Before Connecting

Registration Steps

Why Pre-registration?

Part 2: Connecting Fatture in Cloud

Step 1: Initiate OAuth Connection

Step 2: Complete Connection

Security Note

Part 3: Configuring Fatture in Cloud Settings

Understanding Fatture Products

Company Selection

General Settings

Invoice Line Item Structure

Product Line Items (Standard Products)

Margin Scheme Line Items (Second-hand Goods)

Handling Fees Line Items

Shipping Line Items

Product Mapping

Subject Configuration

Configuration Tips

Part 4: Invoice Features

Automatic Invoice Creation

Customer Management

Invoice URLs

Part 5: Fee Sync

Payment Registration

PayPal Fee Sync

Stripe Fee Sync

Troubleshooting

Connection Issues

"Email Not Registered" or "Connection Failed"

"Failed to Connect to Fatture"

"Token Expired" or "Authentication Failed"

Configuration Issues

"Products Not Loading"

"Company Not Found"

"Invoice Creation Failed"

Common Errors

"No company selected"

"Product {id} not found"

"VAT rate mismatch"

Disconnecting Fatture in Cloud

Best Practices

VAT Configuration for Italian Businesses

Product Organization

Next Steps

Support