Advanced Routing

GoRoute provides intelligent routing capabilities to ensure your documents reach their destination through the optimal path. This guide covers routing rules, fallback strategies, and multi-network support.

How Routing Works

When you send a document, GoRoute determines the best route:

┌─────────────────┐
│  Your Invoice   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  GoRoute API    │
│  Routing Engine │
└────────┬────────┘
         │
    ┌────┴────┐
    │ Lookup  │
    │ SMP/SML │
    └────┬────┘
         │
    ┌────┴────────────────┐
    │                     │
    ▼                     ▼
┌────────┐          ┌────────────┐
│ Peppol │          │  Fallback  │
│   AP   │          │   (Email)  │
└────────┘          └────────────┘

SMP Lookup

Before routing, GoRoute performs Service Metadata Publisher (SMP) lookups:

# Check if recipient is on Peppol
curl https://app.goroute.ai/peppol-api/participants/lookup?identifier=0088:1234567890123 \
  -H "X-API-Key: your-api-key"

Response:

{
  "participant_id": "0088:1234567890123",
  "registered": true,
  "access_point": {
    "name": "Example AP",
    "url": "https://ap.example.com/as4"
  },
  "document_types": [
    {
      "document_type_id": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
      "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
    }
  ],
  "certificate": {
    "subject": "CN=Example AP",
    "valid_until": "2027-01-15T00:00:00Z"
  }
}

Routing Rules

Priority-Based Routing

Configure routing priority for different networks:

{
  "routing_rules": [
    {
      "priority": 1,
      "network": "peppol",
      "conditions": {
        "recipient_registered": true
      }
    },
    {
      "priority": 2,
      "network": "email",
      "conditions": {
        "email_available": true
      }
    },
    {
      "priority": 3,
      "network": "print_mail",
      "conditions": {
        "address_available": true
      }
    }
  ]
}

Country-Based Routing

Route based on recipient country:

{
  "routing_rules": [
    {
      "countries": ["IT"],
      "network": "sdi",
      "comment": "Italy uses SDI for B2G and B2B"
    },
    {
      "countries": ["DE"],
      "network": "peppol",
      "requirements": ["xrechnung"],
      "comment": "Germany requires XRechnung CIUS"
    },
    {
      "countries": ["FR"],
      "network": "peppol",
      "requirements": ["facturx"],
      "comment": "France requires Factur-X for public sector"
    }
  ]
}

Document Type Routing

Different routing for different document types:

{
  "routing_rules": [
    {
      "document_type": "Order",
      "network": "peppol",
      "process_id": "urn:fdc:peppol.eu:2017:poacc:ordering:01:1.0"
    },
    {
      "document_type": "Invoice",
      "network": "peppol",
      "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
    }
  ]
}

Fallback Handling

Automatic Fallback

When Peppol delivery fails, GoRoute can automatically attempt fallback methods:

curl -X POST https://app.goroute.ai/peppol-api/documents/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "<Invoice>...</Invoice>",
    "routing": {
      "primary": "peppol",
      "fallback": ["email", "print"],
      "fallback_email": "invoices@recipient.com",
      "fallback_address": {
        "street": "123 Main St",
        "city": "Amsterdam",
        "postal_code": "1012 AB",
        "country": "NL"
      }
    }
  }'

Fallback Events

Track fallback via webhooks:

{
  "event": "document.fallback",
  "data": {
    "transaction_id": "txn_abc123",
    "original_network": "peppol",
    "fallback_network": "email",
    "reason": "recipient_not_registered",
    "fallback_recipient": "invoices@recipient.com"
  }
}

Disable Fallback

For strict Peppol-only delivery:

{
  "routing": {
    "primary": "peppol",
    "fallback": [],
    "fail_if_not_registered": true
  }
}

Pre-Flight Checks

Check routing before sending:

curl -X POST https://app.goroute.ai/peppol-api/routing/preflight \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "0088:1111111111111",
    "receiver_id": "0088:2222222222222",
    "document_type": "Invoice",
    "country": "NL"
  }'

Response:

