Submit e-invoices to Peppol

This guide describes how to validate and submit e-invoices to the Peppol network through the Lobster Peppol Access Point service.

Prerequisites

• Valid credentials (username and password) for the Lobster Peppol Access Point service, available from the Lobster Customer Success team.

• An e-invoice in Peppol BIS Billing 3.0 format (UBL Invoice or UBL Credit Note) or a supported domestic CIUS format (for example, NLCIUS for the Netherlands).

• Access to the production or staging environment:          

  • Production: https://connect-data-network.lobster-cloud.com

  • Staging: https://connect-test-data-network.lobster-cloud.com

Domestic format support

Contact the Lobster Sales team or your Customer Success Manager to discuss available domestic CIUS formats for your target countries.

Endpoint

Query parameter

Request body

The request body must contain a UBL 2.1 invoice XML document compliant with the Peppol BIS Billing 3.0 specification or a supported domestic CIUS profile.

→ Download sample invoice (Peppol BIS 3.0)

Full schema documentation: Peppol BIS Billing UBL schema

Processing flow

1. The invoice is validated against the appropriate UBL schema (Peppol BIS Billing or domestic CIUS profile).

2. If validation fails, a detailed validation report is returned (422).

3. If validation succeeds and validateonly=false, the invoice is forwarded to the Peppol network.

4. If validation succeeds and validateonly=true, only the validation result is returned — the invoice is not transmitted.

Example requests

Full processing (validate and send)

curl -X POST \
  "https://connect-data-network.lobster-cloud.com/dw/request/v1/einvoice" \
  -u "username:password" \
  -H "Content-Type: application/xml" \
  -d @invoice.xml

Validation only (no transmission)

curl -X POST \
  "https://connect-data-network.lobster-cloud.com/dw/request/v1/einvoice?validateonly=true" \
  -u "username:password" \
  -H "Content-Type: application/xml" \
  -d @invoice.xml

Response codes

Response structure: successful validation

Returned when the invoice passes validation (200).

Example

{
  "status": "ok",
  "message": "Invoice is valid.",
  "transactionId": "30ac9744-0676-4376-baf3-2b1d5efffa0e",
  "validationResponse": {
    "validatorinfo": "Prüftool-Konfiguration Peppol BIS - Peppol Billing BIS 3 - UBL Invoice",
    "description": "Validierung von UBL Invoice version 2.1",
    "schema": "UBL",
    "validationTime": "2025-07-23T10:40:11+02:00",
    "validationSummary": {
      "schemaValidationErrors": false,
      "validationErrors": false,
      "validationWarnings": false,
      "isValid": true
    },
    "report": [
      {
        "id": "-",
        "text": "No errors found."
      }
    ]
  }
}

Response structure: validation error

Returned when the invoice fails validation (422). Contains a detailed report listing all rule violations with their EN 16931 / Peppol BIS rule identifiers.

Example

