Send XML You Already Generate
If your software already writes the e-invoice XML, GoRoute only has to deliver it.
POST /api/v1/documents takes your document as it is, routes it over Peppol and reports the
outcome. GoRoute does not rewrite, re-render or sign it: the XML you send is the XML the
recipient receives.
This page lists the rules that matter when the XML comes from your own code. For a working call in Python, Node.js, C# and Java, see Client libraries.
The rules in one tableโ
| Rule | What it means for you |
|---|---|
| UBL only | The root element must be UBL Invoice or CreditNote (or one of the UBL business documents). CII is refused, not converted โ see below. |
| XML as a JSON string | The XML travels in the document field of a JSON body. There is no raw-XML, base64 or multipart variant. |
| You name the receiver | receiver_scheme and receiver_id are required. GoRoute does not read them from the XML. |
| You name the document type | document_type defaults to the Peppol BIS 3.0 Invoice. A credit note, XRechnung, PINT or any other customisation must pass its own value. |
| The document type must say what the XML is | For a UBL Invoice or CreditNote, the identifier's root part must be the XML's root element and its customisation part must equal the document's own cbc:CustomizationID, exactly. A disagreement is refused with 422 DOCUMENT_TYPE_MISMATCH, and nothing is created; see below. |
| Name the sender | sender_scheme/sender_id are optional, but if your organisation has more than one active participant, name the sender on every call. What GoRoute uses when you leave it out differs between services; see Sending an Invoice. |
| Sent as submitted | No signature, QR code or attachment is added. Anything the recipient needs must already be in your XML. |
The BIS 3.0 default above is the wrong document for an Omani seller. An invoice or credit
note from an Omani seller โ sent from a 0248 participant, or naming an OM VAT number as
the seller's โ must be PINT OM (urn:peppol:pint:billing-1@om-1), or be sent as invoice data
to POST /api/v1/invoices so GoRoute renders it as PINT OM and reports it to the Tax
Authority. A BIS Billing 3.0 invoice from an Omani seller is accepted and logged for now, but
do not rely on that: GoRoute can refuse it. The refusal is HTTP 422 with error_code
OMAN_PINT_OM_REQUIRED, and its message starts with [OMAN-PINT-OM-REQUIRED]. Only a new
document is refused: sending again a document GoRoute has already accepted returns its
existing transaction, as any idempotent resend does.
Acceptance is not reporting. While it is accepted, the invoice is delivered to the buyer and is not filed with the Oman Tax Authority โ nothing in the response says so, and the symptom is silence. Full rules, including the Oman document types and reason codes, are in the Oman country guide.
The requestโ
POST /api/v1/documents
X-API-Key: your_api_key
Content-Type: application/json
Idempotency-Key: INV-2026-00123
{
"receiver_scheme": "0208",
"receiver_id": "0100000367",
"document_type": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
"process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
"document": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" ...>...</Invoice>",
"metadata": {"your_reference": "order-8812"}
}
| Field | Required | Notes |
|---|---|---|
document | Yes | The UBL XML as a string, without an SBDH envelope (GoRoute's Access Point adds that). Empty or whitespace-only is refused. |
receiver_scheme, receiver_id | Yes | The buyer's Peppol identifier, e.g. 0208 + 0100000367. Use the same value as the buyer's cbc:EndpointID in your XML. |
document_type | No | Defaults to the BIS 3.0 Invoice identifier shown above. Must start with urn: and contain ::, and must name the XML's root element and its exact cbc:CustomizationID (see Credit notes and other document types). |
process_id | No | Must start with urn:. Send the PINT process for a PINT document: urn:peppol:bis:billing, or urn:peppol:bis:selfbilling for PINT self-billing. A service that sets the process from the document type fills an omitted one the same way; a service that does not yet set it uses the BIS 3.0 process urn:fdc:peppol.eu:2017:poacc:billing:01:1.0, which is right for BIS 3.0 and wrong for PINT. |
sender_scheme, sender_id | No | Your participant. Name it if your organisation has more than one. Must be a participant of your organisation (or of one it manages); see Sender entitlement. |
destination | No | Where the document goes. Defaults to peppol โ to the buyer, which is what this whole page describes. authority sends it to the tax authority only and to no buyer; peppol_authority is a third value the schema accepts that no GoRoute service serves today. Any value but peppol is refused with 400 INVALID_REQUEST unless a jurisdiction pack on the service you are calling serves that route for your organisation โ which, on production, Spain's Verifactu pack and Poland's KSeF pack do, each for an enrolled organisation of that country. See the destination field. |
metadata | No | Free-form object stored with the transaction. |
webhook_url | No | A URL to notify for this document only. |
A new document is answered with 202 Accepted:
{
"transaction_id": "5f1cโฆ",
"status": "queued",
"message": "Document queued for delivery",
"created_at": "2026-10-01T09:30:00Z",
"idempotency_key": "INV-2026-00123"
}
Credit notes and other document typesโ
The document type is not inferred from your XML, and it is checked against it.
A Peppol document type identifier is
<root namespace>::<root element>##<cbc:CustomizationID>::<UBL version>: it is what GoRoute
writes into the envelope, looks up on the recipient's SMP, files the transaction under and
reads for every country decision (whether an Omani invoice is reported to the Tax Authority,
for one). So for a UBL Invoice or CreditNote the identifier's root part must be the XML's
root element and its customisation part must equal the document's own cbc:CustomizationID,
character for character. A UBL CreditNote sent without its own document_type, or a PINT
document declared as BIS 3.0, is refused with HTTP 422 DOCUMENT_TYPE_MISMATCH; the body's
expected_document_type is the identifier built from your XML, ready to copy, and nothing is
created. Pick the value from the root element before you send:
from lxml import etree
INVOICE = ("urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##"
"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1")
CREDIT_NOTE = ("urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##"
"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1")
root = etree.fromstring(xml_bytes)
document_type = CREDIT_NOTE if etree.QName(root).localname == "CreditNote" else INVOICE
The two values above are for Peppol BIS Billing 3.0. A document with a different
cbc:CustomizationID โ XRechnung, a PINT jurisdiction, self-billing โ needs the matching
document type identifier: see Document types and the
country guides. For PINT OM (Oman) the identifiers are
urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@om-1::2.1
and urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:billing-1@om-1::2.1,
with process_id urn:peppol:bis:billing (self-billing: โฆ##urn:peppol:pint:selfbilling-1@om-1::2.1
and urn:peppol:bis:selfbilling). The process_id is not checked against the XML's
cbc:ProfileID; send the process of the profile you declare. The UBL post-award documents (orders,
despatch advice and the rest) are the exception: GoRoute sets their document type from the
document itself, see Business documents.
CII is refusedโ
ZUGFeRD, Factur-X and XRechnung can be written in UN/CEFACT CII syntax
(rsm:CrossIndustryInvoice). GoRoute does not convert CII to UBL. A CII document is refused
with HTTP 400:
Document validation failed with 1 errors: [INVALID_ROOT] Root element must be 'Invoice' or 'CreditNote', got 'CrossIndustryInvoice'
Convert it to UBL first, or let GoRoute build the invoice from data instead. Both routes are in ZUGFeRD, Factur-X and XRechnung CII.
Validate before you sendโ
POST /api/v1/documents/validate runs GoRoute's own checks without sending. They are not
everything the send runs: the send also checks the official rules (see the caution below).
It needs the invoices:read permission and answers 200 even when the document is invalid;
read valid and issues[].
response = requests.post(
f"{BASE_URL}/api/v1/documents/validate",
headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
json={"document": invoice_xml},
timeout=30,
)
result = response.json()
if not result["valid"]:
for issue in result["issues"]:
print(issue["severity"], issue["code"], issue["message"], issue["location"])
For raw XML, /documents/validate checks the root element, the header, both parties, the tax
and monetary totals, the lines and a set of business rules. It does not run the XSD or the
official CEN / Peppol / KoSIT Schematron on your XML (UBL post-award documents excepted).
The send does. On production and on the test service, and since 10 November 2026 on GoRoute's
services in Oman, POST /api/v1/documents also checks your
XML against the UBL 2.1 schema and the official Schematron of its own customisation. A document
that breaks them is refused with 422 DOCUMENT_INVALID and its findings, and nothing is
created or sent. This changed on 31 October 2026 (10 November 2026 on GoRoute's services in
Oman); before, such a document was sent and the
receiving access point refused it. So a document can pass /documents/validate and still be
refused at the send. Keep running your library's own validation, or the official validators, as
part of your build.
Retries and duplicatesโ
- Send an
Idempotency-Key(up to 255 characters, kept for 24 hours). Repeating the same key with the same body returns the original transaction with202and"Document already accepted (idempotent replay)"; the document is not sent twice. The same key with a different body is refused with 422IDEMPOTENCY_KEY_REUSED. - Without a key, GoRoute derives one from the document itself. Re-sending the identical
document replays; sending different content under an invoice number you already used is
refused with 409 and
"error": "duplicate_invoice_number"plus theexisting_transaction_id. That 409 carries noerror_codefield โ checkerror.
Details: Sending an invoice โ Idempotency.
Errorsโ
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | The document failed validation (up to five [code] message items in message), no sender could be found, or the sender is not entitled (see below). For an Omani PINT OM invoice this includes a cbc:UUID that is not the Solution Architecture ยง10.2.3 derivation; the message gives the expected value. Nothing is created. |
| 400 | INVALID_IDEMPOTENCY_KEY | The key is longer than 255 characters. |
| 401 | MISSING_API_KEY / INVALID_API_KEY / EXPIRED_API_KEY | Check the X-API-Key header. |
| 403 | INSUFFICIENT_PERMISSION / INSUFFICIENT_SCOPE | The key needs the send scope. |
| 402 | PLAN_LIMIT_REACHED | The organisation's plan allows no more documents this month. |
| 409 | duplicate_invoice_number (in error) | Same invoice number, different content, no idempotency key. |
| 409 | SAME_DOCUMENT_EXISTS / SAME_DOCUMENT_FAILED | This document was already sent under a different Idempotency-Key. |
| 409 | SAME_DOCUMENT_IN_FLIGHT | Another send of this document is still running. Retry after the Retry-After header (60 s). |
| 422 | (FastAPI field errors) | Missing receiver, empty document, malformed document_type or process_id. |
| 422 | IDEMPOTENCY_KEY_REUSED | Same key, different body, within 24 hours. |
| 422 | IDEMPOTENCY_KEY_IN_BODY_NOT_SUPPORTED | The body carries an idempotency_key that differs from the Idempotency-Key header. Send the key in the header only. |
| 422 | PLATFORM_ONLY_DOCUMENT_TYPE | Tax-reporting and MLS document types are sent by GoRoute itself, never by a tenant. |
| 422 | DOCUMENT_TYPE_MISMATCH | document_type does not name the XML's root element and exact cbc:CustomizationID. The body carries declared_document_type, document_customization_id and expected_document_type (the identifier to send). Nothing is created; a resend of a document GoRoute already accepted still returns its existing transaction. |
| 422 | PROCESS_ID_MISMATCH | Only where the service sets the process from the document type: the process_id you named is not the one your PINT document type is sent under. The body carries declared_process_id, document_type and expected_process_id (the process to send). Nothing is created. |
| 422 | SANDBOX_RECEIVER_NOT_ALLOWED | A sandbox receiver (scheme 9999) on a cell that does not deliver to sandbox receivers. |
| 422 | DOCUMENT_INVALID | The document breaks the UBL 2.1 schema or the official Schematron of its customisation. The body carries rule_pack, finding_count and findings (layer, rule_id, severity, xpath, message). Nothing is created. Enforced on production and the test service since 31 October 2026. |
| 422 | OMAN_PINT_OM_REQUIRED | Only where the service enforces it: an Omani seller sent a document that is not PINT OM. Production does not enforce it today (see the warning above). |
| 429 | RATE_LIMIT_MINUTE / RATE_LIMIT_DAY | Wait for Retry-After. |
| 503 | SEND_RULES_UNAVAILABLE | The official rules could not be run on the document just now, so it was not sent and nothing was created. Send it again after Retry-After (60 s). |
A 202 means GoRoute has accepted the document for delivery, not that it has been delivered.
Delivery is confirmed by transaction.delivered (below).
Sender entitlement. If you name a sender, it must be an active participant of your
organisation or of an organisation beneath it. Otherwise the send is refused (as
INVALID_REQUEST on this endpoint) with the message "Sender โฆ is not an active participant
of this organization or of an organization it manages". See
For software vendors.
After the sendโ
transaction.queuedfires as soon as the document is accepted.transaction.deliveredfires when the recipient's Access Point confirms receipt;transaction.retryingandtransaction.failedcover the other outcomes.GET /api/v1/transactions/{transaction_id}returns the currentstatus(queued,submitted,accepted,delivered,failed,retrying,heldorissued) with the delivery timestamps and anyerror_code/error_message.
A raw-XML transaction has no invoice data behind it, so resend is not available for it
(400 NO_INVOICE_DATA); use retry instead. See Tracking.