ERP & Accounting Integration

This guide is aimed at integrations that synchronise Provet Cloud financial data with an ERP or accounting system such as Microsoft Business Central or SAP. It covers the fields and patterns specific to that use case.

For invoice lifecycle, recording payments, credit notes, and the recommended baseline sync pattern, see Billing & Invoicing first. This guide builds on those fundamentals.

Invoice Document Numbers

ERP systems require a unique, human-readable document number. Provet invoices expose several number fields:

Field	Type	When set	Description
id	Integer	On creation	Database primary key. Always present, even on draft invoices. Stable and unique.
invoice_number	Integer or null	On finalization	Sequential number assigned when the invoice is finalized. null on draft invoices.
invoice_prefix	String	On finalization	Alphanumeric prefix configured per department (e.g. INV). Empty string if not configured.
reference_number	String or null	On finalization	Market-specific reference (e.g. Finnish bank reference number). null if not applicable.
additional_reference	String or null	On finalization	Secondary reference field used in some ERP workflows.

Recommended approach: construct the formatted document number as invoice_prefix + "-" + invoice_number (e.g. INV-1042). Fall back to id only for draft invoices where invoice_number is still null.

Note

invoice_number is assigned automatically during finalization. Do not attempt to set it. Use id for all internal references and foreign keys in your integration.

Payer Identification

The invoice record carries a full snapshot of the payer’s details at the time of invoicing. These fields do not update if the client record changes later, making them safe to use as the authoritative billing address for an ERP document.

Field	Description
payer_name	Client’s full name as invoiced
payer_organization_name	Company name for business clients
payer_vat_number	EU VAT registration number — use for reverse-charge B2B invoicing
payer_register_number	Company register number
payer_country_code	ISO 3166-1 alpha-2 code (e.g. GB, FI, US)
payer_street_address	Billing address line 1
payer_street_address_2	Billing address line 2
payer_zip_code	Postal code
payer_city	City
payer_state	State or region (US and similar markets)

Note

For EU B2B clients (customer_type=2 — EU company without VAT), payer_vat_number holds the VAT registration number used for intra-community reverse-charge transactions.

Chart-of-Accounts Mapping

Each invoice row carries an account_number field that maps the line item to a GL (general ledger) account in your chart of accounts. This value is configured on the item master data in Provet Cloud and flows through to the invoice row on finalization.

Fetching invoice rows:

GET /api/0.1/invoicerow/?invoice__is=<invoice_id>

To additionally retrieve the VAT group’s own GL account number (needed for posting VAT liability to a separate account), add the expose parameter:

GET /api/0.1/invoicerow/?invoice__is=<invoice_id>&expose_invoicerow_vat_group

This adds a invoicerow_vat_group object to each row containing:

Field	Description
title	VAT group name
percentage	VAT rate applied
account_number	GL account for VAT liability entries

The invoice_row_extra object is always present in the invoice row response. It contains the internal account number and other internal fields:

Field	Description
internal_account_number	Secondary or internal GL account code
internal_reporting_dimension_1	Internal reporting dimension 1
internal_reporting_dimension_2	Internal reporting dimension 2

Summary of account-related fields per invoice row:

Field	Expose parameter needed	Description
account_number	None (default)	Revenue GL account for this line item
invoicerow_vat_group.account_number	expose_invoicerow_vat_group	VAT liability GL account
invoice_row_extra.internal_account_number	None (always present)	Secondary or internal GL account code

Reporting Dimensions

Invoice rows carry up to three reporting dimensions used for multi-dimensional GL posting (cost centres, profit centres, projects, etc.). These values are configured per item in the Provet Cloud item master and flow through to the invoice row.

Fields on each invoice row:

• reporting_dimension_1

• reporting_dimension_2

• reporting_dimension_3

All are string values (or null). They are available in the default invoice row response with no additional expose parameter required.

Note

reporting_dimension_3 is always present in the invoice row response. If the feature is not active for the organisation, the field will be null rather than absent.

Financial Period Lock Date

Provet Cloud enforces a financial period lock to prevent backdating of invoices, payments, and credit notes. Before creating any date-sensitive financial document, check whether the target date falls before the lock.

GET /api/0.1/settings/department/<id>/

Key fields:

Field	Description
financial_period_lock_date	Earliest date allowed for any new invoice, payment, or credit note. null if no lock is set.
automatic_financial_period_lock_enabled	true if the lock advances automatically each month.
automatic_financial_period_lock_monthday	Day of the month on which the automatic lock advances (1–31).

Note

financial_period_lock_date can be updated via PATCH to /api/0.1/settings/department/<id>/ unless automatic_financial_period_lock_enabled is true, in which case the field is managed automatically and manual updates will be rejected with a validation error. Attempting to record a payment or create a credit note with a date before financial_period_lock_date will also result in a validation error.

Prepayment Reconciliation

Unallocated payments (prepayments) are recorded against a client before an invoice exists. They generate significant polling volume — use modified__gte filtering to fetch only changed records rather than retrieving all prepayments on every sync run.

Efficient delta poll:

GET /api/0.1/unallocatedpayment/?modified__gte=<last_sync_timestamp>

On each returned record, check fully_used and unused_amount to determine whether a remaining balance exists.

Tracking ERP sync status

The external_info object for storing your ERP system’s document reference is always included on unallocated payment records — no additional query parameter is required:

GET /api/0.1/unallocatedpayment/?modified__gte=<ts>

The external_info object contains:

Field	Description
external_id	Your ERP system’s document ID for this prepayment
metadata	Arbitrary key-value store for additional integration state

After posting a prepayment to your ERP, write back the ERP document ID to external_info.external_id. On subsequent sync runs, records where external_info.external_id is already set can be skipped.

Note

Consider subscribing to the Unallocated payment webhook trigger (trigger type 12) to eliminate polling entirely — it fires on both creates and modifications. See Webhooks for configuration details and List of Webhook Triggers for available events.

Pagination for Bulk Sync

Use the page_size query parameter to control how many records are returned per request (maximum 1000):

GET /api/0.1/invoice/?status__is=3&modified__gte=<ts>&page_size=200

The response includes count, num_pages, next, and previous fields alongside the results array.

Warning

Large page_size values count as multiple requests against your rate limit. The weight is calculated as ceil(requested_page_size / default_page_size). Prefer smaller page sizes combined with modified__gte filtering rather than requesting the maximum page size on each call.

For large datasets where the result offset would exceed 10,000 records, use date-range or ID-based filtering (id__gt=<last_seen_id>) rather than paginating through all records. Querying at very high offsets degrades performance significantly.

Rate Limiting for Bulk Sync

Rate limits are enforced per endpoint action on a rolling 60-second window. When the limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Approximate limits for the key ERP endpoints:

Endpoint	Action	Limit (requests / 60 s)
GET /api/0.1/invoice/	list	60
GET /api/0.1/invoice/<id>/	retrieve	250
GET /api/0.1/invoicerow/	list	varies
GET /api/0.1/unallocatedpayment/	list	200
GET /api/0.1/unallocatedpayment/<id>/	retrieve	800

Best practices for ERP sync jobs:

• Always read the Retry-After header on a 429 response and sleep for that duration before retrying.

• Use exponential backoff if 429 responses persist.

• Use modified__gte delta sync so each run fetches only changed records, not the full dataset.

• Prefer webhooks for high-frequency triggers (invoice finalized, payment recorded) to reduce polling load and avoid hitting list endpoint limits.

See Rate limit for the complete rate limiting reference including page-size weighting rules.