{
  "status": "nok",
  "message": "Invoice is invalid.",
  "transactionId": "e0232fd4-8012-432b-b981-175854149920",
  "validationResponse": {
    "validatorinfo": "Prüftool-Konfiguration Peppol BIS - Peppol Billing BIS 3 - UBL Invoice",
    "description": "Validierung von UBL Invoice version 2.1",
    "schema": "UBL",
    "validationTime": "2025-07-23T10:38:13+02:00",
    "validationSummary": {
      "schemaValidationErrors": false,
      "validationErrors": true,
      "validationWarnings": false,
      "isValid": false
    },
    "report": [
      {
        "id": "BR-CO-14",
        "type": "validationError",
        "flag": "fatal",
        "location": "/*:Invoice[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'][1]/*:TaxTotal[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]",
        "text": "[BR-CO-14]-Invoice total VAT amount (BT-110) = Σ VAT category tax amount (BT-117).",
        "ruleset": "EN16931  model bound to UBL",
        "rule": "(xs:decimal(child::cbc:TaxAmount)= round((sum(cac:TaxSubtotal/xs:decimal(cbc:TaxAmount)) * 10 * 10)) div 100) or not(cac:TaxSubtotal)"
      },
      {
        "id": "BR-CO-17",
        "type": "validationError",
        "flag": "fatal",
        "location": "/*:Invoice[...][1]/*:TaxTotal[...][1]/*:TaxSubtotal[...][1]",
        "text": "[BR-CO-17]-VAT category tax amount (BT-117) = VAT category taxable amount (BT-116) x (VAT category rate (BT-119) / 100), rounded to two decimals.",
        "ruleset": "EN16931  model bound to UBL",
        "rule": "..."
      },
      {
        "id": "BR-S-09",
        "type": "validationError",
        "flag": "fatal",
        "location": "/*:Invoice[...][1]/*:TaxTotal[...][1]/*:TaxSubtotal[...][1]/*:TaxCategory[...][1]",
        "text": "[BR-S-09]-The VAT category tax amount (BT-117) in a VAT breakdown (BG-23) where VAT category code (BT-118) is \"Standard rated\" shall equal the VAT category taxable amount (BT-116) multiplied by the VAT category rate (BT-119).",
        "ruleset": "EN16931  model bound to UBL",
        "rule": "..."
      }
    ]
  }
}

Response structure: general error

Returned for technical errors (400, 500).

Example

{
  "status": "error",
  "message": "Malformatted payload.",
  "transactionId": "b9f8543c-4861-4939-a878-13a341556f92"
}

Validation response details

ValidationResponse

ValidationSummary

ValidationReportItem

Schema reference endpoints

The connector provides dedicated GET endpoints for accessing the JSON schema definition of each data model used. Utilize these endpoints for programmatic schema access, code generation, or integration testing.

All schema endpoints require the same HTTP Basic Authentication credentials as the submission endpoint and return application/json responses.

Example request

curl -X GET \
  "https://connect-data-network.lobster-cloud.com/schemas/validation-success-response" \
  -u "username:password" \
  -H "Accept: application/json"

Replace the path with any endpoint from the table above to retrieve the corresponding schema. The response contains the full JSON schema definition for that data model.

Delivery notifications after submission

After a valid invoice is forwarded to the Peppol network, a Message Delivery Notification (MDN) confirms successful delivery to the receiving Access Point.

If the intended recipient is unreachable through Peppol, perhaps due to their lack of registration as a Peppol participant, the system will automatically initiate a fallback email delivery to the address indicated in the UBL document.

The invoice sender receives these status notifications through one of the following channels:

• One or more configured email addresses

• An HTTP callback endpoint

If an endpoint is already configured for receiving inbound invoices, it can be reused for status callbacks.

Note

Callback configuration is performed by the Lobster Onboarding team. Coordinate all technical details with your Customer Success Manager or designated technical contact.

Callback response structure (AcknowledgementResponse)

Example: successful Peppol delivery

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "delivered",
  "peppolRecipient": "0192:123456789",
  "fallbackEmail": null,
  "message": "Invoice successfully delivered via Peppol",
  "timestamp": "2025-08-11T14:32:00Z"
}

Example: fallback email delivery

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "fallback_email_sent",
  "peppolRecipient": "0192:123456789",
  "fallbackEmail": "recipient@example.com",
  "message": "Peppol delivery failed, invoice sent via fallback email",
  "timestamp": "2025-08-11T14:32:00Z"
}

Example: delivery error

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "error",
  "peppolRecipient": "0192:123456789",
  "fallbackEmail": null,
  "message": "Delivery failed. Recipient not reachable via Peppol and no fallback email available.",
  "timestamp": "2025-08-11T14:32:00Z"
}

Troubleshooting

Further reading

• Peppol BIS Billing 3.0 — full specification

• Sample invoice file (Peppol BIS 3.0 UBL Invoice)

• UBL Invoice syntax binding — element reference

• Peppol Directory — look up participant registrations