Skip to content

How It Works

Architecture Overview

The Billecta Integration is a two-way synchronization system that automates data flow between Lime CRM and Billecta using event-based workflows:

  • Lime → Billecta: Data is sent via direct API calls in response to object creation, updates, and manual user-triggered actions
  • Billecta → Lime: Data is received via webhook events, which are processed and stored in Lime

This architecture ensures real-time synchronization of critical business data while maintaining data integrity through robust error handling and retry mechanisms. For more technical details, see the Billecta API documentation.

Data Flow: Lime to Billecta

When objects are created or modified in Lime:

  1. Decorators intercept the changes (if enabled for that object type)
  2. Changes are automatically sent to Billecta via API calls
  3. Billecta receives and updates its records
  4. The integration maintains Billecta ID references to link Lime objects with their Billecta counterparts

Alternatively, users can manually trigger synchronization actions through commands and endpoints at any time.

Data Flow: Billecta to Lime (Webhooks)

Billecta sends event notifications to Lime through a webhook system:

  1. Billecta detects a change (e.g., invoice paid, debtor updated)
  2. Billecta sends a webhook to Lime's webhook receiver endpoint
  3. Lime receives the webhook and extracts the payload data
  4. A handler processes the webhook and upserts (creates or updates) the corresponding object in Lime
  5. Only supported webhook events are processed; others are acknowledged but ignored

View all supported webhook events.

Error Handling & Reliability

The integration includes multiple layers of error handling to ensure no data is lost:

Webhook Processing Errors

When Lime cannot process a webhook (for example, a required related object doesn't exist in Lime):

  1. Lime returns an error to Billecta
  2. Billecta retries the webhook up to 5 times over 24 hours using exponential backoff
  3. Daily reconciliation job runs once per day to identify and retry webhooks that failed over the last 48 hours

This ensures temporary synchronization issues are automatically resolved without manual intervention.

Decorator API Errors

If an API call from Lime to Billecta fails, the error is logged and can be monitored through the integration monitoring dashboard. Users should review failed synchronizations and retry them manually if needed.

Product Row Types

The integration supports different types of rows on orders and invoices. Each row type corresponds to a different "product" type in Billecta's system:

Row Type Description Billecta Product Type Integrated
Standard A single article Service ✅ Yes
Package Multiple articles from the same article group in one line Package ✅ Yes
Message Text message or note related to another row (no pricing) N/A ❌ No

Note: Message rows are reference/informational rows in Lime and are not synchronized to Billecta as products.

User Interface & Web Components

Beyond automated synchronization, the integration provides a rich set of interactive web components and commands that allow users to manually control synchronization workflows and perform specialized operations. These are built as StencilJS web components and are exposed as actions in Lime CRM.

Component Categories

Data Synchronization Commands

These commands allow users to manually trigger synchronization of key objects:

  • Article Management: Upsert or delete articles in Billecta
  • Debtor Updates: Synchronize debtor information to Billecta
  • Creditor Updates: Update creditor data in Billecta
  • Attestation: Attest orders and order rows before sending to Billecta
  • Anonymization: Securely anonymize debtors in both systems

All synchronization commands include: - Confirmation dialogs to prevent accidental operations - Error notifications if synchronization fails - Integration with the monitoring system to track sync status

Payment Reconciliation

These components provide specialized interfaces for payment and credit management:

  • Swish Payment Requests: Send Swish payment requests directly from invoices with customizable messages
  • Manual Payment Registration: Register manual payments that occurred outside Billecta
  • Write-Off Payments: Record write-offs (uncollectible amounts) on invoices
  • Credit Invoice Application: Apply credit from one invoice to settle balances on other open invoices
  • Payment Reconciliation: Match unhandled or manually registered payments to their corresponding invoices

Invoice Management

Control invoice collection workflow directly from Lime CRM:

  • Dispute Invoice: Mark an invoice as disputed when a debtor contests the charge
  • Cancel Dispute: Remove disputed status when the dispute is resolved
  • Pause Invoice: Temporarily halt collection activities during negotiation or payment plans
  • Resume Paused Invoice: Resume normal collection after pause period ends

Debt Collection

Manage the full debt collection lifecycle for overdue invoices directly from Lime CRM:

  • Cancel Debt Collection: Stop an active debt collection process on an invoice
  • Postpone Next Event: Delay the next scheduled collection event by selecting a new date
  • Send to Bailiff: Escalate a debt collection case to a bailiff or request bailiff assistance
  • Send to Long-Term Surveillance: Move a case to long-term surveillance for ongoing monitoring

All debt collection commands require a valid Action Public ID linking the Lime object to the corresponding Billecta debt collection action. If the ID is missing, the operation will fail with a clear error message.

How Debt Collection Works

User-initiated actions follow a consistent flow:

  1. User triggers a debt collection command from a debtcollection object in Lime
  2. A confirmation dialog (or specialized dialog for postpone/bailiff) collects any required input
  3. The frontend sends a request to the corresponding backend endpoint
  4. The handler validates the object, calls the Billecta API, and updates the Lime object
  5. On failure, the error is stored on the object's billecta_error_message field and surfaced to the user

Webhook-driven updates keep Lime in sync automatically:

  1. When a debt collection state changes in Billecta, a DebtCollectionActionStateChanged webhook is sent to Lime
  2. The webhook handler upserts the debtcollection object with the latest state — including status, amounts (debt, current, interest, fees), interest details, next event, delivery method, and links to the related invoice, debtor, contract, and creditor

This two-way flow ensures that both manual actions and automatic state transitions are always reflected in Lime CRM.

Reporting Components

Advanced reporting dialogs for financial analysis and reconciliation:

  • Account Reconciliation Report: Compare invoices and transactions between Lime and Billecta
  • Accounts Receivable Report: View outstanding invoices and customer aging
  • Prepaid Payments Report: Track advance payments and prepaid amounts
  • Report Creator: Build custom reports by selecting fields, filtering conditions, and data sources

Event Monitoring

  • Event Log Dialog: View detailed logs of all Billecta webhook events received by Lime, including processing status and error messages

How Components Integrate with the Backend

When a user triggers a command or opens a dialog:

  1. Command Execution: The command handler extracts context from the current Lime object
  2. Dialog Display: A web component dialog opens with relevant data pre-populated
  3. User Input: Users interact with form fields, make selections, and confirm actions
  4. API Call: The dialog communicates with a backend endpoint
  5. Task Creation or Direct Processing: The endpoint either:
  6. Creates a background task for heavy operations (articles, debtors, creditors)
  7. Directly calls the Billecta API for lighter operations (payments, credits)
  8. Result Handling: Success/error notifications inform the user of the outcome

Adding Components to Your Views

To enable these components for your users:

  1. Open Lime Admin → Navigate to the relevant limeobject view configuration
  2. Add an Action → Select "Add action (unpromoted/promoted)" or "Add bulk action"
  3. Choose the Component → Search for the desired Billecta Integration command
  4. Configure → Set any required parameters (e.g., Swish message field mapping)
  5. Save → The action now appears in the view for users

For detailed configuration of each component, see Frontend Commands Documentation.