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. Therefore, sending an invoice generates two billable transactions.
• Verifactu case: Creating and sending an invoice with Verifactu counts as two billable transactions, one for the invoice and one for the tax report. The “ledger” counts as many records as it contains. A ledger with 10 records counts as 10 individual transactions.
• 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.

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

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

Every time the view_as API is called with a document_type parameter different from “original” or “legal”, a transaction is generated. A new transaction is created every time a new document is generated from our database object.

Non-billable document types

original — Returns the document exactly as it was originally submitted or imported, served from storage. No regeneration takes place.

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

legal — Returns the archived legal document (e.g. the signed and timestamped version) as stored. No regeneration takes place.

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}'

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.

Billable document types

Any other document_type value regenerates the document in the requested format and counts as a billable transaction.

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.