Routing

"Routing" in GoRoute means one decision: does this document go over the Peppol network, or is it built and handed back to you to email? There are two channels and no others. GoRoute makes the choice for you by default, you can override it per document, and there is nothing to configure in advance.

This page is the short version, with a pointer to the page that owns each detail. If you are looking for routing rules, per-country routing, a pre-flight call or a third delivery network, read What GoRoute does not have at the bottom — an earlier version of this page described features that do not exist, and that section says so plainly.

The two channels

┌─────────────────────┐
│  POST /api/v1/      │
│     invoices        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Is the buyer       │
│  reachable on       │
│  Peppol?            │
│  (SMP lookup)       │
└──────────┬──────────┘
           │
    ┌──────┴───────────────┐
    │                      │
    ▼                      ▼
┌──────────────┐    ┌─────────────────────┐
│ Peppol AS4   │    │ Issued for email    │
│ status:      │    │ status: issued      │
│ queued →     │    │ you send the PDF    │
│ delivered    │    │ GoRoute never sends │
└──────────────┘    └─────────────────────┘

The left branch is a transmission GoRoute performs and tracks to delivered or failed. The right branch is finished the moment it is created: the document is built, stored and auditable, the transaction status is issued, and nothing further happens to it. Code that waits for delivered or failed must treat issued as a third ending or it will wait forever.

How the channel is chosen

Two fields on POST /api/v1/invoices control it, and both default to auto:

{
    "invoice": { "...": "your canonical invoice" },
    "document_format": "auto",
    "delivery_channel": "auto"
}

delivery_channel takes auto, peppol or email. The response carries a delivery object saying which channel was used and why.

The rule that decides auto is written out, in the order it is applied, on Delivery and Formats. It is stated once, there, so that there is one place to correct if it changes. The headline is that a buyer registered for this document type on Peppol gets it over the network, and anyone else gets an emailable document — except where the seller's country forbids email delivery, which is also listed on that page.

Checking the buyer before you send

If you want to know which way a document will go before you send it, look the buyer up:

curl "https://app.goroute.ai/peppol-api/api/v1/participants/lookup?peppol_id=0106:12345678" \
  -H "X-API-Key: your_api_key"

The answer is 200 whether or not the participant is on the network: read found, and read capabilities to see whether they accept the document type you are about to send. A buyer who is registered but does not accept your document type is the case that surprises people — the document goes by email, not over Peppol.

Full response fields, the scheme:value form the parameter requires, caching, the batch form and the "can this recipient receive an invoice" helper are on Participant Lookup.

When a send fails

A Peppol send that does not succeed lands on one of two statuses, and the difference matters:

Status	What it means	Who acts
`retrying`	A transport problem that may clear on its own. The send is retried up to three more times; after that the transaction becomes `failed`.	Nobody — wait
`failed`	The send did not succeed and will not be retried automatically. `error_code`, `error_message` and `failed_at` are set.	You

You can ask for a failed or retrying transaction to be delivered again:

curl -X POST \
  https://app.goroute.ai/peppol-api/api/v1/transactions/{transaction_id}/retry \
  -H "X-API-Key: your_api_key"

The transaction goes back to queued with the same transaction and message identifier. A transaction that is delivered, queued or issued cannot be retried, and there is no force option. The full status list, the retry refusals, proof of delivery and the difference between a retry and a resend are on Tracking Delivery.

Follow status with webhooks rather than polling. The events that exist for this are transaction.queued, transaction.delivered, transaction.failed, transaction.retrying and transaction.received — see Webhooks.

What GoRoute does not have

An earlier version of this page described a routing engine that was never built. If you planned an integration around any of the following, none of it exists and no call on this list has ever worked. The replacement, where there is one, is named beside it.

Described before	Reality
Configurable `routing_rules` — priority, per-country and per-document-type	No such configuration exists. The channel rule is fixed, and the only per-document control is the `delivery_channel` field
An organisation routing policy (`default_fallback`, `require_delivery_receipt`, `max_retry_attempts`, `retry_timeout_hours`)	No such settings exist, at organisation level or anywhere else. Retries are not configurable
A pre-flight routing call	Use the participant lookup
A route-trace call, and routing analytics	Not available. Transaction history and status are on Tracking Delivery
A `POST /documents/send` endpoint taking a `routing` object	Documents are sent with `POST /api/v1/invoices` — see Sending an Invoice
Delivery over the Italian SDI network	GoRoute does not deliver through SDI. For an Italian seller, GoRoute refuses email delivery, which is a different thing — see where email delivery is refused
Delivery by physical post, and a `print` or `print_mail` channel	GoRoute does not post anything. There are two channels: Peppol and email
A UBL routing-hint extension (`goroute:RoutingHint`, `PreferredNetwork`, `FallbackEmail`)	GoRoute reads no such extension. Put it in a document and it is ignored
A circuit breaker that routes around a failing access point	There is no circuit breaker. A failing access point produces `retrying` and then `failed`
The webhook events `document.fallback` and `routing.circuit_open`	Neither event is dispatched. The real events are listed above
A five-attempt backoff schedule (immediate, 5 min, 15 min, 1 hour, 4 hours)	The real behaviour is up to three more attempts after the first failure, then `failed`

Nothing above is labelled "planned", because nobody has said it is planned. If you need one of these, raise it with support so it is counted as a request rather than assumed to be coming.

Practical advice that does hold

Use webhooks for status, do not poll. Subscribe to the delivery events rather than asking repeatedly — see Webhooks.
Handle issued as an ending. It is the most common cause of a stuck integration here: the document is finished and GoRoute will never transmit it.
Look the buyer up before a bulk send. It tells you which of your invoices will need an email, so you find out before you have five hundred of them.
Keep the buyer's participant identifier on the invoice when you want Peppol delivery. With delivery_channel: peppol, or any named document_format, there is no lookup and a missing identifier is refused with BUYER_IDENTIFIER_REQUIRED.

The two channels​

How the channel is chosen​

Checking the buyer before you send​

When a send fails​

What GoRoute does not have​

Practical advice that does hold​

Next Steps​