POST /v1/send

Generate an e-invoice and queue it for network delivery in one call. In preview: the transmission endpoints are not generally available yet.

POST /v1/send takes the same EN 16931 invoice object as POST /v1/generate, plus the routing, and does both halves in one call: the engine builds and validates the XML, then the document is durably queued for delivery and you get a txn_ handle back. Submission to the network happens afterwards, asynchronously.

{
  "standard": "peppol-bis",
  "profile": "peppol",
  "invoice": { },
  "network": "peppol",
  "sender":    { "scheme": "9930", "id": "DE123456789" },
  "recipient": { "scheme": "0088", "id": "5790000435975" }
}

The generation half is POST /v1/generate’s own request, minus the knobs that only make sense for a file you read yourself: the network payload is always XML, so output, template, pdfTemplateId and verify are not accepted here. Validation is not optional on this route.

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

The sender must be yours, in both places

You may only send as an identifier your organization has registered and that is active, so sender is checked against your registrations before the engine runs. It is not yours: 403 SENDER_NOT_REGISTERED.

The invoice carries the seller’s electronic address too, and Beliq refuses a send where the request and the document name different parties, rather than putting a document on a network under an identity its own content contradicts. That is 400 DOCUMENT_PARTY_MISMATCH, and details gives both identifiers and which role disagreed. On Peppol the document’s field is the seller’s cbc:EndpointID; on Italy SdI it is the CedentePrestatore VAT number, and on a document that may be a self-invoice the buyer’s or the issuing third party’s VAT as well (DOCUMENT_PARTY_MISMATCH says when).

In test mode this is the thing most likely to catch you out, because rehearsing means both the request and the invoice have to name the test identifier Beliq issued you.

A 202 means the document was built, passed validation and is queued. It has not been submitted yet.

{
  "success": true,
  "data": {
    "id": "txn_9f3c2a1b8e4d47a2b1c05d4e3f2a1b0c",
    "status": "queued",
    "direction": "outbound",
    "network": "peppol",
    "deduplicated": false,
    "verdict": { }
  }
}

An invoice that fails validation is a 422 and nothing is queued.

Send an Idempotency-Key header. A repeat with the same key and the same body returns the existing transmission as a 200 with deduplicated: true, costs no quota unit, and does not run the engine again. A repeat with the same key and a different body is refused with 409 IDEMPOTENCY_KEY_REUSED, so a key can never return the wrong document.

Without a key, Beliq still refuses to put the same document on the network twice: an identical document to the same recipient, while the first transmission can still arrive, is 409 CONTENT_ALREADY_SENT and details.transmissionId names the one you already have.

Every one of these reads is scoped to the calling key’s mode, so a live key cannot see a test-mode transmission and the other way round. The push equivalent is the transmission.* webhooks, which saves you polling.

When a transmission is finished

finishedAt is the time a transmission finished, and null until then. Once a transmission is finished its status does not change again and Beliq stops asking the delivery partner about it, so it is the field to wait on, rather than a particular status. A send finishes at once when it is rejected or failed. It finishes at its network’s own end, such as delivered, once the network’s proof of that end is stored with it; until the proof is read, Beliq keeps asking the provider for it.

finishLimit says why a send finished short of its network’s own end, and is null otherwise:

Where you build the XML yourself, POST /v1/transmissions takes it directly: the same network, sender, recipient, documentTypeId and deadlineAt, plus format and the document as xml. It skips the engine’s generation step and queues what you gave it. The idempotency and duplicate rules above are the same.

France and Poland have refusals of their own, because a document that may not legally travel this way is refused rather than queued. The full set, with what to do about each, is on the errors page.