Transaction

Definition of transaction

A transaction is an action performed on a document, such as its sending or reception. This action may include validation, registration, and tracking of the document to ensure that established requirements are met and that the document is correctly transferred.

We consider a document

• Invoice (simplified, self-invoice, regular)
• Quote
• Order
• Delivery note
• Tax report

Billable transactions

Any of the following is considered a billable transaction:

• Send a document.
• Receive a document.
• Transform a document for download (API and APP).

Exceptions

• Downloading a PDF copy of an issued invoice is not considered billable.
• State changes are not considered documents; therefore, actions on state changes are not counted as transactions.
• The event error_sending: Sending error (Status: Error, Corner C2) is not considered a transaction.

Specific cases

• Tax report enabled: When an invoice is sent and the tax report is enabled, the corresponding report is automatically generated and sent. Whether that report is billed depends on the tax authority — see Billing per tax authority below.
• SDI case: When a cross-border invoice is sent, we charge for the sending of the invoice to the tax authority. In this case, the tax report is the invoice sent to the tax authority.

Billing per tax authority

Enabling automatic tax reporting does not have the same cost in every regime. Three of them bill one transaction per report, and the other two do not bill the report at all or bill it in aggregate:

Tax authority	Billing of the tax report	Effect per invoice
Verifactu	One transaction per tax report	Sending an invoice generates two billable transactions
TicketBAI	One transaction per tax report	Sending an invoice generates two billable transactions
SII	One transaction per tax report	Sending an invoice generates two billable transactions
KSeF	Not billed	No additional transaction
DGFiP	One transaction per ledger	No transaction per invoice, one per aggregated declaration

Ledgers. For Verifactu and TicketBAI, a ledger counts as many transactions as it contains records: a ledger with 10 records counts as 10 individual transactions. This does not apply to the other two authorities that use ledgers. For DGFiP the whole ledger counts as a single transaction, and for KSeF the ledger is not billed at all.

DGFiP F10 declarations are grouped per civil period according to the declarant’s VAT regime. Each grouped declaration generates a single transaction, whatever the number of invoices it contains: a declaration with 200 invoices counts the same as one with two.

API endpoints that generate a billable transaction

• Send invoice
• Create an issued invoice (with send_after_import: true)
• Import an invoice from a file (with send_after_import: true)
• Get an invoice with a specific document type (except in PDF format)
• Generate a tax report from an Invoice
• Create a Tax Report
• Import a Tax Report
• Annulate a tax report

Note: the four tax-report endpoints above are billed according to the tax authority. See Billing per tax authority.

Examples of other API endpoints that currently do not generate a billable transaction

• Create an issued invoice (with send_after_import: false)
• Import an invoice from a file (with send_after_import: false)
• Switch invoice state
• Validation
• Mark an invoice as acknowledged
• Lookup (Directory)

Transaction counters by document type

Transactions can be registered by counting any of the following events (1 event = 1 transaction).

List of events

• success_sending: Successful sending (Status: Sent, Corner C2)
• success_clearing: Clearance process completed successfully (ZATCA)
• error_clearing: Error during the clearance process (ZATCA)
• notification_c2_state_downloaded: Invoice downloaded. Corresponds to corner C2. When the transport is “Download” and the user clicks the Issue and Download button (Status: Downloaded)

Outgoing

Issued invoices of different types (sendable_type: Invoice)

API endpoints:

• Send invoice
• Import invoice (with parameter send_after_import: true)

Events:

• success_sending
• error_sending

Non-API related events:

• notification_c2_state_downloaded

Quotes (sendable_type: Quote)

API endpoints: Quotes cannot be sent via API.

Non-API related events:

• success_sending
• error_sending

Delivery notes (sendable_type: DespatchAdvice)

API endpoints: Delivery notes cannot be sent via API.

Non-API related events:

• success_sending
• error_sending

Orders (sendable_type: Order)

API endpoints:

• Mark as processed (this endpoint does not generate any transaction)

Non-API related events: When accepting or rejecting an order (UI only), an order response is sent that generates one of these events:

• success_sending
• error_sending

Tax reports (sendable_type: TaxReport)

API endpoints:

• Send invoice (if the invoice requires the tax report)
• Create tax report
• Import tax report
• Modify tax report
• Annulate tax report
• Annulate tax report (legacy)

Events:

• success_sending
• error_sending
• success_clearing
• error_clearing

Notes: When the tax_authority is Verifactu or TicketBAI (Bizkaia), in addition to sending the TaxReport, a Ledger is also sent.

Ledger

API endpoints: Same as those for TaxReport.

Events:

• success_sending
• error_sending

Incoming

Received invoices of different types (sendable_type: Invoice)

A transaction is generated when a “received invoice” is received. When the received invoice is manually created or imported via the platform, it is not counted as a transaction.

API endpoints:

• Import invoice (with issued=false, corresponding to from_net: 'uploaded')

Orders (sendable_type: Order)

API endpoints: Orders cannot be generated or sent via API.

Notes: A transaction is generated when an order is received. When imported via the platform, it is not counted as a transaction.

View_as

Calling GET /invoices/{id}/as/{document_type_code} generates a new billable transaction whenever the document is freshly produced from the underlying invoice data. The following values of document_type_code are exceptions and do not generate a transaction:

• original — returns the document exactly as it was originally submitted or imported, served from storage. No regeneration takes place.
• legal — returns the archived legal document (e.g. the signed and timestamped version) as stored. No regeneration takes place.
• pdf.invoice and pdf.invoice.signed — although the PDF is rendered on demand, downloading a PDF copy of an issued invoice is not considered billable.

For any other value (e.g. xml.ubl.invoice.bis3, xml.facturae.3.2.2, etc.), a new transaction is registered on every call, because the document is regenerated from the database object.

curl --request GET \
  --url https://api.b2brouter.net/invoices/{id}/as/legal \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

curl --request GET \
  --url https://api.b2brouter.net/invoices/{id}/as/xml.ubl.invoice.bis3 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Note: If you only need to retrieve the document you already sent or received, use /as/legal or /as/original instead.

How to monitor your transactions usage

If you are a Partner or Reseller, you can monitor the transaction consumption of each integration group directly from the B2Brouter portal.

When you provision an integration group, whether because you manage a single business group or operate as an eDocSync, the most efficient way to monitor total and per-account transaction usage is through the following API endpoint: GET /accounts

Example request

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Example response

{
  "accounts": [
    {
      "id": 12345,
      "name": "Ejemplo S.L.",
      ...
      "transactions_count": 24,
      "transactions_count_previous_period": 41,
      "transactions_limit": 100
    },
    {
      "id": 23456,
      "name": "Muster GmbH",
      ...
      "transactions_count": 32,
      "transactions_count_previous_period": 9,
      "transactions_limit": 100
    },
    {
      "id": 34567,
      "name": "Esempio S.r.l.",
      ...
      "transactions_count": 124,
      "transactions_count_previous_period": 326,
      "transactions_limit": 100
    }
    ...
  ]
}

Each account includes:

• transactions_count → Transactions consumed in the current billing period.
• transactions_count_previous_period → Transactions consumed in the previous billing period.
• transactions_limit → Maximum number of transactions included in the subscription.

By controlling this data, you can automatically manage the consumption of each account and the overall total. This allows you to automate payments based on transaction volume for your end clients, or to monitor your usage against the agreed quota and increase your transaction limit before exceeding it.