Simple Peppol
SimplePeppol
API-First Peppol Access Point

API Documentation

Technical guide for integrating your software with Simple Peppol Gateway

Table of Contents

Authentication

All API requests require authentication using a Bearer token. You'll receive an API token when your account is created. 

Authorization: Bearer SBG_your_api_token_here

API tokens are prefixed with SBG_ and should be kept secure. Never commit tokens to version control.

Security Note: Tokens are hashed using SHA-256 with your account's salt. Store tokens securely and rotate them periodically.

Base URL

The API base URL depends on your environment:

  • Production: https://peppol-api.simplebill.pro/api/v1
  • Test: https://peppol-api.test.simplebill.pro/api/v1
  • Staging: https://peppol-api.staging.simplebill.pro/api/v1

Sending Documents

Send Peppol documents (invoices, credit notes, orders) via the POST /api/v1/documents endpoint.

Request

POST /api/v1/documents
Content-Type: application/json
Authorization: Bearer SBG_your_api_token_here
Idempotency-Key: your-unique-idempotency-key (optional)

{
  "environment": "production",
  "sender_peppol_id": "0199:pixeline",
  "receiver_peppol_id": "0199:triaxis",
  "document_type_id": "urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0",
  "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "payload_format": "ubl",
  "payload_xml": "<Invoice xmlns='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'>...</Invoice>",
  "client_reference": "simplebill-invoice-1234"
}

Request Parameters

Field Type Required Description
environment string Yes Either "sandbox" or "production"
sender_peppol_id string Yes Your registered Peppol participant ID (e.g., "0199:pixeline")
receiver_peppol_id string Yes Recipient's Peppol participant ID
document_type_id string Yes Peppol document type URN (e.g., invoice, credit note)
process_id string Yes Peppol process URN
payload_format string Yes Either "ubl" or "sbdh"
payload_xml string Yes The UBL XML document (max 10 MB)
client_reference string No Your unique reference for idempotency (prevents duplicate sends)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Checking Document Status

Poll the document status using GET /api/v1/documents/{id}: 

GET /api/v1/documents/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer SBG_your_api_token_here

Response:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "direction": "outbound",
  "sender_peppol_id": "0199:pixeline",
  "receiver_peppol_id": "0199:triaxis",
  "document_type_id": "urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0",
  "sent_at": "2025-11-29T10:30:00Z"
}

Document statuses: queued, processing, sent, delivered, failed

Receiving Documents

You can receive inbound Peppol documents in two ways: via webhooks (recommended) or by polling the API.

Polling Method

List inbound documents using GET /api/v1/inbox: 

GET /api/v1/inbox?page=1&per_page=50
Authorization: Bearer SBG_your_api_token_here

Response:
{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "status": "delivered",
      "sender_peppol_id": "0199:triaxis",
      "receiver_peppol_id": "0199:pixeline",
      "document_type_id": "urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0",
      "received_at": "2025-11-29T10:30:00Z"
    }
  ],
  "current_page": 1,
  "per_page": 50,
  "total": 1
}

Retrieving Document Payload

Get the full XML payload using GET /api/v1/inbox/{id}: 

GET /api/v1/inbox/660e8400-e29b-41d4-a716-446655440000
Authorization: Bearer SBG_your_api_token_here

Response:
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "payload_xml": "<StandardBusinessDocument>...</StandardBusinessDocument>",
  ...
}

Webhooks

Configure webhooks to receive real-time notifications when documents are received. Webhooks are sent via HTTP POST to your configured endpoint.

Webhook Payload

POST https://your-endpoint.com/webhooks/peppol
X-SimpleBill-Event: peppol.inbound_document.received
X-SimpleBill-Signature: sha256=abc123...
Content-Type: application/json

{
  "event": "peppol.inbound_document.received",
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "sender_peppol_id": "0199:triaxis",
  "receiver_peppol_id": "0199:pixeline",
  "document_type_id": "urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0",
  "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "received_at": "2025-11-29T10:30:00Z",
  "payload_xml": "<StandardBusinessDocument>...</StandardBusinessDocument>"
}

Webhook Signature Verification

Verify webhook authenticity by checking the X-SimpleBill-Signature header. The signature is computed as HMAC-SHA256(request_body, webhook_secret).

Important: Always verify webhook signatures to ensure requests are from Simple Peppol Gateway.

Usage Tracking

Monitor your API usage for the current billing period: 

GET /api/v1/usage/current
Authorization: Bearer SBG_your_api_token_here

Response:
{
  "period_start": "2025-11-01",
  "period_end": "2025-11-30",
  "outbound_count": 123,
  "inbound_count": 45,
  "outbound_bytes": 1234567,
  "inbound_bytes": 7654321
}

Error Handling

The API uses standard HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 422 - Validation Error
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Error responses include a JSON body with error details: 

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "sender_peppol_id": ["The sender peppol id field is required."]
  }
}

Code Examples

cURL

curl -X POST https://peppol-api.simplebill.pro/api/v1/documents \
  -H "Authorization: Bearer SBG_your_api_token_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-1234" \
  -d '{
    "environment": "production",
    "sender_peppol_id": "0199:pixeline",
    "receiver_peppol_id": "0199:triaxis",
    "document_type_id": "urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0",
    "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "payload_format": "ubl",
    "payload_xml": "<Invoice>...</Invoice>",
    "client_reference": "invoice-1234"
  }'

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->post('https://peppol-api.simplebill.pro/api/v1/documents', [
    'headers' => [
        'Authorization' => 'Bearer SBG_your_api_token_here',
        'Content-Type' => 'application/json',
        'Idempotency-Key' => 'invoice-1234',
    ],
    'json' => [
        'environment' => 'production',
        'sender_peppol_id' => '0199:pixeline',
        'receiver_peppol_id' => '0199:triaxis',
        'document_type_id' => 'urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0',
        'process_id' => 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
        'payload_format' => 'ubl',
        'payload_xml' => $ublXml,
        'client_reference' => 'invoice-1234',
    ],
]);

$result = json_decode($response->getBody(), true);

Python (requests)

import requests

response = requests.post(
    'https://peppol-api.simplebill.pro/api/v1/documents',
    headers={
        'Authorization': 'Bearer SBG_your_api_token_here',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'invoice-1234',
    },
    json={
        'environment': 'production',
        'sender_peppol_id': '0199:pixeline',
        'receiver_peppol_id': '0199:triaxis',
        'document_type_id': 'urn:fdc:peppol.eu:2017:poacc:billing:3:ver2.0',
        'process_id': 'urn:fdc:peppol.eu:2017:poacc:billing:01:1.0',
        'payload_format': 'ubl',
        'payload_xml': ubl_xml,
        'client_reference': 'invoice-1234',
    }
)

result = response.json()

Need Help?

For additional support, questions, or to request API access, please contact us:

Contact Support