Postman Collection

Our Postman collection lets you explore and test the GoRoute API interactively. It includes all endpoints with pre-configured examples, making it easy to understand the API before writing code.

Quick Start

1. Import the Collection

Or import manually:

1. Open Postman
2. Click Import → Link
3. Enter: https://app.goroute.ai/peppol-api/openapi.json
4. Click Import

2. Configure Environment

Create a new environment with the following variables:

Variable	Value
base_url	https://app.goroute.ai/peppol-api
api_key	your-api-key-here

3. Set Up Authentication

The collection uses a pre-request script to automatically add the API key header:

pm.request.headers.add({
    key: 'X-API-Key',
    value: pm.environment.get('api_key')
});

Collection Structure

GoRoute Peppol API/
├── 🔐 Authentication
│   └── Get API Key Info
├── 📄 Documents
│   ├── Send Invoice
│   ├── Send Credit Note
│   ├── Validate Document
│   ├── Get Transaction Status
│   └── Download Document
├── 👥 Participants
│   ├── Register Participant
│   ├── List Participants
│   └── Lookup Participant
├── 🔔 Webhooks
│   ├── Create Webhook
│   ├── List Webhooks
│   └── Delete Webhook
└── ❤️ Health
    └── Health Check

Example Requests

Send an Invoice

POST {{base_url}}/documents/send
X-API-Key: {{api_key}}
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
    <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
    <cbc:ID>INV-2026-001</cbc:ID>
    <!-- ... rest of invoice -->
</Invoice>

Response:

{
  "transaction_id": "txn_abc123def456",
  "status": "accepted",
  "message": "Document queued for delivery"
}

Lookup a Participant

GET {{base_url}}/participants/lookup?identifier=0088:1234567890123
X-API-Key: {{api_key}}

Response:

{
  "participant_id": "0088:1234567890123",
  "registered": true,
  "document_types": [
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
  ],
  "endpoint_url": "https://ap.example.com/as4"
}

Validate Document

POST {{base_url}}/documents/validate
X-API-Key: {{api_key}}
Content-Type: application/xml

<!-- Your UBL document here -->

Response (Valid):

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "rule": "PEPPOL-EN16931-R040",
      "message": "Allowance reason code SHOULD be provided",
      "location": "/Invoice/cac:AllowanceCharge[1]"
    }
  ]
}

Response (Invalid):

{
  "valid": false,
  "errors": [
    {
      "rule": "BR-16",
      "message": "An Invoice shall have at least one Invoice line",
      "location": "/Invoice",
      "severity": "error"
    }
  ]
}

Using Collection Variables

The collection supports dynamic variables for testing:

Variable	Description	Example
{{$timestamp}}	Current Unix timestamp	1706284800
{{$randomUUID}}	Random UUID	a1b2c3d4-e5f6-...
{{$isoTimestamp}}	ISO 8601 date	2026-01-26T10:30:00Z

Example with Variables

POST {{base_url}}/documents/send
Content-Type: application/json

{
  "document_id": "INV-{{$timestamp}}",
  "correlation_id": "{{$randomUUID}}",
  "issued_date": "{{$isoTimestamp}}"
}

Testing Workflows

Complete Send → Track → Verify Flow

1. Send Document - POST to /documents/send
2. Save Transaction ID - Store transaction_id from response
3. Poll Status - GET /transactions/{transaction_id}
4. Verify Delivery - Check for status: delivered

// Test script to save transaction ID
if (pm.response.code === 202) {
    const response = pm.response.json();
    pm.environment.set('last_transaction_id', response.transaction_id);
}

Webhook Testing

Use Postman's mock servers or services like webhook.site to test webhook delivery:

1. Create a webhook.site URL
2. Register it as a webhook endpoint
3. Send a document
4. Watch the webhook arrive in real-time

Common Issues

401 Unauthorized

Problem: API key is missing or invalid

Solution:

• Check that api_key environment variable is set
• Verify the key hasn't expired
• Ensure no extra whitespace in the key

400 Bad Request

Problem: Invalid request format

Solution:

• Validate XML/JSON syntax
• Check Content-Type header matches body format
• Use the validation endpoint first

404 Not Found

Problem: Resource doesn't exist

Solution:

• Check participant identifier format
• Verify transaction ID is correct
• Ensure the resource was created in the same environment

Download Links

• 📥 Postman Collection (JSON)
• 📥 Environment Template
• 📥 OpenAPI Spec

Video Tutorial

Coming soon: Step-by-step video walkthrough of the Postman collection