Skip to main content

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​

Run in Postman

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:

VariableValue
base_urlhttps://app.goroute.ai/peppol-api
api_keyyour-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:

VariableDescriptionExample
{{$timestamp}}Current Unix timestamp1706284800
{{$randomUUID}}Random UUIDa1b2c3d4-e5f6-...
{{$isoTimestamp}}ISO 8601 date2026-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

Video Tutorial​

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