Skip to main content

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โ€‹

RuleWhat it means for you
UBL onlyThe 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 stringThe XML travels in the document field of a JSON body. There is no raw-XML, base64 or multipart variant.
You name the receiverreceiver_scheme and receiver_id are required. GoRoute does not read them from the XML.
You name the document typedocument_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 isFor 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 sendersender_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 submittedNo signature, QR code or attachment is added. Anything the recipient needs must already be in your XML.
Send Omani invoices as PINT OM, or as invoice data

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"}
}
FieldRequiredNotes
documentYesThe UBL XML as a string, without an SBDH envelope (GoRoute's Access Point adds that). Empty or whitespace-only is refused.
receiver_scheme, receiver_idYesThe buyer's Peppol identifier, e.g. 0208 + 0100000367. Use the same value as the buyer's cbc:EndpointID in your XML.
document_typeNoDefaults 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_idNoMust 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_idNoYour 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.
destinationNoWhere 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.
metadataNoFree-form object stored with the transaction.
webhook_urlNoA 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"])
These are GoRoute's own checks, not the official Schematron

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 with 202 and "Document already accepted (idempotent replay)"; the document is not sent twice. The same key with a different body is refused with 422 IDEMPOTENCY_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 the existing_transaction_id. That 409 carries no error_code field โ€” check error.

Details: Sending an invoice โ†’ Idempotency.

Errorsโ€‹

StatusCodeMeaning
400INVALID_REQUESTThe 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.
400INVALID_IDEMPOTENCY_KEYThe key is longer than 255 characters.
401MISSING_API_KEY / INVALID_API_KEY / EXPIRED_API_KEYCheck the X-API-Key header.
403INSUFFICIENT_PERMISSION / INSUFFICIENT_SCOPEThe key needs the send scope.
402PLAN_LIMIT_REACHEDThe organisation's plan allows no more documents this month.
409duplicate_invoice_number (in error)Same invoice number, different content, no idempotency key.
409SAME_DOCUMENT_EXISTS / SAME_DOCUMENT_FAILEDThis document was already sent under a different Idempotency-Key.
409SAME_DOCUMENT_IN_FLIGHTAnother 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.
422IDEMPOTENCY_KEY_REUSEDSame key, different body, within 24 hours.
422IDEMPOTENCY_KEY_IN_BODY_NOT_SUPPORTEDThe body carries an idempotency_key that differs from the Idempotency-Key header. Send the key in the header only.
422PLATFORM_ONLY_DOCUMENT_TYPETax-reporting and MLS document types are sent by GoRoute itself, never by a tenant.
422DOCUMENT_TYPE_MISMATCHdocument_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.
422PROCESS_ID_MISMATCHOnly 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.
422SANDBOX_RECEIVER_NOT_ALLOWEDA sandbox receiver (scheme 9999) on a cell that does not deliver to sandbox receivers.
422DOCUMENT_INVALIDThe 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.
422OMAN_PINT_OM_REQUIREDOnly 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).
429RATE_LIMIT_MINUTE / RATE_LIMIT_DAYWait for Retry-After.
503SEND_RULES_UNAVAILABLEThe 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โ€‹

  1. transaction.queued fires as soon as the document is accepted.
  2. transaction.delivered fires when the recipient's Access Point confirms receipt; transaction.retrying and transaction.failed cover the other outcomes.
  3. GET /api/v1/transactions/{transaction_id} returns the current status (queued, submitted, accepted, delivered, failed, retrying, held or issued) with the delivery timestamps and any error_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.

Next stepsโ€‹