{
  "routing_available": true,
  "recommended_route": {
    "network": "peppol",
    "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "access_point": "ap.receiver.com"
  },
  "alternatives": [
    {
      "network": "email",
      "available": true,
      "email": "invoices@receiver.com"
    }
  ],
  "warnings": []
}

Network Selection

Available Networks

Network	Description	Coverage
peppol	Peppol AS4 network	40+ countries
sdi	Italian Sistema di Interscambio	Italy
email	PDF via email	Global
print	Physical mail	Global

Explicit Network Selection

Force a specific network:

curl -X POST https://app.goroute.ai/peppol-api/documents/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "<Invoice>...</Invoice>",
    "routing": {
      "network": "peppol",
      "allow_fallback": false
    }
  }'

Routing Intelligence

Recipient Capability Detection

GoRoute automatically detects recipient capabilities:

{
  "recipient_capabilities": {
    "peppol_registered": true,
    "supported_documents": ["Invoice", "CreditNote"],
    "supported_processes": [
      "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
    ],
    "cius_requirements": ["XRechnung"],
    "endpoint_status": "active"
  }
}

Smart Retries

Failed deliveries are automatically retried with exponential backoff:

Attempt 1: Immediate
Attempt 2: After 5 minutes
Attempt 3: After 15 minutes
Attempt 4: After 1 hour
Attempt 5: After 4 hours

Circuit Breaker

If a recipient's AP is consistently failing, GoRoute temporarily routes around it:

{
  "event": "routing.circuit_open",
  "data": {
    "access_point": "https://failing-ap.example.com",
    "reason": "consecutive_failures",
    "failure_count": 5,
    "circuit_reset_at": "2026-01-26T12:00:00Z"
  }
}

Routing Policies

Organization-Level Policies

Set default routing for your organization:

curl -X PUT https://app.goroute.ai/peppol-api/organizations/org_abc123/routing \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "default_fallback": ["email"],
    "require_delivery_receipt": true,
    "max_retry_attempts": 5,
    "retry_timeout_hours": 24
  }'

Document-Level Override

Override routing per document:

<Invoice>
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  
  <!-- GoRoute extension for routing hints -->
  <ext:UBLExtensions>
    <ext:UBLExtension>
      <ext:ExtensionContent>
        <goroute:RoutingHint>
          <goroute:PreferredNetwork>peppol</goroute:PreferredNetwork>
          <goroute:FallbackEmail>backup@example.com</goroute:FallbackEmail>
        </goroute:RoutingHint>
      </ext:ExtensionContent>
    </ext:UBLExtension>
  </ext:UBLExtensions>
</Invoice>

Monitoring Routes

Route Analytics

View routing statistics:

curl https://app.goroute.ai/peppol-api/analytics/routing \
  -H "X-API-Key: your-api-key"

{
  "period": "2026-01",
  "total_documents": 1523,
  "by_network": {
    "peppol": 1412,
    "email": 98,
    "print": 13
  },
  "fallback_rate": "7.3%",
  "success_rate": "99.2%",
  "avg_delivery_time_seconds": 3.2
}

Route Tracing

Debug routing decisions:

curl https://app.goroute.ai/peppol-api/transactions/txn_abc123/route-trace \
  -H "X-API-Key: your-api-key"

{
  "transaction_id": "txn_abc123",
  "route_trace": [
    {
      "step": 1,
      "action": "smp_lookup",
      "result": "found",
      "duration_ms": 45
    },
    {
      "step": 2,
      "action": "capability_check",
      "result": "invoice_supported",
      "duration_ms": 12
    },
    {
      "step": 3,
      "action": "as4_send",
      "result": "success",
      "duration_ms": 892
    }
  ],
  "final_route": "peppol",
  "recipient_ap": "ap.example.com"
}

Best Practices

1. Always provide fallback contacts - Include email/address for non-Peppol recipients
2. Use pre-flight checks - Verify routing before bulk sends
3. Monitor fallback rates - High fallback rates may indicate recipient registration issues
4. Set appropriate timeouts - Balance between delivery speed and retry resilience
5. Use webhooks for status - Don't poll; subscribe to delivery events

Next Steps

• Sending Documents →
• Webhooks →
• Error Handling →