Receiving invoices

Network receiving, and POST /v1/receive to validate and parse an e-invoice you hold. In preview: the transmission endpoints are not generally available yet.

Receiving is two different things, and only one of them involves a network.

• Network receiving is Beliq collecting documents addressed to a participant your organization has registered, validating them, and making them readable as inbound transmissions.
• POST /v1/receive is a compute convenience: hand it an XML invoice you already hold, from your own access point or an email attachment, and get the validation verdict and the parsed invoice back. No network, no storage.

You receive on an identifier, not on an account. A document reaches you because a participant registration your organization holds is published on the network with a provider collecting for it, so the first step is a registration: GET /v1/participants lists the ones you hold in the calling key’s mode, and in test mode Beliq issues you one with POST /v1/participants/sandbox.

An inbound document then moves through four statuses:

available and failed are the terminal pair. Read what arrived with the same endpoints an outbound transmission uses, filtered to the inbound direction:

Every read is scoped to the calling key’s mode, so a live key cannot read a document that arrived in test mode.

A valid document is not a guaranteed one

Beliq validates what arrives and stores the verdict, but it does not refuse a document because the verdict is bad: an invoice your counterparty sent you is a business fact whether or not it passes EN 16931. Read the verdict and decide. The one thing that stops a document reaching available is Beliq being unable to ingest or validate it at all, which is failed.

Anyone on the network can address you

A document addressed to a participant you hold is filed whoever sent it, and the sender’s own network identifier is shown as the counterparty. There is no allowlist of counterparties, because a delivery network’s point is that a party you have never dealt with can invoice you. Design your handler to treat the counterparty as untrusted input, and in test mode expect strangers: see what arrives in your test inbox.

A validate-and-parse pass over an invoice you already hold. It takes the raw XML as the request body, like POST /v1/validate, and touches no network: nothing is sent, nothing is stored, and no participant registration is needed.

curl -X POST https://api.beliq.eu/v1/receive \
  -H "Authorization: Bearer blq_test_abc123..." \
  -H "Content-Type: application/xml" \
  --data-binary @incoming-invoice.xml

{
  "success": true,
  "data": {
    "validationResult": { },
    "parse": { }
  }
}

The request body is capped at 1 MiB; a larger one is a 413 and nothing is read.

Errors